Enabling single sign-on

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.

Before you begin

Procedure

  1. SolarisLinuxAIXWindows Configure single sign-on using the WebSphere Commerce Integration Wizard.
    1. Ensure that the WebSphere Application Server is in the following state.
      • SolarisLinuxAIXWindowsEnsure that the WebSphere Application Server is started.
      • WebSphere Commerce DeveloperWebSphere Application Server is not started.
      Note: If the database hostname is recently changed, ensure that 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 WebSphere Commerce Integration Wizard.
      • SolarisLinuxAIXWC_installdir/bin/WCIntegrationWizard.sh
      • WindowsWC_installdir\bin\WCIntegrationWizard.bat
      • WebSphere Commerce DeveloperWCDE_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:
      • WebSphere Commerce DeveloperWCDE_installdir/logs/enableFeature.log
      • SolarisLinuxAIXWindowsWC_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.
  2. For IBM i OS operating system Copy and modify the components/sso/properties/ltpa.properties file.
    1. Copy the components/sso/properties/ltpa.properties file to the following directory: WC_installdir/instance_name/properties/ltpa.properties[WebSphere Commerce Developer] WCDE_installdir\setup\ltpa.properties.
    2. 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
    3. 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

[WebSphere Commerce Developer] enableFeature.bat -DfeatureName=sso
  3. Generate and export the key file for WebSphere Commerce.
    1. Log on as one of the following users:
      • SolarisLinuxAIX non-root user.
      • Windows 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.
  4. 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.
  5. 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.
  6. 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"><BR>
    <Role name="Registered Customer" roleContext="explicit" DN="o=Reseller Organization,o=Root Organization"/><BR>
    <Role name="Registered Customer" roleContext="explicit" DN="o=Seller Organization,o=Root Organization"/><BR>
    <Role name="Registered Customer" roleContext="explicit" DN="o=Supplier Organization,o=Root Organization"/><BR>
    <Role name="Registered Customer" roleContext="explicit" DN="ou=Supplier Hub Organization,o=Business Indirect Supplier Organization,
           o=Root Organization"/><BR>
  </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).

  7. Enable single sign-on for Management Center.
    1. Navigate to the following directory:
      • SolarisLinuxAIXWindowsWC_installdir/LOBTools.war/WEB-INF
      • WebSphere Commerce Developerworkspace_dir\LOBTools\WebContent\WEB-INF
    2. Open the struts-extension.xml file for editing.
    3. If the single sign-on actions for Management Center are commented out, uncomment the sections of code.
      • ResolveIdentify - this action is for resolving the identity of users by using the authenticateLTPA service.
        <action path="/ResolveIdentity" parameter="Person" 
type="com.ibm.commerce.foundation.client.lobtools.actions.AuthenticationClientLibraryAction"
className="com.ibm.commerce.foundation.client.facade.bod.servlet.struts.BusinessObject DocumentActionMapping">
  <set-property property="contextParameters" value="channelId" />
  <set-property property="clientLibrary" value="com.ibm.commerce.member.facade.client.MemberFacadeClient" />
  <set-property property="clientLibraryMethod" value="authenticateLTPA" />
  <forward name="success" path="/jsp/commerce/shell/restricted/ResolveIdentitySuccess.jsp">
  </forward>
  <forward name="failed" path="/jsp/commerce/shell/restricted/ResolveIdentityFailed.jsp">
  </forward>
</action>
      • Feature Pack 7 or laterLogon - this action is for generating an LTPA token when a user logs on to Management Center. If this action does not display within the struts-extension.xml file, add this action.
        <action path="/Logon" parameter="Person" 
type="com.ibm.commerce.foundation.client.lobtools.actions.AuthenticationClientLibraryAction" 
className="com.ibm.commerce.foundation.client.lobtools.actions.AuthenticationActionMapping">
  <set-property property="contextParameters" value="channelId" />
  <set-property property="clientLibrary" value="com.ibm.commerce.member.facade.client.MemberFacadeClient" />
  <set-property property="clientLibraryMethod" value="authenticatePassword" />
  <set-property property="aliasParameters" value="password:logonPassword" />
  <set-property property="generateLTPAToken" value="true" />
  <forward name="success" path="/jsp/commerce/shell/restricted/AuthenticationSuccess.jsp">
  </forward>
  <forward name="failed" path="/jsp/commerce/shell/restricted/AuthenticationFailed.jsp">
  </forward>
</action>
      • Feature Pack 7 or laterLogout - this action is for removing the generated LTPA token when a user logs out of Management Center. If this action does not display within the struts-extension.xml file, add this action.
        <action path="/Logout" parameter="Person" 
type="com.ibm.commerce.foundation.client.lobtools.actions.AuthenticationClientLibraryAction" 
className="com.ibm.commerce.foundation.client.lobtools.actions.AuthenticationActionMapping">
  <set-property property="clientLibrary" value="com.ibm.commerce.member.facade.client.MemberFacadeClient" />
  <set-property property="clientLibraryMethod" value="logout" />
  <set-property property="removeLTPAToken" value="true" />
  <forward name="success" path="/jsp/commerce/foundation/restricted/Values.jsp">
  </forward>
  <forward name="failed" path="/jsp/commerce/shell/restricted/AuthenticationFailed.jsp">
  </forward>
</action>
    4. Save your changes and close the file.
  8. 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.
    1. Navigate to the following directory:
      • SolarisLinuxAIXWindowsWC_eardir/Stores.war/WEB-INF
      • WebSphere Commerce Developerworkspace_dir/wc/Stores.war/WEB-INF
    2. Open the struts-config-ext.xml file for editing.
    3. 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.
    4. 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.
    5. 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.
    6. 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.
  9. Optional: Feature Pack 7 or laterIf 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:
      • For IBM i OS operating systemSolarisLinuxAIXWindowsWC_eardir/xml/config/
      • WebSphere Commerce Developerworkspace_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.
  10. Deploy your changes to the WebSphere Commerce enterprise archive (EAR).
  11. 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.