This topic applies only to the IBM Business Process Manager Standard configuration.

This topic applies only to the IBM Business Process Manager Advanced configuration.

Configuring single sign-on (SSO) for federated IBM BPM environments by using LTPA keys

In single sign-on (SSO) environments, Lightweight Third Party Authentication (LTPA) keys are exchanged between Process Portal, Process Federation Server, and each IBM® BPM server in the federated environment. When users log in to one server, they can access all the other servers in the federated environment for which they are authorized without getting prompted again for their credentials.

Before you begin

Ensure that the following conditions are met:

Domains: The Process Federation Server and the IBM BPM servers, including the server that hosts Process Portal, must be in the same domain.
User registries for Process Federation Server and IBM BPM servers:
- The user registries must be shared. Different federated IBM BPM environments can use different user registries but you must configure these user registries on both Process Federation Server and the IBM BPM server that hosts Process Portal too.
  Restriction: You cannot mix LDAP servers with other authentication services, such as a basic user registry or a custom user registry.
- The user registries must use the same realm. The realm name must be the same as the one that you set for Process Federation Server. To do so, in the WebSphere® Application Server administration console, go to Security > Global Security, then, in the User account repository section, set your LDAP directory to use a federated repository and name the realm ldap_realm. For more information, see the Federated repositories page of the WebSphere Application Server knowledge center.
LTPA key file:
- The keys are active.
- All the IBM BPM servers, including the server that hosts Process Portal, share an LTPA key file.
System times: To avoid problems with LTPA expiry intervals, ensure that the system times on Process Federation Server and each IBM BPM server in the production environment are the same.

About this task

Users can log in to any server in the federated environment. When a user is authenticated on one of the servers, authentication information that the server generates is transported to the web browser in a cookie. The cookie contains the LTPA token for the browser session; the LTPA token is used to propagate the authentication information to the other servers.

Procedure

Configure SSO for Process Federation Server by uncommenting the following statement to the server.xml file:
```
<webAppSecurity allowLogoutPageRedirectToAnyHost="false" ssoDomainNames="domain.mycompany.com" ssoCookieName="LtpaToken2" ssoRequiresSSL="true" ssoUseDomainFromURL="true"/>
```
To ensure that the LTPA token cookies are propagated to all the federated IBM BPM systems, if you change the default value of the ssoCookieName property, you must also change the value of the propagateCookieNames property in all the ibmPfs_bpdRetriever and ibmPfs_bpelRetriever elements in the server.xml file. For more information, see Configuration properties for the Process Federation Server index.
Enable SSO for the federated IBM BPM servers, including the server that hosts Process Portal.
1. Log in to the administrative console.
2. Open the Global security page by clicking Security > Global security. Expand Web and SIP security and click Single sign-on (SSO).
3. In the Single sign-on (SSO) window, configure the following settings:
  - Select Enabled.
  - Enable Requires SSL.
  - Set the domain name.
  - Save your updates.
Disable the automatic LTPA key generation on the IBM BPM servers. Because the LTPA keys are shared between Process Federation Server and the IBM BPM servers, automatic generation of keys causes the shared keys to become out of sync over time. See WebSphere Application Server: Disabling automatic generation of Lightweight Third-Party Authentication keys
Share the LPTA key file among all the servers in the federated process environment.
Tip: To minimize the impact on existing IBM BPM environments that share LTPA keys, get and share the LTPA key file from one of the IBM BPM servers instead of sharing the Process Federation Server LTPA key. The instructions in this step assume that you are sharing an IBM BPM LTPA key.
1. Export the IBM BPM server LTPA key file from one of the servers by selecting Security > Global security > Authentication mechanisms and expiration > LTPA. Enter a password, which will be used to encrypt and decrypt the keys, and the fully qualified key file name, and then click Export keys.
2. If you have other IBM BPM servers that are not already configured for SSO with LTPA, import the LTPA key file into each of the servers.
  In the administrative console, import the LTPA keys into each of these servers by selecting Security > Global security > Authentication mechanisms and expiration > LTPA. Enter the encryption password (the default password is WebAS) and the fully qualified key file name, and then click Import keys.
3. Save your changes and restart the IBM BPM servers.
4. Import the LTPA keys into Process Federation Server by copying the key file to the pfs_install_root/usr/servers/server_name/resources/security directory and uncommenting the following entry to the server.xml file:
```
<ltpa keysFileName="pfs_install_root/usr/servers/server_name/resources/security/yourLTPAKeysFileName.keys" keysPassword="keys_Password"/>
```
5. Optional: Monitor the lpta.key file so that changes to the key file can be dynamically reloaded by setting a value for the monitorInterval attribute. In the following example, the lpta.key file is checked every 5 seconds:
```
<ltpa keysFileName="yourLTPAKeysFileName.keys" keysPassword="keys_Password" expiration="120" monitorInterval="5s" />
```

What to do next

Verify that SSO is configured correctly by completing the following steps:

From a web browser, go to a URL on any federated IBM BPM system or the IBM BPM server that hosts Process Portal, for example, the Process Portal URL: https://bpm_host.mycompany.com:9443/ProcessPortal. Import the signer certificate if prompted to do so by the browser.
Tip: Before you are directed to Process Portal, you should be prompted for your user ID and password the first time you access the URL.
From the same web browser, go to a URL on any other IBM BPM system in your federated environment, for example, the Process Portal URL: https://bpm_host.mycompany.com:9443/ProcessPortal. Import the signer certificate if prompted to do so by the browser.
Tip: You should be automatically directed to Process Portal without having to log in again.
From the same web browser, go to a Process Federation Server URL, for example, the systems REST service: https://pfs_host.mycompany.com:9443/rest/bpm/federated/v1/systems. Import the signer certificate if prompted to do so by the browser.
Tip: The REST service request should complete without having to log in again.

If you are not prompted to log in at steps 2 and 3, SSO is working correctly.

If you are prompted to log in at either step 2 or step 3, SSO is not working correctly. Verify the SSO configuration and restart your IBM BPM server or Process Federation Server if you updated the configuration. Before you verify SSO again, clear your browser cookies to remove the LTPA cookie that is used for SSO.