This section describes how to configure the VSJ TAI and VSJ User Registry for IBM WebSphere. Before you perform this activity you must have already installed the VSJ components. You must also ensure that you have set up Active Directory for SSO.
Setting Up the VSJ TAI To configure the VSJ TAI:
1. Go to the Security section of the WebSphere Administration console and enable LTPA and Trust Association.
2. Add the VSJ Trust Association interceptor (class name com.vintela.vsj.websphere.tai.VsjNtai) and click OK.
3. Enter VSJ custom properties as required.
For a list of the available parameters see VSJ Parameters for IBM WebSphere on page 23. In particular, if you are running VSJ on z/OS, be sure to configure the jcsi.kerberos.nameservers system property.
4. Finally, enable security and Set the Active Authentication Mechanism to LTPA.
5. Click OK.
Setting up the VSJ User Registry
The VSJ User Registry is designed to work much better with Active Directory than WebSphere's LDAP User Registry does. The LDAP User Registry only really supports a single Active Directory domain, whereas the VSJ User Registry effortlessly supports more complex Active Directory environments (cross-realm and cross-forest scenarios). Even for a single Active Directory domain, the VSJ User registry has many advantages over the LDAP User registry: performance, security, DNS auto-discovery of domain controllers, load-balancing / failover, site support, and simple configuration.
The VSJ User Registry can be used either with the VSJ TAI or independently of the VSJ TAI.
Note If you intend to use the VSJ TAI with the VSJ User Registry in an environment with multiple Active Directory domains, you need to update your VSJ TAI configuration and set the custom property idm.ad.qualifyUserPrincipal to true.
Before you configure the VSJ User Registry, it is advisable to check that Active Directory is correctly configured for VSJ and that the VSJ configuration parameters for the user registry are correct. If you have already successfully configured the VSJ TAI, then the same parameters that you used for the TAI will also work correctly for the user registry.
A number of custom properties are used to configure the user registry. Many of these properties are the same as the custom properties for the VSJ TAI, but some are peculiar to the user registry. The user registry must be configured separately from the TAI, so in some cases the same property must be configured twice: once for the TAI and once for the user registry.
Chapter 2 – Installing VSJ (WebSphere Edition) 23
The following custom properties for the VSJ User Registry are the same as custom properties for the VSJ TAI. Please see VSJ Parameters for IBM WebSphere below for descriptions of these properties:
Required—idm.realm Required—idm.princ
Required—one of the following:
idm.keytab idm.password
com.wedgetail.idm.sso.password (this is a Java system property, not a user-registry custom property)
Optional – idm.ad.site
The other VSJ TAI custom properties are not relevant to the user registry.
The following custom properties are peculiar to the VSJ User Registry:
Optional—idm.ad.userListAttribute (default: sAMAccountName) Optional—idm.ad.groupListAttribute (default: cn)
WAS allows deployers to search for users by specifying a search pattern. The VSJ User Registry implements this as an LDAP search request in Active Directory's Global Catalog for the LDAP attribute named by idm.ad.userListAttribute matching the specified search pattern. You may wish to specify an alternative LDAP attribute to use for the search, e.g. 'displayName', 'cn' or 'userPrincipalName' Similarly, WAS allows deployers to search for groups, and
idm.ad.groupListAttribute can be used to specify the LDAP attribute that the user registry will use for these searches.
Optional—idm.websphereRealm (default: VSJ)
This value is returned by UserRegistry.getRealm(). This is not related to the AD domain. It is not used by VSJ and can generally be left at its default value.
To configure the VSJ User Registry, go to the Security section of the WebSphere Administrative Console and set up a Custom Registry with the class name com.vintela.vsj.websphere.registry.VsjUserRegistry. Set the necessary custom properties as listed above.
Go back to the initial screen and set the custom registry to be active.
Save your configuration, log out of the administration console and restart the server. WAS should now be set up to use the VSJ user registry. See the simple example for instructions on how to use the registry to do authorization.
VSJ Parameters for IBM WebSphere
Table 1 provides a comprehensive list of VSJ parameters for IBM WebSphere.
Table 1: VSJ Parameters for IBM WebSphere
Parameter Default Description
idm.realm (required) none The Active Directory domain to be used for authentication, ie.
EXAMPLE.COM.
idm.princ "HTTP/
localhost"
The Kerberos service principal to use. This should be in the form HTTP/fully-qualified-host, i.e., HTTP/example.quest.com. It defaults to HTTP/localhost.
idm.keytab none The file containing the keytab that Kerberos will use for user-to-service authentication. If unspecified, VSJ will default to using an in-memory keytab with a password specified in the
com.wedgetail.idm.sso.password custom property or the idm.password parameter.
idm.allowNTLM false Specifies whether to allow fallback to NTLM authentication. This is required if you wish to use the VSJ solution with pre-Windows 2000/XP Internet Explorer browsers which do not support SPNEGO. The default is false.
In addition to setting this to true, complete NTLM support requires the FauxNtlmFilter to be configured. See the section Enabling NTLM authentication for a VSJ Web Application in Chapter 3 for more details.
idm.password none The password of the Kerberos service principal. VSJ will create an in-memory keytab using this password.
NOTE: This parameter is required if the idm.keytab parameter or com.wedgetail.idm.sso.password property is not set.
See Keytabs and Passwords on page 46.
idm.allowFallback false Specifies whether to allow fallback to Basic authentication. This is required if you wish to use the VSJ solution with non-Internet Explorer browsers. The default is false.
idm.allowUnsecured false Specifies whether to allow authentication over an unsecured channel. If you do not have SSL enabled on your Web Server, you must set this to true. The default if not set is false.
idm.kdc automatic
discovery
The Active Directory against which secondary credentials should be validated This can be used for BASIC fallback, or credential delegation. By default the KDC will be discovered automatically and this parameter should only be used if automatic discovery fails, or if a different KDC to the one discovered automatically should be used.
idm.fallbackCrossRealm false If this parameter is set, VSJ will attempt to guess the client's realm from domain part of the hostname returned by
ServletRequest.getRemoteAddr(), and the user is not required to append the realm to their username. By default this is false.
idm.supportMultiple SPN false Whether to support multiple service principal names. If this option is set to true then the server will use the service name in the ticket to determine which key to use for decryption. The default is false. (See Manually Creating Keytab Files.) idm.ad.site none The Active Directory site in which this server should be placed.
idm.tai.include “/” This parameter defines the URLs that will be included in the VSJ TAI authentication checking. It defaults to / .
idm.tai.exclude “/admin /ibm” This parameter defines the URLs that will be excluded from the VSJ TAI authentication checking. It defaults to /admin.
Table 1: VSJ Parameters for IBM WebSphere (continued)
Parameter Default Description
Chapter 2 – Installing VSJ (WebSphere Edition) 25
idm.ad.userPrincipalAttribute none This parameter can be set to the name of an Active Directory attribute. If set, the value of this attribute will be made available to web applications rather than the user name that was
authenticated. This could be used to allow a user to login normally with username and password but then be known to the web application by perhaps an employee id, which is stored and managed in Active Directory.
This property takes precendence over
idm.ad.qualifyUserPrincipal but is preceded by idm.ad.userPrincipalFormatterClass.
com.wedgetail.idm.sso.password none The password of the Kerberos service principal. VSJ will create an in-memory keytab using this password.
NOTE This property is required if idm.keytab or idm.password parameters are not set.
This is a system property. Configure this property in the Custom Properties in the Java Virtual Machine section.
See Keytabs and Passwords on page 46. jcsi.kerberos.nameservers automatic
discovery
A colon-separated list of one or more DNS servers that VSJ should use to look up DNS SRV records for Active Directory domain controllers. Specify each DNS server as either a hostname or as an IPv4 address.
Normally VSJ automatically discovers DNS servers by querying the JVM and/or the operating system. However, in some circumstances (such as when VSJ is running on z/OS), VSJ’s auto-discovery logic comes up empty-handed and so the list of DNS servers must be specified explicitly.
This is a system property. Configure this property in the Custom Properties in the Java Virtual Machine section..
idm.ad.qualifyUserPrincipal false Fully qualify the authenticated user name returned by VSJ i.e.
append the Active Directory domain name. The idm.ad.userPrincipal attribute and
idm.ad.userPrincipalFormatterClass properties take precedence over this one.
This property should be set to true if you are using the VSJ User Registry in an environment with multiple Active Directory domains.
idm.ad.userPrincipalFormatterClass none The class name of a UserPrincipalFormatter implementation to use for formatting principal names returned by VSJ. This property takes precendence over both
idm.ad.userPrincipalAttribute and idm.ad.qualifyUserPrincipal.
idm.ntlm.signing.username none The NTLM logon name of a user account that VSJ can use for NTLM signing.
idm.ntlm.signing.domain none The NTLM domain (not the AD domain) to which the above user account belongs.
Table 1: VSJ Parameters for IBM WebSphere (continued)
Parameter Default Description