Enabling single sign-on with LDAP

Enabling single sign-on (SSO) preserves user authentication on different web applications in WebSphere Commerce. By using HTTP single sign-on, the user is not prompted multiple times for security credentials within a trust domain.

WebSphere Commerce Version 8.0.0.9 or later

WebSphere Commerce Version 8.0.1.1 or later

Note: If you want to enable single sign-on for WebSphere Commerce Developer, you need to install one of the following maintenance packages:

Fix Pack 9 (8.0.0.9) or later
Mod Pack 1 Fix Pack 1 (8.0.1.1) or later

Before you begin

Install and configure an LDAP server. To configure an LDAP server see Preparing the LDAP server for use with WebSphere Commerce.
Enable WebSphere Application Server security with Federated Repositories.
Modify the WebSphere Commerce configuration file. If WebSphere Commerce switches to a single sign-on environment when there is shopper information in the WebSphere Commerce database, ensure that the MigrateUsersFromWCSdb flag is set to ON.
Synchronize the system clocks of all the systems that are included in the single sign-on configuration.

Procedure

Configure single sign-on using the WebSphere Commerce Integration Wizard.
Alternatively, you can configure single sign-on by using a properties file and run a command in a command prompt. For more information, see 2.
1. Ensure that the WebSphere Application Server is in the following state.
 - Ensure that the WebSphere Application Server is started.
 Note: If the database hostname is recently changed, ensure that the following files are updated with the hostname information so that the WebSphere Commerce Integration Wizard can locate the database.
 - WC_installdir/instances/instance_name/xml/instance_name.xml
 - WC_installdir/instances/instance_name/properties/createInstance.properties
2. Open the Integration Wizard.
 - WC_installdir/bin/WCIntegrationWizard.sh
 - WC_installdir\bin\WCIntegrationWizard.bat
3. Verify the prerequisites. Click Next.
4. Select your WebSphere Commerce instance name. Enter and confirm your database password. Click Next.
5. Select Single Sign On as the integration task. Click Next.
6. Enter the information specific to your single sign-on configuration.
 1. Enter your single sign-on domain name.
 2. Select Configure JAAS Login Module if you want WebSphere Commerce to generate the LTPA token.
 Each field is described in the WC_installdir/components/sso/properties/ltpa.properties file.
 If you did not select the option to Configure JAAS Login Module, you can enable this configuration later by updating the security.xml file:
 1. Navigate to the following directory:
 WAS_profiledir/config/cells/host_name
 2. Open the security.xml file for editing.
 3. Add the following <entries> to the file within the <applicationLoginConfig> element:
 <applicationLoginConfig> <entries xmi:id="JAASConfigurationEntry_1210305965219" alias="WCLogin"> <loginModules xmi:id="JAASLoginModule_1210305989406" moduleClassName="com.ibm.ws.security.common.auth.module.proxy.WSLoginModuleProxy" authenticationStrategy="REQUIRED"> <options xmi:id="Property_1210305989406" name="delegate" value="com.ibm.ws.security.server.lm.ltpaLoginModule"/> </loginModules> <loginModules xmi:id="JAASLoginModule_1210306090375" moduleClassName="com.ibm.ws.security.common.auth.module.proxy.WSLoginModuleProxy" authenticationStrategy="REQUIRED"> <options xmi:id="Property_1210306090375" name="delegate" value="com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule"/> <options xmi:id="Property_1210306102953" name="cookie" value="true" required="false"/> </loginModules> </entries> </applicationLoginConfig>
 4. Restart the server.
7. Click Next and verify the summarized information.
8. Click Next > Finish to complete the WebSphere Commerce Integration Wizard.
9. Verify that the configuration is complete by searching for the Feature 'ldap','sso' enablement completed sucessfully. string in the log file:
 - WC_installdir/instances/instance_name/logs/enablesso_time.log
Important: Ensure that you add create/search/read/write permissions to the DNBind user after single sign-on is enabled. This permission ensures access to the tool pages.

Copy and modify the components/sso/properties/ltpa.properties file.

Copy the components/sso/properties/ltpa.properties file to the following directory:
- WC_installdir/instance_name/properties/ltpa.properties
- WCDE_installdir\setup\ltpa.properties

Modify the file.

Sample values are shown in this example:

#-----------------------------------------------------------------#
    Licensed Materials - Property of IBM
#
# WebSphere Commerce
#
# (C)Copyright IBM Corp. 2006, 2010 All Rights Reserved.
#
# US Government Users Restricted Rights - Use, duplication or
# disclosure restricted by GSA ADP Schedule Contract with
# IBM Corp.
#-----------------------------------------------------------------
# The authentication mechanism for Single Sign-On
# Accepted values are: ltpa
#--------------------------------------------------------
sso.authMode=ltpa

# LTPA password# (To avoid decrypting warnings in the log, it is strongly recommended to use
# the ASCII encrypted string generated from the <WCInstallDir>/bin/wcs_encrypt.bat 
# command without the merchant key option.)
#--------------------------------------------------------
sso.ltpaPassword=EaDPFd9VAf0=

# Specifies whether this tool should import or export the LTPA key file?
# Accepted values are: import,export
#--------------------------------------------------------
sso.ltpaFileAction=

# Single Sign-On domain name# For example,acme.com
#--------------------------------------------------------
sso.ssoDomain=acme.com

# LTPA key file path
#--------------------------------------------------------
sso.ltpaKeyPath=

# Need to configure Java Authentication and Authorization Service.  (Accepted values are:
    true/false)
# Only set to true if you want to generate LTPA token from WebSphere Commerce.
# Defaults to false.
#--------------------------------------------------------
sso.configureJAAS=false

Open a command prompt, and run the following command:

config_ant.bat -buildfile WC_installdir/components/common/xml/enableFeature.xml 
-DinstanceName=instance_name -DfeatureName=sso -DdbUserPassword=db_password

```
enableFeature.bat -DfeatureName=sso
```

Generate and export the key file for WebSphere Commerce.
1. Log on as one of the following users:
  - non-root user.
  - user with administrative authority.
2. Ensure that the WebSphere Application Server is started.
3. Open the WebSphere Application Server Administration Console.
4. Expand the Security node. Click Global Security.
5. In the Authentication section, ensure that the radio button for LTPA is selected. Click LTPA.
6. In the Cross-cell single sign-on section, enter and verify the password for the LTPA token that you are exporting.
7. Enter the Fully qualified key file name. This name is the directory location and file name for the key file that must be imported to the server for the other application. Click Export.
8. Click Apply > Save directly to the master configuration.
9. Go to the directory that you specified for the key file and verify that the key is generated.
10. Copy this exported key file from the WebSphere Commerce file system and import the key into the file system of the server for the other application.
Configure the LTPA token so that it flows over only SSL to ensure the security of your site.
1. In the WebSphere Application Server administrative console, expand the Security node. Click Global Security.
2. In the Authentication section, expand Web and SIP security. Click Single sign-on (SSO).
3. Select the Requires SSL check box.
4. Click Apply > Save directly to the master configuration.
Import the key file from the other application into WebSphere Commerce.
1. Copy the generated file key from the file system of the server for the application to the file system of the server for WebSphere Commerce.
2. In the WebSphere Application Server administrative console, expand the Security node. Click Global Security.
3. In the Authentication section, click LTPA.
4. In the Cross-cell single sign-on section, enter and verify the password for the LTPA token that you are importing.
5. Enter the Fully qualified key file name for the key file that you copied from the file system of the other application. Click Import keys.
6. Click Apply> > Save directly to the master configuration.
7. Restart the servers for WebSphere Commerce and the other application.
Configure the roles that are assigned to users that access the system from single sign-on (SSO).
Every time a user connects to the system by SSO, WebSphere Commerce tries to assign the roles from the MemberRegistrationAttributes.xml file with registration type = "SSO".
For more information, see MemberRegistrationAttributes XML and DTD files.

In WebSphere Commerce, security roles are assigned as part of the registration process. With single sign-on, the customer can bypass the registration step for your site if they have successfully authenticated to a collaborating system. The ability to be implicitly authenticated to a WebSphere Commerce site has little value when a user is denied access to the facilities that they want to use, such as shopping in a store. Therefore, the same functionality of automated role assignment that happens with user registration also happens in the session management code. In this case, configure the roles for SSO shoppers by using the 'SSO' registration type. This way, when a customer authenticates onto the system, WebSphere Commerce automatically provides all of the roles that they need for the site. Keep in mind that the SSO role assignment happens on a site level and not on a store level (as with the typical user registration). Therefore, ensure that the storeAncestor attribute specified is actually an ancestor of the site (store 0).
Example:
```
<User registrationType="SSO" memberAncestor="o=Default Organization,o=Root Organization" storeAncestor="o=Root Organization"> 
 <Role name="Registered Customer" roleContext="explicit" DN="o=Reseller Organization,o=Root Organization"/> 
 <Role name="Registered Customer" roleContext="explicit" DN="o=Seller Organization,o=Root Organization"/> 
 <Role name="Registered Customer" roleContext="explicit" DN="o=Supplier Organization,o=Root Organization"/> 
 <Role name="Registered Customer" roleContext="explicit" DN="ou=Supplier Hub Organization,o=Business Indirect Supplier Organization,
 o=Root Organization"/> 
 </User>
```
This example gives four roles to any customer who comes in to the system from SSO. This example gives a role to customers that exists on the LDAP server somewhere below the 'default organization' (because of the memberAncestor specified).

Enable single sign-on for Management Center.

Go to the following directory in your file system:
- WC_installdir/LOBTools.war/WEB-INF
- workspace_dir\LOBTools\WebContent\WEB-INF

Replace or edit the spring-extension.xml file that is in this directory. To enable single sign-on, you must replace the default controller configurations in this file, which are commented out and can be out-of-date, with the most current version of these configurations. Do not use the commented out controller configurations that are in the file by default.

If you did not add any custom configurations to the file, replace the default provided spring-extension.xml file with the following version of the file. This version includes the required controller configurations, which are no longer commented out.
spring-extension.xml

If you did add custom configurations to the default provided extensions file, either replace the file and then add your custom configurations or edit the spring-extension.xml file to include the required controller configurations. Replace the controller configurations for enabling single sign-on that are in commented out in the file by default and might be out-of-date with the following configurations:


<bean id="/Logon" class="com.ibm.commerce.foundation.client.lobtools.controllers.AuthenticationClientLibraryController">
  <property name="urlObject" value="Person"/>
  <property name="contextParameters">
    <props>
      <prop key="channelId">channelId</prop>
    </props>
  </property>
  <property name="clientLibrary" value="com.ibm.commerce.member.facade.client.MemberFacadeClient"/>
  <property name="clientLibraryMethod" value="authenticatePassword"/>
  <property name="aliasParameters">
    <props>
      <prop key="password">logonPassword</prop>
    </props>
  </property>
  <property name="generateLTPAToken" value="true"/>
  <property name="successView" value="/jsp/commerce/shell/restricted/AuthenticationSuccess.jsp"/>
  <property name="failureView" value="/jsp/commerce/shell/restricted/AuthenticationFailed.jsp"/>
</bean>
<bean id="/Logout" class="com.ibm.commerce.foundation.client.lobtools.controllers.AuthenticationClientLibraryController">
  <property name="urlObject" value="Person"/>
  <property name="clientLibrary" value="com.ibm.commerce.member.facade.client.MemberFacadeClient"/>
  <property name="clientLibraryMethod" value="logout"/>
  <property name="removeLTPAToken" value="true"/>
  <property name="logout" value="true"/>
  <property name="successView" value="/jsp/commerce/foundation/restricted/Values.jsp"/>
  <property name="failureView" value="/jsp/commerce/shell/restricted/AuthenticationFailed.jsp"/>
</bean>
<bean id="/ResolveIdentity" class="com.ibm.commerce.foundation.client.lobtools.controllers.AuthenticationClientLibraryController">
  <property name="urlObject" value="Person"/>
  <property name="contextParameters">
    <props>
      <prop key="channelId">channelId</prop>
    </props>
  </property>
  <property name="resolveIdentity" value="true"/>
  <property name="clientLibrary" value="com.ibm.commerce.member.facade.client.MemberFacadeClient"/>
  <property name="clientLibraryMethod" value="authenticateLTPA"/>
  <property name="successView" value="/jsp/commerce/shell/restricted/ResolveIdentitySuccess.jsp"/>
  <property name="failureView" value="/jsp/commerce/shell/restricted/ResolveIdentityFailed.jsp"/>
</bean>

After you complete your edits, save your changes and close the file.

The controller configurations include the following actions:

A Logon action, which generates an LTPA token when a user logs on to Management Center.
A Logout action, which removes the generated LTPA token when a user logs out of Management Center.
A ResolveIdentify action that is used with the authenticateLTPA service for resolving the identity of users.

Optional: If you configured WebSphere Commerce to generate the LTPA token (previously selected Configure JAAS Login Module), you must update the properties for the LogonCmd, UserRegistrationAddCmd, PersonProcessServicePersonRegister, and LogOffCmd.

Navigate to the following directory:
- WC_eardir/Stores.war/WEB-INF
- workspace_dir/Stores/WebContent/WEB-INF
Open the struts-config-ext.xml file for editing.

Locate the following code snippet for the logon command:

<action parameter="com.ibm.commerce.security.commands.LogonCmd" path="/Logon" type="com.ibm.commerce.struts.LTPATokenGenerationEnabledBaseAction">

Add the following generateLTPAToken property to the action parameter:

<!-- The store will create LTPA the token on logon -->
<set-property property="generateLTPAToken" value="10101:1"/>

Where 10101 represents your store ID.

Locate the following code snippet for the UserRegistrationAddCmd command:

<action parameter="com.ibm.commerce.usermanagement.commands.UserRegistrationAddCmd" path="/UserRegistrationAdd" type="com.ibm.commerce.struts.LTPATokenGenerationEnabledBaseAction">

Add the following generateLTPAToken property to the action parameter:

<!-- The store will create LTPA the token on registration -->
<set-property property="generateLTPAToken" value="10101:1"/>

Where 10101 represents your store ID.

Locate the following code snippet for the PersonProcessServicePersonRegister command:

<action parameter="member.registerPerson" path="/PersonProcessServicePersonRegister" type="com.ibm.commerce.struts.LTPATokenGenerationEnabledComponentServiceAction">

Add the following generateLTPAToken property to the action parameter:

<!-- The store will create LTPA the token on registration -->
<set-property property="generateLTPAToken" value="10101:1"/>

Where 10101 represents your store ID.

Locate the following code snippet for the logoff command:

<action parameter="com.ibm.commerce.security.commands.LogoffCmd" path="/Logoff" type="com.ibm.commerce.struts.LTPATokenGenerationEnabledBaseAction">

Add the following removeLTPAToken property to the action parameter:

<!-- The store will destroy/remove the LTPA token on logoff -->
<set-property property="removeLTPAToken" value="10101:1"/>

Where 10101 represents your store ID.

Optional: If LTPA tokens are being used, it is possible to allow them to keep a session alive beyond the standard WebSphere Commerce session timeout. The LTPA token is only checked when the session is expired. If valid it refreshes the session.
1. Navigate to the following directory:
 - WC_eardir/xml/config/
 - workspace_dir\WC\xml\config\
2. Open the wc-server.xml file for editing.
3. Change the value of keepAliveSession to true, as highlighted in the following code:
```
<MemberSubSystem AuthenticationMode="LDAP" ProfileDataStorage="LDAP">
	<Directory EntryFileName="ldap/ldapentry.xml" MigrateUsersFromWCSdb="ON" SingleSignOn="1"
	display="false" keepAliveSession="true"/>
<SyncOrganizationWxclusionList display="false"/>
<ResetPassword resetNullPasswordEnabled="true"/>
```
4. Save and close the file.
Deploy your changes to the WebSphere Commerce enterprise archive (EAR).
Restart the WebSphere Application Server.

What to do next

For security purposes, when single sign-on is enabled, users should close all web browsers after they logout of Management Center.