Enabling single sign-on

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

The following instructions are provided for enabling single sign-on when HCL Commerce is configured to use LDAP and the web application for which you are enabling single sign-on is sharing the same LDAP server.

Before you begin

Install and configure an LDAP server. To configure an LDAP server see Preparing the LDAP server for use with HCL Commerce.
Enable WebSphere Application Server security with Federated Repositories.
Modify the HCL Commerce configuration file. If HCL Commerce switches to a single sign-on environment when there is shopper information in the HCL 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

Enable SSO in your HCL Commerce deployment.

Method Procedure

Using Run Engine commands

Add the enable SSO command to custConfiguration.sh.
For example:
```
#!/bin/bash
run enable-sso domainName true
run set-system-property SingleSignOnEnabled true
```
Where an example of the domainName is mydomain.com.
In the Docker file, copy custConfiguration.sh to /SETUP/bin/custConfiguration.sh and change the permissions for the file to 755.
For example:
```
COPY custConfiguration.sh /SETUP/bin
RUN chmod 755 /SETUP/bin/custConfiguration.sh
```
Build the customized ts-app Docker image.

Using Vault configurations

Set the following SSO values in Vault.

Tenant/EnvName/EnvType/ssoEnable:true 
Tenant/EnvName/EnvType/ssoDomainName: domainName 
Tenant/EnvName/EnvType/ssoSSL: boolean

For more information on these values, see SSO-related configurations within the Environment data in Vault reference.

Optional: If HCL Commerce is the master of the SSO configuration, generate and export the key file for HCL Commerce.
- 1. Ensure that WebSphere Application Server is started.
  2. Open the WebSphere Application Server Administrative Console.
  3. Expand the Security node and click Global Security.
  4. In the Authentication section, click LTPA.
  5. In the Cross-cell single sign-on section, enter and verify the password for the LTPA token that you are exporting.
  6. 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.
  7. 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 HCL Commerce file system and import the key into the file system of the server for the other application.
- 1. From inside the ts-app container, run the following command to export the LTPA token.
```
export-ltpa-keys ltpaKeyFile password
```
    For example:
```
export-ltpa-keys /SETUP/ltpa.key passw0rd
```
  2. Copy and save the ltpa.key file locally.
```
docker cp bvt_txn_1:/SETUP/ltpa.key ltpa.key
```
Optional: If another application is the SSO Master, then import the key file from the other application into HCL Commerce.
1. Copy the generated key file from file system of the server for the other application to the file system for HCL Commerce.
2. Open the WebSphere Application Server Administration Console.
3. Expand the Security node and click Global Security.
4. In the Authentication section, select LTPA.
5. In the Cross-cell single sign-on section, enter and verify the password for the LTPA token that you are importing.
6. Enter the Fully qualified key file name for the key file that you copied from the file system of the other application.
7. Click Import keys.
8. Click Apply > Save directly to the master configuration.
9. Restart the servers for HCL Commerce and for the other application.
Optional: Configure the roles that are automatically assigned to users that use single sign-on (SSO) to log into HCL Commerce from another application.
1. Edit MemberRegistrationAttributes.xml.
  When a user logs into HCL Commerce by using single sign-on, the user is assigned a role in HCL Commerce from the MemberRegistrationAttributes.xml file with registrationType = "SSO". For more information, see MemberRegistrationAttributes XML and DTD files.
  
  In HCL 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 an HCL 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, HCL 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).
  
  The following 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).
```
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>
```
2. Copy the customized file to the following location in ts-app Docker and create a customized image: /opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/member
Optional: If LTPA tokens are being used, it is possible to allow them to keep a session alive beyond the standard HCL 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:
  - <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.
5. Build a customized image with this change.
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 log out of Management Center.