Approach 2: Customize the existing CMS provided with Host On-Demand
YoucancreatecustomNetwork SecurityandHCMplug-instocustomize the existingCMS. TheCMSreliesontheseplug-ins toprovidetheuser’snetworkID and hostcredentials.The CMSinteracts withtheseplug-insvia thefollowingthree Java interfaces:
v com.ibm.eNetwork.security.SSO.CMS.CMInterface v com.ibm.eNetwork.security.sso.CMRequest v com.ibm.eNetwork.security.sso.CMResponse
com.ibm.eNetwork.security.SSO.CMS.CMInterface
The CMInterfaceinterface containsthefollowingmethods:
public int Init(Properties p, String id)
Thismethodisusedtoinitializetheplug-in.Anyconfigurationparameters neededtointializetheplug-inwillbepassed inwiththepropertiesobject parameter.Theparametersarespecifiedintheservlet’sweb.xmlfile.The idparameteristhesymbolicnameoftheplug-inspecifiedintheCMS configurationportionoftheweb.xmlfile.Thisvalue maybeusedto qualifytheinstanceoftheplug-inintheeventmultipleinstancesofthe plug-inarerunning.
public void Destroy()
ThismethodiscalledwhenCMSisshutting down.
public CMResponse CMSGetUserCredentials(CMRequest req)
ThismethodiscalledbytheCMSwhenithasselectedtheplug-into respond toarequest.Iftheplug-inisanetworksecuritytype,it is expectedthattheplug-inwillreturntheuser’snetworkuserid.Ifthe plug-inisahostuser credentialtype,then thismethodwillneedtoreturn theuser’shostcredentials.
The followingmethodsareneededforplug-inidentificationandselection.
public String getName();
Thismethodreturnsastringthatidentifestheplug-in.
public String getDescription();
Thismethodreturnsastringthatcontainsinformationthatdescribesthe purposeandfunction oftheplug-in.
public String getAuthor();
Thismethodisneededtoidentifytheoriginatingcompanyorpersonof theplug-in.
public String[] getParameters();
Thismethodreturnsastringarraycontainingtheparametertokensthat maybe usedtoconfigurethis plug-in.Thesetokensare thekeys specified intheinitialization(INIT)parameterssection oftheweb.xmlfileusedto definetheCMSservlet.Ifnotokensareneededforconfiguration, the method mayreturnnull.
public Properties getParameterInfo(String strParm);
Givena parametertoken,thismethod returnsa propertiesobjectwiththe listofpropertiesforthegivenparameter.Thecurrentlistofpossible propertiesareasfollows:
v cmiDefaultValue: Thispropertycontainsthedefaultvalue forthe specified parameter.
v cmiEncrypted: Thispropertydeterminesif theparametermustbe encrypted(trueorfalse).
v cmiRequired:Thispropertyidentifieswhetherornota parameteris requiredforinitializationoftheplug-in.
com.ibm.eNetwork.security.sso.CMRequest
TheCMRequestobjectisusedbyCMStoencapsulate allnecessaryparametersfor a plug-inrequest.TheCMRequestinterfacecontainsthefollowingmembersand methods:
Members:
v ID(HostIDorNetworkID) v HostApplicationID
v HostDestinationAddress v AuthenticationType
v HTTPServletrequestobject
Methods
public CMRequest()
public CMRequest(String id, String applID, String hostAddr, int authType, HttpServletRequest httpRequest)
public String getID()
public void setID(String id) public String getHostApplID()
public void setHostApplID(String applID) public String getHostDestination()
public void setHostDestination(String hostAddr) public int getAuthType()
public void setAuthType(int authType)
public HttpServletRequest getHttpRequestObject()
public void setHttpRequestObject(HttpServletRequest httpRequest) public String toString()
com.ibm.eNetwork.security.sso.CMResponse
TheCMResponseobjectencapulatesallrelevantinformationneededbytheCMS fortherequestmadeofaplug-in. TheCMResponseinterfacecontainsthe followingmembers andmethods:
Members:
v StatusCode
v ID(HostIDorNetworkID)
v UserCredentials(PasswordorPassticket)
Methods:
public CMResponse()
public CMResponse(Object id, Object password, int status) public int getStatus()
public void setStatus(int status) public Object getID()
public String getIDasString() public void setID(Object id) public Object getPassword()
public String getPasswordasString() public void setPassword(Object password) public String toString()
Writing your own plug-ins
The NetworkSecurityandHCM plug-insareJavaclassesthatimplementthe CMInterfaceinterface.TheCMSmakescalls toyourplug-insviatheAPIs described earlier.
NetworkSecurityplug-in:HostOn-DemandprovidestwoNetwork Security plug-ins,oneforTivoliAccessManagerandoneforNetegrity Siteminder.Ifyou decidenottouseeither ofthese,youmaycreateyour ownplug-in.
The primaryfunctionoftheNetworkSecurity plug-inistoacquiretheuser’s networkID,whichmaybe gleanedfromtheHTTPheaderoftheincomingHTTP requestobject.Thedetailsofhow toacquirethenetworkIDisspecific toyour networksecurityapplication.Refertoyour networksecuritydocumentationfor more information.
HCM plug-in:HostOn-DemandprovidesthreeHCMplug-ins,twoforDCASand onefor Vault.Ifyoudecidenottouseeitherofthese,youmaycreateyourown plug-in. ForsampleHCMplug-incode,refertoAppendixD, “SampleHCM plug-in,”onpage123.
The primaryfunctionoftheHCMplug-inistotaketheuser’snetworkIDor user’scertificate (andperhapstheapplication ID)and obtaintheappropriatehost credentials.InWebExpressLogon’simplementation, users’networkIDsare mappedtotheirhost IDsbywayof aJDBC-accessibledatabase.However,you maywishtodo thisbyanothermeans,suchasLDAP.Forthis reason,youmay wanttowriteyourown HCMplug-in.InourDCAS/JDBCplug-in, weautomate 3270application loginsbyassociatingusers’networkIDstotheirhostIDs.Then, thehostIDsand applicationIDsareusedtoobtainaRACF-generatedpassticket.
Thispassticketisthen usedtosigntheuserontothehost.Inyour environment, youmaynotwanttousetheJDBCassociationaspectofour plug-in.Forthis reason, wehaveprovideda DCASAPIthatyoucanusetodevelop yourown custom plug-ins.ThisAPIprovides accesstoRACF-generatedpasstickets.
TheDCASAPIobject(DCASClient)encapsulatesthePassticketrequests:
TheDCASAPIclientcontains thefollowingmembers:
Members:
v PortNumber v KeyringFileName v KeyringPassword
v UseWellKnownTrustedCAs v ServerAuthentication v TraceLevel
v TraceLogFileName
TheDCASAPIclientcontains thefollowingmethods:
Methods:
Public DCASClient()
Thisconstructorshouldbeusedifyouwanttousethedefaulttracelevel and logfilenamewhentheobjectiscreated.
Public DCASClient(int traceLevel, String logFile)
v traceLevel -Tracelevel(0=None,1=Minimum,2=Normal and 3=Maximum)
v logFile -Trace logfilename.Itshouldinclude thefullpathname.
Thisconstructorshouldbeusedifyouwanttospecifya tracelevelandlog filenamewhentheobjectiscreated.
Public int Init (String hostAddress, int hostPort, String trustStoreName, String trustStorePassword, String trustStoreType)
v hostAddress-DCASserver’sIPaddress
v hostPort -DCASserver’s portnumber.Ifnotspecified,thedefaultport number of8990willbe used.
v trustStoreName-ThenameofthetruststoretobeusedbyJSSEto connecttoDCAS. Itshouldincludethefullpathname. Settonullif usingdefaulttruststoreorWellKnownTrustedCAs.p12.
v trustStorePassword -Thepasswordof theabovetruststore.Settonullif usingdefaulttruststoreorWellKnownTrustedCAs.p12.
v trustStoreType--Thetype oftheabovetruststore.Validvaluesare DCASClient.TRUSTSTORE_TYPE_PKCS12(pkcs12),
DCASClient.TRUSTSTORE_TYPE_JCEKS(jceks),and
DCASClient.TRUSTSTORE_TYPE_JKS (jks).Settonull ifusingdefault truststore orWellKnownTrustedCAs.p12.
Thismethodshouldbecalledafter creatingtheDCASClientobject.The parametersarestoredin theobject, andtheydonotchangeforthelifeof theobject.Thetruststore nameshouldincludethefullpathname.The truststoremust containtheDCASclientcertificate andDCASserver certificate, unlessthedefaulttruststoreorWellKnownTrustedCAs.p12will be used.Thetruststorepasswordshouldhavebeen encryptedusingthe encryptpasswordtool.Itwillbe decryptedbeforebeingstored inthe object. Thevalidreturn codesare describedintheSSOConstantsobject.
Return0onsuccess, non-zerootherwise.
public void setUseDefaultTrustStore(boolean def) public void setNoFIPS(boolean nof)
Public int Init(String dcasAddr, int dcasPort, String keyringFileName, String keyringPassword)
v dcasAddr-DCASserver’sIPaddress
v dcasPort-DCASserver’sportnumber.Ifnotspecified,thedefault port numberof8990willbe used.
v keyringFileName-ThenameoftheSSLkeyringdatabasefile.Itshould includethefullpathname.
v keyringPassword-Thepasswordoftheabovekeyringdatabase.
Thismethodshouldbecalledafter creatingtheDCASClientobject.The parametersarestored intheobject, andtheydonotchangeforthelifeof theobject.The p12filenameshouldincludethefullpathname. Itmust containtheDCASclientcertificateand theDCASservercertificate.If WellKnownTrustedCAs.p12orthedefaulttruststoreisbeingusedforthese certificates,setp12FileName andp12Passwordtonull.Thep12password shouldhavebeenencryptedusingtheencryptpasswordtool.Itwillbe decrypted beforebeingstoredintheobject.Thevalidreturn codesare describedin theSSOConstantsobject.Ifa truststoreofatype otherthan p12isbeingused,usetheInit(hostAddress, hostPort,trustStoreName, trustStorePassword,trustStoreTypemethod instead.
Public void setWellKnownTrustedCAs(boolean wellKnownCAs) public void setWellKnownTrustedCAsPassword(String password)
Thismethodisusedforsettingthevaluespecified bytheaboveparameter.
Public void setServerAuthentication(boolean serverAuth) Public void setTraceLevel(int level)
Public void setLogFile(string fileName)
Public CMResponse getPassticket(String hostUserID, String hostApplID, String hostAddr, long timeout)
v hostUserID-UserIDforwhichthepassticketisbeingrequested.
v hostApplID-ApplicationIDforwhichthepassticketisbeingrequested.
v hostAddr-TheDCASserver’s address.
v timeout-ThetimeavailablefortheDCASprotocoltoreturna passticket.Itisspecifiedinmilliseconds.
Thismethodshouldbecalledafter creatingandinitializingthe DCASClientobjecttoobtainapassticketfromtheDCASserver.The passticket andtheuserIDarereturnedinaCMResponseobject.Thecaller shouldcheck thestatusfieldoftheCMResponseobjecttoseeifthecall was successfulornot.Ifthecallwassuccessful,thestatusfieldwillbeset toSSO_CMR_SUCCESS(0).Thevalidvaluesforthestatusfieldare specifiedin Table9 onpage93.AnSSLclient authenticatedconnectionis established withtheDCASserver,andit isreused forallsubsequent passticket requests.
Public CMResponse getPassticket(byte certificate[], String hostApplID, String hostAddr, long timeout)
v certificate-UserCertificateforwhichthepassticket isbeingrequested.
v hostApplID-ApplicationIDforwhichthepassticketisbeingrequested.
v hostAddr-TheDCASserver’s address.
v timeout-ThetimeavailablefortheDCASprotocoltoreturna passticket. Itisspecifiedinmilliseconds.
Thismethodshouldbecalledafter creatingandinitializingthe DCASClientobjecttoobtainapassticketfromtheDCASserver.The passticket andtheuserIDarereturnedinaCMResponseobject.Thecaller shouldcheck thestatusfieldoftheCMResponseobjecttoseeifthecall was successfulor not.Ifthecallwassuccessful,thestatusfieldwillbeset toSSO_CMR_SUCCESS(0).Thevalidvaluesforthestatusfieldare specifiedinTable9 onpage93.AnSSLclientauthenticatedconnectionis established withtheDCASserver,anditisreused forallsubsequent passticket requests.
Public void Destroy()
ThismethodclosestheDCASconnection.