Web Express Logon Reference

(1)

IBM

WebSphere

Host

On-Demand

Version

10 Web

Express

Logon

Reference

(2)

(3)

IBM

WebSphere

Host

On-Demand

Version

10 Web

Express

Logon

Reference

(4)

Note

Beforeusingthisinformationandtheproductitsupports,readtheinformationinAppendixG,“Notices,”onpage135.

ThirdEdition(June2006)

ThiseditionappliestoVersion10ofIBM®

WebSphereHostOn-Demand(programnumber5724-I20)andtoall subsequentreleasesandmodificationsuntilotherwiseindicatedinneweditions.

©CopyrightInternationalBusinessMachinesCorporation2004,2006.Allrightsreserved.

(5)

Part

1. About

this

book

.

. 1

Chapter

1. Description

of

book

.

. 3

Conventionsusedinthisbook . . . 3

Part

2. Overview

of

Web

Express

Logon

.

. 5

Chapter

2. Introduction

.

. 7

WhatisthedifferencebetweenWebExpressLogon, CertificateExpressLogonandReuseActive Credentials? . . . 7

UsingclientcertificateswithWebExpressLogon 8 CanImigratefromCertificateExpressLogonto Certificate-basedWebExpressLogon? . . . 8

HowdoesWebExpressLogonwork? . . . 9

Macro-basedautomation . . . 9

Connection-basedautomation . . . 14

Part

3. Planning

.

. 19

Chapter

3. Planning

for

implementation

21

Step1:Chooseyourstyleoflogonautomation. . . 21

Step2:Identifyareasofcredentialchallenges. . . . 21

Step3:Takeaninventoryofyourenvironment. . . 21

Macro-basedautomation . . . 22

Connection-basedautomation . . . 22

Step4:Developyourdeploymentstrategy. . . . . 22

Step5:EstablishanHCMdatabase. . . . 23

Part

4. Implementing

macro-based

automation

.

. 25

Chapter

4. Configuring

macro-based

automation

in

a

z/OS

and

DCAS

environment

.

. 27

Step1:ConfiguretheCredentialMapperServlet (CMS). . . . 27

A.LocatetheWARfilesontheHostOn-Demand Version9CD . . . 28

B.BecomefamiliarwiththeINITparametersin theweb.xmlfile.. . . 28

C.EdittheCMS-relatedparameters. . . . 29

D.AddoptionalCMS-relateddebugging parameters. . . . 30

E.AddtherequiredDCASclientparametersfor theCMPIDCASPlugin. . . . 31

F.AddtheoptionalDCASclientparameters(if desired). . . . 35

Step2:SavetheWARfileanddeploytheCMS. . . 37

Step3:CreatetheSSLkeydatabase. . . . 37

Step4:AddtheWebserver’scertificatetotheJava keyring(Java2clientsonly).. . . 38

Step5:BegincreatingyourHTMLfile. . . . 39

Step6:ConfiguretheHostOn-Demandsessionto useWebExpressLogon. . . . 41

Step7:RecordtheWebExpressLogonmacro.. . . 42

Step8:FinishcreatingyourHTMLfile. . . . 43

Chapter

5. Configuring

macro-based

automation

in

a

vault-style

environment

.

. 47

E.AddtherequiredVaultparametersforthe CMPIVaultPlugin. . . . 51

F.AddtheoptionalVaultparameters(ifdesired). 53 Step2:SavetheWARfileanddeploytheCMS. . . 54

Chapter

6. Configuring

macro-based

automation

in

a

Portal

Server

environment

.

. 61

Step1:BegincreatingyourHostOn-Demand portlet. . . . 61

Step4:FinishcreatingyourHostOn-Demand portlet. . . . 65

Step5:Usingacustomportlettomanageuser credentials. . . 68

Part

5. Implementing

connection-based

automation

.

. 69

Chapter

7. Configuring

connection-based

automation

in

an

i5/OS

or

OS/400

and

Kerberos

environment

.

. 71

Step1:UsetheDeploymentWizardtocreateyour HTMLfile. . . . 72

(6)

Step2:ConfigureyourHostOn-Demandsessionto

useWebExpressLogon. . . . 72

Chapter

8. Configuring

connection-based

automation

in

an

FTP

environment

.

. 75

E.AddtherequiredVaultparametersforthe CMPIVaultPlugin. . . . 79

F.AddtheoptionalVaultparameters(ifdesired). 81 Step2:SavetheWARfileanddeploytheCMS. . . 82

Part

6. API

programming

guide

.

. 89

Chapter

9. Customizing

Web

Express

Logon

.

. 91

Approach1:ReplacetheentireCMSwithyourown customversionoftheservlet . . . 91

HTTPrequestparameters. . . 92

XMLdataresponseobject . . . 92

Approach2:CustomizetheexistingCMSprovided withHostOn-Demand . . . 94

com.ibm.eNetwork.security.SSO.CMS.CMInterface 94 com.ibm.eNetwork.security.sso.CMRequest . . . 95

com.ibm.eNetwork.security.sso.CMResponse . . 95

Writingyourownplug-ins . . . 96

Part

7. Troubleshooting

error

messages

.

. 101

Chapter

10. Troubleshooting

Web

Express

Logon

.

. 103

WebExpressLogonclient-sidemessages . . . . 104

WebExpressLogonserver-sidemessages . . . . 107

DCASerrormessages . . . 109

Appendix

A. Recording

the

Web

Express

Logon

macro

.

. 113

Appendix

B. Web

Express

Logon

using

the

Configuration

server-based

model

.

. 119

Appendix

C. Password

encryption

tool

121

Windowsplatforms . . . 121

Unixplatforms . . . 121

Appendix

D. Sample

HCM

plug-in

.

. 123

WritetheHCMplug-in. . . . 123

Updatetheweb.xmlfile. . . . 126

Appendix

E. Glossary

of

terms

.

. 129

authenticationtype . . . 129

clientcertificate. . . 129

connection-basedautomation . . . 129

credentialchallenges . . . 129

CredentialMapperServlet(CMS). . . 129

DigitalCertificateAccessServer(DCAS) . . . . 129

EnterpriseIdentityMapping(EIM) . . . 130

fullclasspathname . . . 130

HostCredentialMapper(HCM) . . . 130

hostID . . . 130

hostmask . . . 130

Kerberos . . . 130

macro-basedautomation. . . 131

networkID . . . 131

NetworkSecurityplug-in . . . 131

PortalServerCredentialVault . . . 131

ResourceAccessControlFacility(RACF) . . . . 131

Appendix

F. Sources

for

more

information

.

. 133

Appendix

G. Notices

.

. 135

(7)

(8)

(9)

Chapter

1. Description

of

book

Thisbookiswrittenforadministratorswho areinterestedinunderstanding, planningfor,implementing,andtroubleshootingWebExpress Logon.Itprovides step-by-step instructionsforconfiguringHostOn-DemandforWebExpressLogon. For detailsaboutconfiguringotherapplicationssuchasyournetworksecurity application, refertotheWebExpress LogonforHostOn-Demandwhitepaper, locatedat ftp://ftp.software.ibm.com/software/network/hostondemand/library/ whitepapers/wel2.pdf.

Thisbookcontainsthefollowingparts: v Overviewof WebExpressLogon v Planning

v Implementingmacro-basedautomation v Implementingconnection-basedautomation v APIprogramming guide

v Troubleshootingerrormessages v Appendices

– RecordingtheWebExpress Logonmacro

– WebExpress LogonusingtheConfigurationserver-basedmodel – Passwordencryptiontool

– Glossary ofterms

– Sourcesformoreinformation – Notices

– Trademarks

Conventions

used

in

this

book

Thefollowingtypographicconventionsare usedinHostOn-DemandWebExpress Logon Reference:

Table1.Conventionsusedinthisbook

Convention Meaning

Monospace Indicatestextyoumustenteratacommandpromptandvaluesyoumustuseliterally, suchascommands,functions,andresourcedefinitionattributesandtheirvalues. Monospacealsoindicatesscreentextandcodeexamples.

Italics Indicatesvariablevaluesyoumustprovide(forexample,yousupplythenameofafile forfile_name).Italicsalsoindicatesemphasisandthetitlesofbooks.

(10)

Table1.Conventionsusedinthisbook (continued)

Convention Meaning

> Whenusedtodescribeamenu,showsaseriesofmenuselections.Forexample,“Click File>New”means“FromtheFilemenu,clicktheNewcommand.”

Whenusedtodescribeatreeview,showsaseriesoffolderorobjectexpansions.For example,“ExpandHODConfigServlet>Sysplexes>Plex1>J2EEServers>

BBOARS2”means:

1. ExpandtheHODConfigServletfolder 2. ExpandtheSysplexesfolder

3. ExpandthePlex1folder 4. ExpandtheJ2EEServersfolder 5. ExpandtheBBOARS2folder

Thisgraphicisusedtohighlightnotestothereader. Thisgraphicisusedtohighlighttipsforthereader.

ThisgraphicreferstoinformationthatisspecifictoCertificate-basedWeb ExpressLogon.

(11)

(12)

(13)

Chapter

2. Introduction

Intheageofe-businessondemand,findingwaystosimplifytheuserexperience whilemaintainingcompanysecuritycanbea realchallenge.For example,many companieswould liketodecreasethenumber ofIDsandpasswordsthattheir usershavetomanage,buttheyalso realizethatallowing userstoaccesscompany resources withoutproperidentificationriskscompanysecurity.

Several productsexistinthemarketplacethatclaimtosolve themultiplelogon issue andmaintainsecurityatthesametime.However, theseproductsgenerally apply toWeb-basedapplicationsonlyand donotaddresslogonprocessesfor legacy hostsandhost-basedapplications.Inotherwords,inhost-based

applicationsthatdonotuseHTMLorXML,automatingthelogonprocessrequires beingable tointerceptthetelnetdatastream.Becauseofitsuniquepositionto workwith individualscreensandtheabilitytosubstitutefields inthedatastream, HostOn-Demandisanidealcandidatetoaddress multiplelogonissuesin

companieswhere usersaccesshostsystemsviabrowser-basedterminalemulation. WebExpress Logonworks inconjunctionwithyour company’snetworksecurity application tomaintaincompanysecuritywhileallowinguserstologontohost systemswithouthavingtore-entertheiruser IDsandpasswords.Ithasseveral benefits,includingthefollowing:

v Easeofuse:Users canlogontotheirnetworksecurityapplicationandaccess hostapplicationswithouthavingtore-entertheirIDsandpasswords.

v Reducedpassword-relatedsupport calls:Users arelesslikelytocallthe companysupportlinebecauseofforgottenormisplacedpasswords.

v Increasedproductivity:Userscanlogononlyonceinanenvironmentthathas multiplemethodologiesfordefininguserIDs,passwords,andauthentications.

What

is

the

difference

between

Web

Express

Logon,

Certificate

Express

Logon

and

Reuse

Active

Credentials?

HostOn-DemandoffersthreetypesofExpressLogon: v WebExpressLogon

v CertificateExpressLogon v ReuseActiveCredentials

WebExpress Logonhasbeenavailable sinceHostOn-DemandVersion8, Certificate ExpressLogon,formerlyknown asExpressLogonFeature(ELF),has been availablesinceHostOn-DemandVersion5.Althoughthenamehaschanged, Certificate ExpressLogonfunctionsthesameasELFdidin earlierversionsand requiresthesameconfiguration. ReuseActiveCredentialsisa featureavailable in HostOn-DemandVersion10.0.

ReuseActiveCredentialsprovidesautomatedauthentication onallemulation platforms.ItisnotascomprehensiveasWebExpress Logonbutdoesnotrequire anyspecialnetworkconfiguration.Ifa newconnectionismadetoahost anda user hasalreadyauthenticatedto thathost somehow,thosecredentialsare applied tothenew connection.Thecredentialsare maintainedforaslongasHost

(14)

On-DemandisrunningintheJVM.ThecredentialsareonlystoredinJavamemory and oncetheJVMclosestheywillhavetobere-enteredwhenHostOn-Demandis restarted.

AlthoughallthreetypesofExpressLogonallowuserstologontoa hostsystem withouthavingtoenterauser IDand password,theyhavedifferentrequirements for sessiontype,clientcertificates,andSSLconfiguration. CertificateExpressLogon works exclusivelywith3270sessiontypesandrequiresclient-sidecertificatesand an SSLconnectiontoa TN3270server.WebExpressLogonandReuseActive Credentialsoffera widevarietyof stylesthatfunctionwith allHostOn-Demand session types(notjust3270emulation).CertificateExpress Logonrequiresamacro tologontothehostapplicationand thendistribute thatmacro totheclients. Web Express Logonand ReuseActiveCredentialsmayormaynotrequireamacro, dependingonyourenvironment.

Using

client

certificates

with

Web

Express

Logon

DCASandz/OS environmentsthatuseclientcertificatesfor userauthentication are nolongerlimited toCertificateExpressLogon. Startingwith HostOn-Demand V9,WebExpress Logonoffers atypeof logonautomation thatusesclient-side certificatesknown asCertificate-basedWebExpress Logon.Althoughboth Certificate ExpressLogonandCertificate-basedWebExpressLogonwork exclusivelywith 3270hostsessionsandrequirea DCASserver,theclient certificatesinthetwomodelsareuseddifferentlyand theautomation process requiresdifferentcomponents.WithCertificateExpress Logon,clientcertificatesare usedtoauthenticate userstoan ExpressLogon-enabledTN3270server,andthe HostOn-Demandclientanda TN3270serverare configuredtoautomatethelogin process. WithCertificate-basedWebExpress Logon,however,clientcertificatesare usedtoauthenticate userstoa secureWebserver,and aHostCredentialMapper plug-inand amacroareusedtoautomatetheloginprocess.

Certificate-basedWebExpress Logonisamoreflexible solutionthanCertificate Express Logonbecauseit providesmoreimplementationoptions.Formore informationaboutCertificate-basedWebExpressLogon, refertoChapter4, “Configuringmacro-basedautomationina z/OSandDCASenvironment,”on page27.

Can

I

migrate

from

Certificate

Express

Logon

to

Certificate-based

Web

Express

Logon?

HostOn-DemandV9offers anewDCASELF plug-inthatallows usersof Certificate ExpressLogontomigratetothemorescalablecertificate-basedWeb Express Logonarchitecture.Thisplug-inallowsyoutomoveSSLclient

authentication fromtheTN3270servertoa secureWebserver.For specificdetails abouthow tomigratefromCertificateExpress Logontocertificate-basedWeb Express Logon,refertotheWebExpressLogonwhitepaper,locatedat ftp://ftp.software.ibm.com/software/network/

hostondemand/library/whitepapers/wel2.pdf .

(15)

How

does

Web

Express

Logon

work?

Theoverallgoal ofWebExpressLogonistoprovideanautomated wayforusers tologontohosts andhost-basedapplicationswithouthavingtoprovidean additionalIDandpassword. Inorder toaccommodatethewide rangeof

supportedcomputingenvironments, WebExpressLogonoffers twostyles oflogon automation:

v macro-basedautomation v connection-basedautomation

Thestyle oflogonautomation thatbestsuitsyour needsdependsonyour

environment,includingyourhosttype, sessiontype,andyour currentmethodfor authenticatingusers.Ifthehostdoesnotallowtheclienttosupplytheneeded credentialsat thetimetheconnectionisestablished,forexample,if theclient must authenticate tothehostafterthehostconnectionisestablished,macro-based automation istheappropriatestyle.Inthismodel,thehostmustsenda login screentoauthenticatetheclient.Themacroautomatestheloginscreen,populates thescreen’scredentialfieldswith theappropriateuser information,andthen transmits thisinformationtothehostforauthentication.However,if yourhost allows theclienttosupplytheneededhostcredentialsatthetimethehost

connection isestablished,forexample,usingKerberosauthentication orFTPlogin, connection-basedautomationistheappropriatestyle.

Thefollowingsectionsprovidemoredetailsaboutmacro-andconnection-based automation, includinghigh-leveloverviewsofsomeexampleenvironments supportedbyWebExpressLogon.Theseexamplesare discussedinmoredetail throughouttheremainderof thisdocument.

Macro-based

automation

Asthenameimplies,macro-basedautomationrequiresamacrotoautomate the loginprocess.Themacro isresponsibleforobtainingtheuser’shostcredentials and passingthatinformationtothehostforauthentication.Thehostcredentials are basedononeofthefollowinguseridentitytypes:

v localsystemID:theuser’slocaloperatingsystemID.Web ExpressLogon currentlysupportsMicrosoftActiveDirectory(Windows Domain).Host On-Demandwillusenativecode toobtaina user’slocalWindowsdomainID whenUserIdentityType isset to″LocalSystemID″intheExpressLogon sessionpropertiespanel.Tousethisoption,the″WindowsDomain″HTML parametermustbe settocontainthenameoftheWindows Domain(s)towhich theendusersbelong.Multipledomains mustbeseparatedbycommas.

v networkID: theuser’snetworksecurityapplicationIDorclientcertificate.Web ExpressLogoncurrentlysupportsIBMTivoliAccessManager andNetegrity Siteminder.

v PortalID: theuser’sPortalServer ID.WebExpressLogoncurrentlysupports PortalServer, acomponentofIBMWebSpherePortal.

Useridentitytype isa configurableoptioninsession properties.

IfyouplanforHostOn-Demandtoacquiretheuser’scredentialsfroma differentapplicationthantheonessupportedbyWebExpressLogon,youwill needtocreateyourownplug-in.Formoreinformation,refertoChapter9, “CustomizingWebExpressLogon,”onpage91.

(16)

Macro-basedautomationreliesonthefollowingfourkeycomponentsandthe interactionsthattakeplaceamongthem.Not allenvironmentsthatuse macro-basedautomationuseallfourcomponents:

v loginmacro

v CredentialMapperServlet(CMS) v NetworkSecurityplug-in

v HostCredentialMapper(HCM)database

The loginmacro automatestheend-to-endprocessoftheclientsendingtheHTTPS requesttotheCMS,theCMSrespondingwiththeneededcredentials,and the macro insertingtheuser’scredentialsintheproperfieldstoallowauthenticated logon. Youmust recordtheloginmacrowhileyouareinanactivesession.It initiatesatthetimetheuser attemptstoaccessthehostsession,either automaticallyormanually(dependingonyourconfiguration).

The CMSissuppliedwith HostOn-Demandandmust bedeployed toa J2EE-compliantHTTPserver.Ata highlevel,theCMSisresponsiblefor

determiningtheclient’sidentityandreturningthehostcredentialstotheclientas an XMLdocument.

TheCMSisnotrequiredifusingthePortalCredentialVaultasyourHCM database.ThisisbecausetheHostOn-Demandportletisdesignedtoallowthe WebExpressLogonmacrotoacquiretheuser’scredentialsdirectlyfromPortal Server.

HostOn-DemandprovidestwoNetworkSecurityplug-ins,oneforeachofthetwo supportednetworksecurityapplications—IBMTivoliAccessManagerand

Netegrity Siteminder.Theprimaryfunction oftheNetworkSecurityplug-inisto acquiretheuser’snetworkID, whichmaybegleanedfromtheHTTPheaderofthe incoming HTTPrequestobject.

TheNetworkSecurityplug-indoesnotapplytoMicrosoftActiveDirectory (WindowsDomain),PortalServer,orCertificate-basedWebExpressLogon.For MicrosoftActiveDirectory,theWindowsloginIDisusedtoidentifytheuser. ForPortalServer,thePortalIDisusedtoidentifytheuser.For

Certificate-basedWebExpressLogon,theclientcertificateisusedtoidentify theuser.

The HCMdatabaseisaback-endrepositorythatmapsusers’networkIDstotheir host credentials.Thisrepositorycanbeoneofthefollowing:

v aJDBCdatabase suchasonecreatedwith IBMWebSphereDB2 v PortalServer CredentialVault

The DigitalCertificateAccessServer (DCAS)andVaultplug-insprovidedwith WebExpress Logonand HostOn-Demandportletsaredesigned toworkwith these repositories.Another possibilityfora repositoryisan LDAPdirectory. However, usingLDAPasyourHCMdatabaserequiresyoutowriteyour own plug-in. Formore information,refertoChapter9,“CustomizingWebExpress Logon,”onpage91.

The followingexamples showyouhowthekeycomponentsdiscussedabove interacttogether,beginningat thepointtheuser attemptstoopena Host

On-Demandsession andinitiatetheloginmacro.Ifthemacro isnotconfiguredto auto-start,theuserwillneedtostart itmanually.

(17)

Supported

environments

ThefollowingthreeWebExpressLogon-supportedenvironmentsusemacro-based automation:

v “z/OSand DCAShostauthentication”

v “z/OSwith vault-stylecredentialmapping”onpage13

v “AuthenticationviaPortalServer’sCredentialVaultService”onpage13

z/OSandDCAShostauthentication: Inaz/OSand DCASenvironment,Web Express Logonsupportstwodifferentmodels—one inwhichusersare identified via clientcertificates(calledCertificate-basedWebExpressLogon)and onein whichusersareidentified viaanetworksecurityapplication.Sinceboth ofthese models havetheirownrequirementsforuseridentification,theWebExpress Logonconfigurationstepsare differentforeachmodel.Inacertificate-based environment,youmustconfigureyour HTTPserveraswellasthebrowserand Java 2keystoreoneachHostOn-Demandclient.Ina non-certificate-based environment,youmustconfigureyour networksecurityapplicationand create your HCMdatabase.Bothmodelsrequire youtoconfiguretheDigitalCertificate AccessServer (DCAS).

Figure1and Figure2 onpage12alongwiththeaccompanyingstepsillustratehow Certificate-basedand non-Certificate-basedWebExpressLogonworkinaz/OS and DCASenvironment:

1. Theuser clicksalinktolaunchtheHostOn-Demanddesktop,whichsendsan HTTPrequesttotheWebserver.

2. Theserverrequestsa clientcertificatetoperform clientauthentication.The client certificatemustbe storedinthebrowser’skeyring.

3. Theuser sendstheclientcertificate totheserver.

4. TheWeb serverreturnstheHTTPSrequest,andtheHostOn-Demanddesktop displays.

5. Theuser launchesa hostsession. 6. Theloginmacro executes.

7. Themacro sendsan HTTPSrequesttotheCMStoobtainthehostcredentials.

Client Workstation Web Server Host System

6 Login Macro Secure HTTP Server Credential Mapper Servlet(CMS) DCASELF Host Credential Mapper (HCM) 11 8 TN3270 Host Application 4 3 1 2 7 12 DCAS RACF 9 10 5 N e t w o r k S e c u r i t y Application Server

(18)

8. The CMSpassestheapplicationIDtotheDCASELF HCMplug-in.

9. The DCASELFHCMretrievestheuser’scertificatefromtheWebapplication server.

10. The host(RACF)identifies theclient,checkstheclient’sauthorization, and returnsthepasstickettotheDCASELFHCM plug-in.

11. TheDCASELF HCMplug-inreturnsthehostIDandpassticketto theCMS. 12. The CMSreturnsthehostcredentialstotheclientasanXMLdocument.

1. The userclicksalinktolaunchtheHostOn-Demanddesktop,whichsendsan HTTPSrequestthroughthenetworksecurityapplication totheHTTPserver. 2. The WebserverreturnstheHTTPSrequest,andtheHostOn-Demanddesktop

displays.

3. The userlaunchesa hostsession. 4. The loginmacro executes.

5. The macrosendsan HTTPSrequesttotheCMStoobtainthehostcredentials. 6. The CMSretrievestheuser’snetworkIDfromtheNetworkSecurityplug-in. 7. The CMSpassesthenetworkIDandapplication IDtotheDCASHCM

plug-in.

8. Using thenetworkIDandapplication ID,theDCASHCM plug-incallsupon a database,suchasIBM DB2,tomaptheuser’shostID.

9. The DCASHCMplug-inpassestheuser’shost IDandapplication IDto Digital CertificateAccessServer (DCAS)andrequestsapassticket.

10. The host(RACF)identifies theclient,checkstheclient’sauthorization, and returnsthepasstickettotheDCASHCMplug-in.

11. TheDCASHCMplug-inreturnsthehost IDandpassticket totheCMS. 12. The CMSreturnsthehostcredentialstotheclientasanXMLdocument. The loginmacro automaticallyinsertstheuser’scredentialsinthelogonscreen fields withoutuser intervention.Nowtheuserisfullyauthenticatedand can proceedwith thesession.

Client Workstation Web Server Host System

1 5 3 2 13 6 4 Login Macro Web Application Server Credential Mapper Servlet(CMS) Network Security Plug-in DCAS Host Credential Mapper(HCM) 6 ₇ 8 9 10 RACF DCAS TN3270 Host Application N e t w o r k S e c u r i t y 11 Database (IBM DB2) 12

(19)

For moreinformation,refertoChapter4,“Configuringmacro-basedautomationin a z/OSandDCASenvironment,”onpage27.

z/OSwithvault-style credentialmapping: Inthis model,usersare authenticated ina vault-styleenvironment.Figure3illustratesthisenvironment:

1. Theuser clicksalinktolaunchtheHostOn-Demanddesktop,whichsendsan HTTPSrequestthroughthenetworksecurityapplication totheWebserver. 2. TheWeb serverreturnstheHTTPSrequestandtheHostOn-Demanddesktop

displays.

3. Theuser launchesa hostsession. 4. Theloginmacro executes.

5. Themacro sendsan HTTPSrequesttotheCMStoobtainthehostcredentials. 6. TheCMSretrievestheuser’snetworkIDfromtheNetworkSecurityplug-in. 7. TheCMSpassesthenetworkIDandapplicationIDtotheVaultHCMplug-in. 8. Using thenetworkIDandapplication ID,theVaultHCMplug-incallsupona

database,suchasIBMDB2,tomaptheuser’shostIDand password.

9. TheVault HCMplug-inpassestheuser’shostIDandpasswordtotheCMS. 10. TheCMSreturnsthehostcredentialsto theclientasanXMLdocument.

AuthenticationviaPortalServer’sCredentialVaultService: Inthismodel,users are authenticatedviaPortalServer,a componentofIBMWebSpherePortal. Figure4onpage14illustratesthis environment:

Client Workstation

4 Login Macro

Application Server

Web Server Host System

1 5 3 2 10 6 HTTP Server Credential Mapper Servlet(CMS) Network Security Plug-in Vault Host Credential Mapper(HCM) 6 7 ₉ 8 TN3270 Host Application N e t w o r k S e c u r i t y Database (IBM DB2)

(20)

1. Theuser logsontoIBMWebSpherePortaland choosesa portalpagethat includestheHostOn-Demandportlet.

2. TheHostOn-DemandportletinitiatestheCredentialVaultService.

3. TheCredentialVaultServiceretrievesall thecredentialsthatare accessibleto thePortaluser.

4. TheHostOn-Demandportletsendsthecredentialstotheclientworkstation anddisplays theHostOn-Demandapplet.

5. Theuser launchesa hostsession. 6. Theloginmacroexecutes.

7. TheloginmacroretrievesthecredentialsfromthedatareceivedfromtheHost On-Demandportletand performsthelogonoperation.

Macro-basedautomationhasbeensuccessfullytestedwith thefollowing applications:

v IBMTivoliAccessManagerfor e-businessVersions4.1and5.1 v MicrosoftActive Directory

v NetegritySiteminderVersion5.5

v IBMWebSpherePortalServer Version5.02

v WebSphereApplicationServer Version5.02,Version5.02Enterprise, and5.0.2.5 v IBMDB2Universal DatabaseVersion7

v z/OSV1R4withAPARPQ74457

Themacro-basedautomationversionofWebExpressLogoncanfunctionwith otherapplicationsthatarenotlistedhere.

Connection-based

automation

Unlikemacro-basedautomation,connection-basedautomation doesnotrequirea macro becausetheclient andthehostareabletoconnectwithouthavingto providetheuser withaloginscreen.

Client Workstation WebSphere Portal Host System

1 5 2 6 4 Login Macro Host On-Demand portlet Credential Vault Service 6 7 TN3270 Host Application 3

(21)

Supported

environments

ThefollowingtwoWebExpressLogon-supportedenvironmentsuse connection-basedautomation:

v “IBMi5/OSorOS/400hostwith Kerberospassticket authentication” v “FTPlogin” onpage16

IBMi5/OSorOS/400hostwithKerberospassticketauthentication: Currently, WebExpress Logonsupportsi5/OSand OS/400(V5R2andlater)telnet-negotiated environmentsthathaveKerberosauthentication enabled.Itdoesnotrequire the CMS, aloginmacro,aNetwork Securityplug-in,northeHCMdatabase.Instead,it extends theexistingsinglesign-oncapabilityofthei5/OSand OS/400operating systems.

Inorderforconnection-basedautomationtofunction inthisenvironment,you must havethefollowingprerequisites inplace:

v WindowsDomainController(MicrosoftActiveDirectory) v keydistribution center(KDC)

v Kerberosnetworkauthenticationenabled oneachtarget i5/OSorOS/400 system

v i5/OSorOS/400V5R2(5722-SS1)orlaterasthehostoperatingsystem v oneormoreofthefollowingclientoperatingsystems:

– Windows 2000Professionaland Server – Windows XPProfessional

– Windows Server2003

Youmust configureyouri5/OSorOS/400environmenttousesinglesign-on capability inordertoimplementconnection-basedlogonautomation.Thei5/OSor OS/400 environmentprovidessinglesign-oncapabilitythrougha combinationof networkauthenticationservice andanIBMtechnology calledEnterpriseIdentity Mapping(EIM).HostOn-Demandusesthisexistingmethodologyforacquiring credentialstoallowuserstobypassthe5250session loginscreen.Bothnetwork authentication serviceandEIM technologyareavailable withthei5/OSand OS/400 (V5R2and later)operatingsystems.

Figure5onpage16illustratestheoverallprocessofconnection-basedautomation inan i5/OSorOS/400environment withKerberosauthentication enabled:

(22)

1. Auserlogs ontotheWindows domain.TheWindows domaingivesusers accesstothenetwork.

2. Theuser requestsaHostOn-DemandsessionfromtheHostOn-Demand server.

3. TheHostOn-Demandsessioninitializesandrequestsa Kerberosticket fromthe KDC.

4. Theuser attemptsto createa connectionwith theidentifiedsession usingthe Kerberosticketasthecredential.

5. Thei5/OSorOS/400hostvalidatestheticket withtheKDC. 6. Theuser issuccessfullyloggedin

FTP login: WebExpressLogonprovidesanautomated wayforuserstologonto FTPhostsbyprovidingacentralrepositoryforstoringandretrievinguser’s credentials.Althoughthis processissimilartoconfiguringWebExpressLogonina vault-style environment,thistypeofautomation isdifferentbecausetheuser’s credentialsare retrievedfromtheCMSatthetimetheconnectionisestablished.In otherwords,itdoesnotrequireamacro.Currently,HostOn-Demandallowsyou tostore auser’sIDandpasswordstaticallyintheFTPconfiguration;however,Web Express Logonextendsthis approachbyautomatingtheusercredentialretrieval process.

Figure6 onpage17illustratestheoverallprocessofconnection-basedautomation in anFTPloginenvironment: 4 3 1 2 K D C Windows Domain Controller 6 5 Host On-Demand Server User’s Workstation iSeries Host

(23)

1. Theuser clicksalinktolaunchtheHostOn-Demanddesktop,whichsendsan HTTPSrequestthroughthenetworksecurityapplication totheWebserver. 2. TheWeb serverreturnstheHTTPSrequest,andtheHostOn-Demanddesktop

displays.

3. Theuser attemptstolaunchanFTPsession.

4. TheFTPsessionsendsanHTTPSrequesttotheCMStoobtaintheFTP credentials.

5. TheCMSretrievestheuser’snetworkIDfromtheNetworkSecurityplug-in. 6. TheCMSpassesthenetworkIDtotheVaultHCMplug-in.

7. Using thenetworkID, theVaultHCM plug-incalls upona database,suchas IBM DB2,tomaptheuser’shostIDandrequesttheuser’spassword.

8. TheVault HCMplug-inreturnstheFTPuser IDand passwordtotheCMS. 9. TheCMSreturnstheFTPcredentialstotheclient asanXMLdocument. 10. TheFTPlogincompletesanddisplaystheFTPserver’s filelistings.

Client Workstation

Application Server

Web Express Logon Server FTP Server 1 4 2 9 5 Web Application Server Credential Mapper Servlet(CMS) Network Security Plug-in Vault Host Credential Mapper(HCM) 6 7 N e t w o r k S e c u r i t y 10 Database (IBM DB2) 8 3

(24)

(25)

(26)

(27)

Chapter

3. Planning

for

implementation

Havinga clearunderstandingofyour environmentandhowyouplanto

implementWebExpress Logoninyour environmentwillsaveyouvaluabletimein theimplementationphase.Be surethatyoutaketimetodevelopyourstrategy and gather thenecessaryresourcesandskills.Afirm planiskeytoasuccessful

implementation.

Werecommendthatyoubeginplanningbytakingthefollowingsteps:

Step

1:

Choose

your

style

of

logon

automation.

Asdescribed intheintroduction, HostOn-Demandoffers twostyles oflogon automation:

v macro-basedautomation v connection-basedautomation

Thestyle oflogonautomation thatbestsuitsyour environmentdependsonyour host andsessiontype.Ifyour hostallowstheclienttosupplytheneededhost credentialsat thetimetheconnectionisestablished(forexample,duringthetelnet negotiation viaaKerberospassticket),connection-basedautomationisthe

appropriatestyle touse.However,if theclientdoesnotreceivetheneeded credentialsat timetheconnectionisestablished,thehostmustsenda loginscreen toauthenticate theclient.Sinceautomatingthisloginscreenrequiresa macro, macro-basedautomationistheappropriatestyle.Themacropopulatesthescreen’s credentialfieldswith theappropriate userinformationandthen transmitsthis informationtothehostforauthentication.

Step

2:

Identify

areas

of

credential

challenges.

Credentialchallengesarethetimesatwhichusersareprompted toprovideIDs and passwords.Thefirst stepistoevaluateyourexistingnetworkinfrastructure and identifywhichcredentialchallengesexist foryourusers.Approachthis step bysimulatingatypical dayand identifyingallthepointsat whichusersare prompted toprovidecredentials.For example,ina corporateenvironment,users mayhavetoprovidecredentialswhenattemptingtoaccessanyofthefollowing resources:

v operatingsystem v corporatehomepage v Web-basedapplications v host-basedapplications

Step

3:

Take

an

inventory

of

your

environment.

Atthispoint,youshouldknowwhichstyleoflogonautomationisappropriatefor your environmentandwhatcomponentsarenecessarytoimplementWebExpress Logon. Beforeyoucansuccessfullyplanyour deploymentstrategyandestimate thescopeof implementation,takeamoment totakeaninventoryofyour

environment andanswerthefollowingquestionsaccordingtoyour styleoflogon automation:

(28)

Macro-based

automation

v Whatisyour hosttype?

v Whatapplicationdousersgo throughtoaccessthenetwork? TivoliAccess Manager?NetegritySiteminder?MicrosoftActiveDirectory(WindowsDomain)? PortalServer?

v Areyouplanningtocustomize yourownNetwork Securityplug-in?Ifso,do youhavesomeoneonhandwhohassomeJ2EEknowledgeandexperience workingwithJ2EE-compliantservlets?

v WhatWebapplicationserverareyouusing?IBM WebSphereApplicationServer? BEAWebLogic?ApacheTomcat?

v Fornon-Portalenvironments, doyouhavea J2EE-compliantWebapplication servertodeploytheCredentialMapperServlet(CMS)toyour Webserver? v WhatwillyouuseasyourHostCredentialMapper(HCM) database?IBMDB2?

PortalServer CredentialVault?LDAP?

v DoyouplantouseDCASonaz/OSplatform? v Areyouusingclientcertificatesforsecurity?

Connection-based

automation

v Whatlevelofi5/OSorOS/400areyourunningonyour IBMeServeri5,iSeries, orAS/400hostorhosts?Youmustbe runningi5/OSV5R3orOS/400V5R2or laterinorder touseWebExpressLogon.

v Areyour HostOn-Demandclients authenticatedusingWindowsDomain? v WhatareyouusingasyourKey DistributionCenter(KDC)?

v Areyour clientsrunningoneormoreofthefollowingoperatingsystems? – Windows 2000Professional,Server,orAdvancedServer

– Windows XPProfessional – Windows 2003Server

Ifnot,youwillneedtoupgrade,sinceotherversions ofWindowsdonot supportKerberosauthentication.

Step

4:

Develop

your

deployment

strategy.

Now thatyouhaveevaluatedyourneed foraWebExpressLogonsolution,chosen thestyleoflogonautomationthatbestworksinyour environment,andtakenan inventoryofyour company’senvironmentandresources,youcanbegin

developingyour deploymentstrategy.Consider issuessuchashowmany/which userswillbeaffectedbythisimplementation, whichskills arerequiredfora successfulimplementation, andhowmanypeopleyouwillneedtoparticipatein thesetup process.

(29)

Step

5:

Establish

an

HCM

database.

ThisstepdoesnotapplytoCertificate-basedWebExpressLogonori5/OSor OS/400 environmentsthatsupportKerberosauthentication.An HCMdatabaseis requiredforallotherenvironmentsdiscussedinthisdocument.

ThisdocumentdoesnotprovidedetailsabouthowtoestablishanHCM database.Forthesedetails,refertotheWebExpressLogonwhitepaper,located at

ftp://ftp.software.ibm.com/software/

network/hostondemand/library/whitepapers/wel2.pdf .

An HCMisaback-endrepositorythatassociatesusers’networkIDstotheirhost IDs.TheCMSqueriesthisrepositoryduring thelogonprocess.WebExpress Logon supportsthefollowingtwotypesofHCMdatabases:

v aJDBCdatabase suchasonecreatedusingIBMDB2 v thePortalServer CredentialVault

Another possibilityfora repositoryisan LDAPdirectory.However, usingLDAPas your HCMdatabaserequiresyoutowriteyour ownplug-in. Formore

(30)

(31)

Part

4. Implementing

macro-based

automation

Theway inwhichyouimplementmacro-basedautomationdependsonyour environment.Inthissection,wefocusonthefollowingthreeenvironments: v z/OSandDCAS(withorwithoutclientcertificates)

v vault-style v PortalServer

Thisdocumentdoesnotprovidedetailsforconfiguringotherapplicationsto workwithHostOn-DemandWebExpressLogon.Formoreinformation regardingconfiguringotherapplications,refertotheWebExpressLogonfor HostOn-Demandwhitepaper,locatedat

ftp://ftp.software.ibm.com/software/

network/hostondemand/library/whitepapers/wel2.pdf .

(32)

(33)

Chapter

4. Configuring

macro-based

automation

in

a

z/OS

and

DCAS

environment

TheDCASisaTCP/IPserverapplicationthatrunsonOS/390V2R10andlater (z/OSincluded).ItinterfaceswithaSecurityAccessFacility(SAF)-compliant serverproducttoassistwithexpresslogonservicessuchasCertificate-based WebExpressLogon.Inthisexample,thisSAF-compliantserverproductisIBM ResourceAccessControlFacility(RACF).

WebExpress Logonsupportstwodifferentmodels forz/OSandDCAS

environments—oneinwhichusersareidentifiedviaa networksecurityapplication and oneinwhichusersare identifiedviaclientcertificates(calledCertificate-based WebExpress Logon).Theconfigurationstepsdefinedinthischaptercover both models withcertaininformationthatisspecifictoCertificate-basedWeb

highlightedwith thefollowingicon:

ReferstoinformationthatisspecifictoCertificate-basedWebExpressLogon.

Thefollowingstepsshowyouhow toeditanddeploy theCMSprovidedwith HostOn-Demand,createanSSLkeydatabasesothatHostOn-Demandcan communicatewiththeDCAS,and usetheDeploymentWizardtocreateyour HTMLfile,configureyour 3270hostsession,andrecord yourloginmacro.Ina certificate-basedenvironment,youmustalsoconfigureyour HTTPserveraswell asthebrowserandJava 2keystoreoneachHostOn-Demandclient.Ina

non-certificate-based environment,youmust configureyournetworksecurity application andcreateyour HCMdatabase.Bothmodelsrequireyoutoconfigure theDigitalCertificateAccessServer (DCAS).

FormoreinformationaboutconfiguringHostOn-DemandclientsforHTTPS andclientauthentication,refertothePlanning,Installing,andConfiguringHost On-DemandguidelocatedintheHostOn-DemandInformationCenteratStart >Programs>IBMWebSphereHostOn-Demand>InformationCenteroron theWebathttp://publib.boulder.ibm.com/infocenter/hod9help.

Steps5–8aredesignedforadministratorswhoareplanningtousethe DeploymentWizardtocreatetheHTMLfile,configurethehostsessiontouse WebExpressLogon,andrecordtheWebExpressLogonmacroallinone sitting.However,youmaydecidetocreateyourHTMLfilefirstandthen configureyoursessionandcreateyourmacrolater.

Step

1:

Configure

the

Credential

Mapper

Servlet

(CMS).

WerecommendusingaJ2EE-compliantWebapplicationserversuchasIBM WebSphereApplicationServertoconfigure anddeploytheCredentialMapper Servlet(CMS). TheCMSissuppliedwith HostOn-Demandand mustbedeployed toa J2EE-compliantWebapplication server.Ata highlevel,theCMSisresponsible fordeterminingtheclient’sidentityandreturningthehostcredentialstotheclient asanXMLdocument.

(34)

A. Locate

the

WAR

files

on

the

Host

On-Demand

Version

9 CD

The threeWARfilesare locatedinthecdimage\apps\welsubdirectory.Choosethe onethatmatches yournetworksecurityapplication:

v IBMTivoliAccessManager:amcms.war v NetegritySiteminder:smcms.war

v MicrosoftActive Directory(Windows Domain):wincms.war

Ifyouhaveadifferentnetworksecurityapplication,youwillneedtocustomize yourownversionoftheCMS.Formoreinformationabouthowtodothis, refertoChapter9,“CustomizingWebExpressLogon,”onpage91.

Inadditiontoseveralotherfiles,theWARfilecontainsthefollowingfiles: v web.xml:theservletconfigurationfilethatyouwilleditina laterstep

v DCAS.xml:fornon-Certificate-based WebExpressLogon,a samplefiletohelp youbetterunderstandDCASparametersandtheirvalues

v DCASELF.xml:forCertificate-basedWebExpress Logon,asamplefiletohelp youbetterunderstandDCASparametersandtheirvalues

v was.policy:forIBM WebSphereApplicationServer usersonly,thisfilecontains therequiredpermissionsfortheCMSwhenJava 2securityisenabled (referto Chapter10,“TroubleshootingWebExpress Logon,”onpage103 formore information)

B. Become

familiar

with

the

INIT

parameters

in

the

web.xml

file.

Inthisstep, youwillbecomefamiliarwith thethreedefaultINITparametersinthe web.xmlfile.

v HostCredentialMapper(HCM) plug-in:Thenameoftheparameter is CMPICredentialMappers,andtheparametervalue isa compoundvaluethat containsthelistofallavailableHCM plug-ins,forexample,CMPIDCASPlugin CMPIVaultPlugin,and CMPIDCASELFPlugin.Currently,thevalueisecho,but youwilleventuallyreplacethiswith thenameofyour HCMplug-in.

Codeexample: <init-param>

<param-name>CMPICredentialMappers</param-name> <param-value>echo</param-value>

</init-param>

v NetworkSecurityplug-in:ThenameoftheparameterisCMPINetworkSecurity, andtheparametervalueisthefullpathnameoftheclassthathandlestheCMS interfaceintothenetworksecurityapplication.Thisexampleistakenfromthe amcms.warfile,whichisforTivoliAccessManager:

Codeexample: <init-param> <param-name>CMPINetworkSecurity</param-name> <param-value>com.ibm.eNetwork.security.sso.cms.CMNPIAccessManager </param-value> </init-param>

TheNetworkSecurityplug-indoesnotapplytoMicrosoftActiveDirectory (WindowsDomain),PortalServer,orCertificate-basedWebExpressLogon.For MicrosoftActiveDirectory,theWindowsloginIDisusedtoidentifytheuser. ForPortalServer,thePortalIDisusedtoidentifytheuser.For

Certificate-basedWebExpressLogon,theclientcertificateisusedtoidentify theuser.

(35)

v echoplug-in:Thenameofthis INITparameter (echo)isthesameasthevalue fortheHCM plug-in.Inafuturestep,youwillreplace echowith thenameof yourHCMplug-in.

HostOn-Demandprovidesthis optionalechoplug-inincaseyouwantto confirmthatyouareable todeploytheCMScorrectlybeforeyoubeginediting theweb.xmlfile.Forexample,after youdeployyour CMStoa Webserver,you cantest itbyentering thefollowingsyntax inaworkstation’sbrowseraddress bar:https://web_application_server_name/context_root/CredMapper,where web_application_server_nameisthenameof theWebapplication server,

context_rootisthenameofthecontextrootthatyouspecifywhendeployingthe CMS,andCredMapperisthenameof theCMSitself.

SomeWebapplicationserverproductsallowyoutodeploytheservletfirstand thenedittheXMLfile.Otherproducts,suchasWebSphereApplicationServer V5,workbestwhenyoudeploytheservletafteryouedittheXMLcode.Refer toyourproduct’sdocumentationfordetails.

Codeexample: <init-param> <param-name>echo</param-name> <param-value>com.ibm.eNetwork.security.sso.cms.CMPINetEcho,AuthType_All,* </param-value> </init-param>

C. Edit

the

CMS-related

parameters.

Inthisstep, youwilledittwoofthethreeINITparametersintheweb.xmlfile. INITparametersadapttheservlet toyourenvironment.Youwillnoteditthe CMPINetworkSecurity parameternameorvalue.

1. Locate theCMPICredentialMappers parameterandchangethenameofits currentvalue (echo)tothenameoftheDCASHCM

plug-in—CMPIDCASPlugin: <init-param>

<param-name>CMPICredentialMappers</param-name> <param-value>CMPIDCASPlugin</param-value> </init-param>

2. Locate theechoparameterand changethenameofitscurrentvalue(echo)to thenameof theparameter valuethatyouspecified fortheHCM

plug-in—CMPIDCASPlugin.

Now, replacetheparametervaluewith acompoundvalue thatcontainsthefull classpathnameoftheimplementingclass,theauthenticationtype tobeused bytheDCASHCMplug-in, andthehostmask.Separatethesevalueswith commas.Inthisexample,com.ibm.eNetwork.security.sso.cms.CMPIDCASisthe fullclasspathname,AuthType_3270Hostistheauthenticationtype, and*isthe hostmask.

Full classpathname

TheCMSusesthevalue ofthefullclass pathnametocreatea classobjectof thespecifiedtype.ThatobjectisthenusedtohandleCMSorHCMplug-in requests.Thespecifiedclassfilemustbe inthe...\WEB-INF\classes

subdirectoryina loosefile(notasa JARfile).Fromthislocation,theCMSwill be abletoaccessand useit whenevertheneedarises.

Authenticationtype

Thisvalueisusedtoidentifythetype ofauthenticationthattherequestor needs.Once youspecifythedesiredauthenticationtype,theCMScanbetter identifywhichcredentialmappertoselecttohandletherequest.Youcanpair

(36)

multipleauthentication typestogethertogiveHCMplug-insthefreedom to supportmultiple authenticationtypes. Usetheverticalbarcharactertojoin multipleauthentication types.

Thefiveidentifiedauthentication typesarelistedintheTable2:

AuthenticationusedinSecureShell(SSH)onVTemulationorsftpsessionsare notsupportedbytheHCMplug-in.

Table2.Authenticationtypesanddescriptions

Authenticationtype Description

AuthType_3270Host Identifiesthecredentialstobeusedwitha 3270emulation

AuthType_5250Host Identifiesthecredentialstobeusedwith 5250emulation

AuthType_VTHost IdentifiesthecredentialstobeusedwithVT emulation

AuthType_FTPPassword CredentialsusedtoaccessanFTPhost AuthType_ConfigServer Credentialsidentifiedbythetokenusedto

identifytheusertotheHostOn-Demand configurationserver(ifyouareusingthe Configurationserver-basedmodel AuthType_All Identifiesthecredentialstobeusedforall

authenticationtypes

Host mask

Thehostmask isa secondaryselectioncriteriausedbytheCMStoidentifythe mostappropriatecredentialmapper. Thisvalue cancontainoneormorehost addresses.Usetheverticalbarcharactertojoinmultipleaddresses.Usethe asteriskscharactertowildcarda hostaddress.Thewildcardcharactermay start,end,orstart andendahost address.

Table3lists validwild-cardedaddresses: Table3.Hostmasksandvaluesmatched

Hostmask Valuematched

*.raleigh.ibm.com Matchesalladdressesthatendwith

.raleigh.ibm.com

ralvm* Matchesalladdressesthatstartwithralvm

* Matchesall

*xyz* Matchesanyhostaddressthatcontainsxyz

Codeexample: <init-param> <param-name>CMPIDCASPlugin</param-name> <param-value>com.ibm.eNetwork.security.sso.cms.CMPIDCAS, AuthType_3270Host, *</param-value> </init-param>

D. Add

optional

CMS-related

debugging

parameters.

Addthefollowingtwooptionaldebuggingparameterstohelpyoutroubleshoot:

CMPI_TRACE_LOG_FILE

(37)

fullpathtothelogfile,forexampleC:\Program Files\IBM\ HostOnDemand\HODWEL.log ona Windowsplatform. Codeexample: <init-param> <param-name>CMPI_TRACE_LOG_FILE</param-name> <param-value>C:\Program Files\IBM\HostOnDemand\HOD\HODWEL.log </param-value> </init-param> CMPI_CMS_TRACE_LEVEL

ThisparameterspecifiesthetracelevelfortheCMS.Thetracemessages are loggedtothelogfilespecifiedbyCMPI_TRACE_LOG_FILEparameter. Dependingonyour Webapplicationserver,theymayormaynotbe logged totheconsole.Tracelevelvaluesinclude thefollowing: v 0 =None:Notracing.Thisisthedefault.

v 1 =Minimum:TraceAPIsandparameters, returnvalues,anderrors. v 2 =Normal:TraceMinimumplusinternalAPIsandparametersand

informationalmessages.

v 3 =Maximum:TraceNormalplusJavaexceptions. Codeexample:

<init-param>

<param-name>CMPI_CMS_TRACE_LEVEL</param-name> <param-value>3</param-value>

</init-param>

E. Add

the

required

DCAS

client

parameters

for

the

CMPIDCASPlugin.

AddtherequiredDCASclientparameterstoallowtheHCMdatabasetomapthe user IDto thehostIDandget apassticketfromtheDCASapplicationrunningon thehost.Apassticket isa credentialthatissimilartoapassword, howevera passticket expiresafter acertainamount oftimeand isusedonlyonetime.DCAS requiresa SecurityAccessFacility(SAF)-compliantserverproduct,suchasanIBM ResourceAccessControlFacility(RACF)securityserver,thatsupportspassticket generation.

StartingwithHostOn-DemandV9.03,theCMPI_DCAS_KEYRING_FILEand CMPI_DCAS_KEYRING_PASSWORDaredeprecatedandshouldnotbeused. Instead,CMPI_DCAS_TRUSTSTORE,CMPI_DCAS_TRUSTSTORE_PASSWORD, andCMPI_DCAS_TRUSTSTORE_TYPEshouldbeused.However,

CMPI_DCAS_KEYRING_FILEandCMPI_DCAS_KEYRING_PASSWORDwill continuetoworkinlieuofCMPI_DCAS_TRUSTSTOREand

CMPI_DCAS_TRUSTSTORE_PASSWORD,andthetypepkcs12willbeassumed whenthesedeprecatedparametersareused.

TousetheDCASHCMplug-in,youmustconfiguretheDCAS.Forinformation aboutconfiguringtheDCAS,refertodocumentationforz/OSV1R4.0

CommunicationsServerathttp://publibz.boulder.ibm.com/cgi-bin/ bookmgr_OS390/Shelves/F1A1BK33,specificallythez/OSV1R4.0 CommunicationsServerIPConfigurationReference(publicationnumber

SC31-8776-03)andthez/OSV1R4.0CommunicationsServerIPConfigurationGuide (publicationnumberSC31-8775-02).Alsorefertothez/OSV1R4APAR

PQ74457forinformationabouthowtoconfiguretheDCAStofunctionwith WebExpressLogon.

(38)

Fornon-Certificate-basedWebExpressLogon,useDCAS.xmllocatedinthe WARfileasareferenceforaddingparameterswheneditingtheweb.xmlfile. ForCertificate-basedWebExpressLogon,useDCASELF.xmlasareference.

1. AddthefollowingHCMdatabaseparameterstoallowtheclienttoconnectto theDCASsecurely:

CMPI_DCAS_KEYRING_FILE

Thisparameterreferencesan SSLkeyringdatabasefilethatprovides accesstotheDCASclientcertificate aswell astheDCASserver’s certificate.Thecertificatesestablishaclient-authenticated, secure connectionwith theDCASserver.TheDCASplug-inservesasthe DCASclient.Youwillcreateakeyringdatabasefilecalled

HODDCAS.p12in“Step 3:CreatetheSSLkeydatabase.”onpage37. Codeexample: <init-param> <param-name>CMPI_DCAS_KEYRING_FILE</param-name> <param-value>C:\Program Files\IBM\HostOnDemand\HOD\HODDCAS.p12 </param-value> </init-param> CMPI_DCAS_KEYRING_PASSWORD

Thisparameterspecifiesthepasswordfor thekeyringdatabase. Thisparametershouldbeencryptedusingthepasswordencryptiontool.Itis decryptedbytheHCMbeforeusingit.Formoreinformationaboutthe passwordencryptiontool,refertoAppendixC,“Passwordencryptiontool,”on page121. Codeexample: <init-param> <param-name>CMPI_DCAS_KEYRING_PASSWORD</param-name> <param-value>45ie8WciVu</param-value> </init-param> CMPI_DCAS_TRUSTSTORE

Thisparameterisrequiredunless

CMPI_DCAS_USE_DEFAULT_TRUSTSTOREor

CMPI_DCAS_USE_WELLKNOWN_KEYSistrue.Thisparameter containsthenameofthetruststoretobeusedbyJSSEtolookupthe DCAScertificates.

CMPI_DCAS_TRUSTSTORE_TYPE

Thisparameterisrequiredunless

CMPI_DCAS_USE_WELLKNOWN_KEYSistrue.Thisparameter containsthetypeof thetruststorespecified by

CMPI_DCAS_TRUSTSTORE.Validvaluesare pkcs12,jceks,and jks.

CMPI_DCAS_TRUSTSTORE_PASSWORD Thisparameterisrequiredunless

CMPI_DCAS_USE_WELLKNOWN_KEYSistrue.Thisparameter containsthepasswordofthetruststorespecifiedby

CMPI_DCAS_TRUSTSTORE.

2. Thefollowingparameterscontainalltherelevantinformationneededto connecttoyour HCMdatabase,whichinthisexampleisaJDBCdatabase table.Youcaneither configureaccesstoanexistingdatabaseor pointtoa newlycreateddatabase.Thelevelofsecurityforthedatabase variesaccording

(39)

todatabasevendor. Refertothedatabaseapplication’sdocumentationfor details.

ThefollowingparametersarenotusedforCertificate-basedWebExpress Logon: v CMPI_DCAS_DB_ADDRESS v CMPI_DCAS_DB_NET_DRIVER v CMPI_DCAS_DB_USERID v CMPI_DCAS_DB_TABLE v CMPI_DCAS_DB_PASSWORD CMPI_DCAS_DB_ADDRESS

Thisisa URLstringthatprovides theaddress ofthedatabase.An exampleofthis stringisjdbc:db2://dtagw:6789/HODSSO. Codeexample: <init-param> <param-name>CMPI_DCAS_DB_ADDRESS</param-name> <param-value>jdbc:db2://dtagw.raleigh.ibm.com:6789/HODSSO </param-value> </init-param> CMPI_DCAS_DB_NET_DRIVER

Thisstringcontainsthenameoftheclassthatactsasthenetwork databasedriver.An exampleofthisstringis

COM.ibm.db2.jdbc.net.DB2Driver.Thelocationofthis classisassumed tobein theexistingclasspath.

Codeexample: <init-param> <param-name>CMPI_DCAS_DB_NET_DRIVER</param-name> <param-value>COM.ibm.db2.jdbc.net.DB2Driver</param-value> </init-param> CMPI_DCAS_DB_USERID

ThisistheIDoftheuser accounttousewhenaccessingthedatabase. Codeexample: <init-param> <param-name>CMPI_DCAS_DB_USERID</param-name> <param-value>admin</param-value> </init-param> CMPI_DCAS_DB_PASSWORD

Thisisthepasswordoftheuser accounttousewhenaccessingthe database.

Thisparametershouldbeencryptedusingtheencryptpasswordtool.Itis decryptedbytheHCMplug-inbeforeusingit.Formoreinformationaboutthe passwordencryptiontool,refertoAppendixC,“Passwordencryptiontool,”on page121. Codeexample: <init-param> <param-name>CMPI_DCAS_DB_PASSWORD</param-name> <param-value>tuBu9v8lHiJi1jt08UgHzA==</param-value> </init-param> CMPI_DCAS_DB_TABLE

(40)

<param-name>CMPI_DCAS_DB_TABLE</param-name> <param-value>HACP</param-value>

</init-param>

3. Thefollowingparametersshouldcorresponddirectlytothecolumnheadingsin your HCMdatabaseandshouldclearlyindicatethecontentsofthecolumns. Withsomedatabases,suchasIBMDB2,thecolumnheadingsmust beinall upper-case letters,forexample,NETWORKID,HOSTADDRESS,

APPLICATIONID,andHOSTID.

Basedontheinformationprovidedbythefirst threeof theseparameters (networkID,hostaddress,and thehostapplication ID),youcanmake aSQL queryofthedatabasetogetthehostID. Theresultofthequeryisenteredin thehostID(HOSTID)column.Assumingthatthequeryissuccessful,a callis madetotheDCAStorequestthepassticket.

ThefollowingparametersarenotusedforCertificate-basedWebExpress Logon: v CMPI_DCAS_DB_NETID_COL_NAME v CMPI_DCAS_DB_HOSTADDR_COL_NAME v CMPI_DCAS_DB_HOSTAPP_COL_NAME v CMPI_DCAS_DB_HOSTID_COL_NAME CMPI_DCAS_DB_NETID_COL_NAME

Thisentryidentifiesthenameofthecolumnthatcontains thenetwork IDvalue(NETWORKID). Codeexample: <init-param> <param-name>CMPI_DCAS_DB_NETID_COL_NAME</param-name> <param-value>NETWORKID</param-value> </init-param> CMPI_DCAS_DB_HOSTADDR_COL_NAME

Thisentryidentifiesthenameofthecolumnthatcontains thehost addressvalue (HOSTADDRESS).

Codeexample: <init-param> <param-name>CMPI_DCAS_DB_HOSTADDR_COL_NAME</param-name> <param-value>HOSTADDRESS</param-value> </init-param> CMPI_DCAS_DB_HOSTAPP_COL_NAME

Thisentryidentifiesthenameofthecolumnthatcontains thehost applicationvalue (APPLICATIONID).

Codeexample: <init-param> <param-name>CMPI_DCAS_DB_HOSTAPP_COL_NAME</param-name> <param-value>APPLICATIONID</param-value> </init-param> CMPI_DCAS_DB_HOSTID_COL_NAME

Thisentryidentifiesthenameofthecolumnthatcontains theuser’s hostidentificationvalue (HOSTID).

(41)

<init-param>

<param-name>CMPI_DCAS_DB_HOSTID_COL_NAME</param-name> <param-value>HOSTID</param-value>

</init-param>

CMPI_DCAS_USE_NETID_AS_HOSTID

ThisentrywhensettoTrueidentifiesthenetworkIDastheRACFID withoutperforminganymapping.

<param-name>CMPI_DCAS_USE_NETID_AS_HOSTID</param-name> <param-value>False</param-value>

</init-param>

F. Add

the

optional

DCAS

client

parameters

(if

desired).

UnliketheprevioussetofDCASparameters,thefollowingparametersare optional.Which oftheseparametersyouaddtotheweb.mlfiledependsonyour environment andyourobjectivesasanadministrator:

CMPI_DCAS_TRACE_LEVEL

ThisparameterspecifiesthetracelevelfortheDCASplug-in. Thetrace messages areloggedtothelogfilespecifiedbyCMPI_TRACE_LOG_FILE parameter.Dependingonyour Webapplicationserver,theymayormay notbelogged totheconsole.Tracelevelvaluesinclude thefollowing: v 0 =None:Notracing.Thisisthedefault.

v 1 =Minimum:TraceAPIsandparameters, returnvalues,anderrors. v 2 =Normal:TraceMinimumplusinternalAPIsandparametersand

informationalmessages.

v 3 =Maximum:TraceNormalplusJavaexceptions. Codeexample: <init-param> <param-name>CMPI_DCAS_TRACE_LEVEL</param-name> <param-value>3</param-value> </init-param> CMPI_DCAS_HOST_PORT

TheDCAShostaddressisdeterminedbasedonthedestinationhost specifiedintherequest. Thedefaultportaddressof8990isused,butyou mayoverride itusingthisparameter.

Codeexample: <init-param> <param-name>CMPI_DCAS_HOST_PORT</param-name> <param-value>8990</param-value> </init-param> CMPI_DCAS_USE_WELLKNOWN_KEYS

Prior toHostOn-Demand9.03,theparameter

CMPI_DCAS_USE_WELLKNOWN_KEYSdefaultedtotrueand indicated thattheWellKnownTrustedCAs.p12fileshouldbe usedalongwiththe CMPI_DCAS_KEYRING_FILEtolookuptheDCASservercertificate. Starting withHostOn-Demand9.03,thisparameterdefaultstofalse, and whenit istrue,itindicatesthatWellKnownTrustedCAs.p12istheONLY truststorethatJSSEwillusetolookuptheDCASclientandserver certificates.

(42)

<init-param>

<param-name>CMPI_DCAS_USE_WELLKNOWN_KEYS</param-name> <param-value>true</param-value>

</init-param>

CMPI_DCAS_WELLKNOWN_PASSWORD

Ifyouchoosetoreplace theprovidedWellKnownTrustedCAs.p12with your own,youwillneedtospecifythepasswordhere. Placeyour

WellKnownTrustedCAs.p12fileinthesamedirectorywheretheprovided versionwas located.

Thispasswordshouldbeencryptedusingtheencryptpasswordtool.Formore informationaboutthepasswordencryptiontool,refertoAppendixC,

“Passwordencryptiontool,”onpage121.

Codeexample: <init-param> <param-name>CMPI_DCAS_WELLKNOWN_PASSWORD</param-name> <param-value>tuBu9v8lHiJi1jt08UgHzA==</param-value> </init-param> CMPI_DCAS_VERIFY_SERVER_NAME

Thisparameterindicatesif theserverhostnameinthecertificatemust be verifiedinadditiontothecertificatevalidation.The defaultisfalse. Codeexample: <init-param> <param-name>CMPI_DCAS_VERIFY_SERVER_NAME</param-name> <param-value>false</param-value> </init-param> CMPI_DCAS_REQUEST_TIMEOUT

Thisparameterspecifiesthepassticket requesttimeoutinmilliseconds.It shouldbe lessthantheHostOn-Demandmacrotime-outvalue.The defaultis50000. Codeexample: <init-param> <param-name>CMPI_DCAS_REQUEST_TIMEOUT</param-name> <param-value>50000</param-value> </init-param>

TheCMPI_DCAS_DB_PRESERVE_WHITESPACEand

CMPI_DCAS_DB_CASE_SENSITIVEparametersarenotusedfor Certificate-basedWebExpressLogon.

CMPI_DCAS_DB_PRESERVE_WHITESPACE

Thisparameterindicateswhethertotrim whitespacesfromthecredential requestparametersor not.Iftrue,thewhitespacesarenottrimmed.The defaultisfalse. Codeexample: <init-param> <param-name>CMPI_DCAS_DB_PRESERVE_WHITESPACE</param-name> <param-value>false</param-value> </init-param> CMPI_DCAS_DB_CASE_SENSITIVE

Thisparameterspecifieswhetheror nottheDCASplug-inconverts the application IDand networkIDoftheusertolowercase charactersandthen

(43)

usesthelcase()methodtomakeSQLqueriestotheHCMdatabase.This parameter shouldbe settotruewhenusingSQLapplicationsthatdonot support thelcase()method.

Codeexample: <init-param> <param-name>CMPI_DCAS_DB_CASE_SENSITIVE</param-name> <param-value>false</param-value> </init-param> CMPI_DCAS_USE_DEFAULT_TRUSTSTORE

ThisparameterindicatesthatJSSEshouldusethedefaulttruststoreto lookuptheDCAScertificates.Thisparameterisoverriddenbythe CMPI_DCAS_USE_WELLKNOWN_KEYSparameterwhen

CMPI_DCAS_USE_WELLKNOWN_KEYSissettotrue.Thedefaultisfalse.

CMPI_DCAS_NO_FIPS

ThisparameterindicatesthattheFIPSsecurityprovidershouldnotbe used. Thedefaultsecurityproviderwillbeusedinstead.Thedefaultis false.

Step

2:

Save

the

WAR

file

and

deploy

the

CMS.

Once yousave theWAR filewith youredits,youare readytodeploy theservlet to theWebserver.RefertoyourWebserverapplication’sdocumentationfordetailsof how todeploytheservlet.

Step

3:

Create

the

SSL

key

database.

Inordertocommunicatewitha DCASserver,anSSLconnectionmust be

established usingclientauthentication. Thisrequiresyoutocreatea keydatabase file,forexample,HODDCAS.p12.Tocreatethefile,usetheHostOn-Demand Certificate ManagementGUIonWindowsandAIXplatforms,orusea P12keyring toolforotherplatforms.Thiskeydatabase filemust containtheDCASclient’s personal certificateandtheDCASserver’scertificate (publickey)information. Also, theDCASclientcertificate mustbe added/importedto theDCASserver’s keyring forSSLclientauthentication.

Formoreinformationaboutcreatingthiskeydatabasefile,refertothe Planning,Installing,andConfiguringHostOn-Demandguide,whichislocatedin theHostOn-DemandInformationCenteratStart>Programs>IBM

WebSphereHostOn-Demand>InformationCenterorontheWebat http://publib.boulder.ibm.com/infocenter/hod9help.

Tocreatea keyringdatabasecalledHODDCAS.p12filethatwillbespecifiedinthe CMPI_DCAS_KEYRING_FILEparameterinyour web.xmlfile,takethefollowing stepsonaWindows machine:

1. Click Start>Programs>IBMWebSphereHostOn-Demand>Administration >Certificate Management.

2. Click KeyDatabaseFile>New.For theKeydatabasetype,selectPKCS12.For File Name,typeHODDCAS.p12.ForLocation, typeC:\Program

Files\IBM\HostOnDemand.

Web Express Logon Reference

IBM

WebSphere

Host

On-Demand

Version

10

Web

Express

Logon

Reference

IBM

WebSphere

Host

On-Demand

Version

10

Web

Express

Logon

Reference

Contents

Part

1.

About

this

book

.

.

.

.

.

.

. 1

Chapter

1.

Description

of

book

.

.

.

.

. 3

Part

2.

Overview

of

Web

Express

Logon

.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 5

Chapter

2.

Introduction

.

.

.

.

.

.

.

. 7

Part

3.

Planning