Last week (see Single sign-on with an external Enterprise Content Management system - Part 1: LTPA based) we discussed the options to connect IBM Business Process Manager (BPM) to an Enterprise Content Management (ECM) server using a technical user or to propagate the end user credential with single sign-on. We looked at the simplest option to establish single sign-on through Lightweight Third-Party Authentication (LTPA) and checked the Web Service client and provider specific requirements.
The LTPA based approach though has limitations:
- LTPA is IBM proprietary. Non-IBM products will usually not understand it. Nevertheless, there are ECM products that can run on WebSphere Application Server (WAS) – for example Alfresco Enterprise – where LTPA might work.
- Even between IBM products LTPA requires to use the same user registry configuration which might not always be the case.
Today we have a look at a different authentication token that can be used to overcome such limitations: Security Assertion Markup Language (SAML) tokens. SAML was standardized by the OASIS standards consortium.
As IBM BPM uses the Web Services binding of the Content Management Interoperability Services (CMIS) to connect to an ECM system, it is important to note that the Web Services Security (WSS) specification specifies how to use so called SAML assertions within Web Service interactions. Both CMIS as well as WSS are also OASIS standards – so, if still necessary then this is another motivation to bring all of this together.
Based on my area of expertise, when it comes to application servers, I will explain steps based on a target ECM system that is hosted on WAS as well. I will describe the steps for the Web Service client (this is in IBM BPM) and provider (this is in the ECM system) separately. So, if your ECM system does not run on WAS, then you will need to adopt those steps.
The SAML tokens that we need to get into the Web Service request can be generated in different ways:
- By IBM BPM at the time of a Web Service request.
- By an external Secure Token Server (STS) that is called at the time of a Web Service request to generate a token.
- By propagation. With that I mean that the end user login happens through an Identity Provider (IdP) using the SAML HTTP POST binding. On a successful login, the identity provider creates the SAML token and sends this to the IBM BPM system. This SAML token can be propagated to the ECM system if it is valid for that system as well.
We will now look at the steps for the first approach.
To configure this, these things must be done:
- We need a key store with a certificate that is used to sign the SAML token. This allows the receiver of the SAML token to verify that it was signed by a trusted party.
- We need to configure the CMIS Web Service client in IBM BPM to create a SAML token instead of the default LTPA token.
- We need to configure the CMIS Web Service provider in the ECM system to consume the SAML token.
Let’s do it in that order.
Creating a key and trust store for the SAML token signing
A certificate is required for the service client to sign the SAML token that is send in a Web Service request. The receiver will need to check the signature to verify that token comes from a trusted party. Such a certificate can be created using the keytool command that can be found in WAS_HOME/java/jre/bin.
In a command prompt, we create a key store first:
keytool -genkeypair -keystore IBM_BPM_SAML_KeyStore.jks -storepass ksPassword -keypass ksPassword -keyalg RSA -alias IBM_BPM_SAML_Issuer -dname "cn=IBM BPM SAML Issuer, o=ACME" -validity 365 -storetype JKS
In a second and third step, we export the public key and import it into a second store that we call trust store:
keytool -export -alias IBM_BPM_SAML_Issuer -file pub.cer -keystore IBM_BPM_SAML_KeyStore.jks -storepass ksPassword -storetype JKS
keytool -import -alias IBM_BPM_SAML_Issuer -file pub.cer -keystore IBM_BPM_SAML_TrustStore.jks -storepass tsPassword -storetype JKS -noprompt
The pub.cer file is temporary and can now be deleted. The result are two files:
- A key store file IBM_BPM_SAML_KeyStore.jks with the private and public key. This key store will be used by the IBM BPM system to sign the SAML token.
- A trust store file IBM_BPM_SAML_TrustStore.jks with only the public key. This trust store will be used by the ECM system to verify the signature of the SAML token.
The stores are protected with different passwords and the key pair is valid for one year.
Configuring the CMIS web service client in IBM BPM to send SAML tokens
In a next step, we will configure IBM BPM to send a SAML token in the web service requests to the external ECM system.
First, we need to make the key store available to the IBM BPM system. For this, we need to copy the IBM_BPM_SAML_KeyStore.jks file into the config directory of the deployment manager. A good location is PROFILE_HOME/config/cells/CELL_NAME. After you placed the file there you need to perform a Full Resynchronize in the WAS admin console in System Administration > Nodes for all your nodes. This will distribute the file to the nodes.
Now we are ready to configure the web service client. IBM BPM uses a managed web service client with a policy set and binding that are by default configured to send an LTPA token. You can find them in the WAS admin console in Services > Service Clients. The relevant service clients for the single sign-on access to ECM system are prefixed with SSO.
There are in total six clients for different CMIS defined web service ports.
You can click on each of them to see the attached policy set and binding. The policy set defines which service features are required. The binding then specifies how these features are configured. By default, the IBM BPM CMIS service clients use the BPM SSO Policy Set and the BPM SSO Client.
We now need to replace these with a policy set and binding that sends a SAML token instead of an LTPA token. And for that I prepared something: CMIS client policy set.zipView Details and CMIS client policy set binding.zipView Details. Download these two files. These are a policy set and a matching binding that are configured in the same way as the BPM default one’s – beside that they send a SAML instead of an LTPA token.
In the WAS admin console go to Services > Policy sets > Application policy sets. Click Import > From Selected Location … and select the CMIS client policy set.zip file. Then go to Services > Policy sets > General client policy set bindings. Click Import … and select the CMIS client policy set binding.zip.
Let’s look at what we just imported. Go back to the policy sets and open the details of the CMIS client policy set. There, go to WS-Security > Main policy > Request token policies. There we can see the required SAML 2.0 token. The interesting configuration is in the binding. So, go to the client policy set bindings and open the details of the CMIS client policy set binding. Go to WS-Security > Authentication and protection. There, a single outbound authentication token is defined.
This specifies that a SAML token is to be generated. Click Callback handler to see the configuration. There you can see that the com.ibm.websphere.wssecurity.callbackhandler.SAMLGenerateCallbackHandler class is used. This is designated to generate a SAML token. Customization may be required at the bottom, where the custom properties are defined.
Here is an explanation for these properties, the long names are shortened:
|confirmationMethod||Use Bearer as the simplest confirmation method where the SAML token is only signed and could theoretically be used by anybody. For more security where the SAML token can only be used by a dedicated client, consider looking at the Holder-of-key assertion.|
|KeyStorePath||The path to the key store, if you chose a different file name or location, then you need to adjust this here.|
|KeyStoreType||The type of the key store that you specified as the storetype argument when creating the store with the keytool command.|
|KeyStorePassword||The password of the key store as specified in the storepass argument when you created the store with the keytool command. You can specify the password in clear text. WAS will automatically encode it.|
|KeyAlias||The alias of the key as specified in the alias argument when running the keytool command.|
|KeyName||The distinguished name of the key as specified in the dname argument when running the keytool command.|
|KeyPassword||The password of the key as specified in the keypass argument when running the keytool command. You can specify the password in clear text. WAS will automatically encode it.|
|IssuerURI||A URI that is used as issuer of the SAML token. You can choose a value here.|
The reference information of these properties can be found at SAML token generator properties for self-issued tokens.
After you made required changes, click OK to confirm the changes.
Note: if you are using older versions of IBM Business Process Manager and therefore possibly also older WAS versions, then the settings other than confirmationMethod may need to be specified in a different way. Please check the SAML Issuer Config Properties documentation.
Now we can configure the service client to use the policy set and binding. Go to Services > Service clients. For SSODiscoveryServiceRef, SSOMultiFilingServiceRef, SSONavigationServiceRef, SSOObjectServiceRef, SSORepositoryServiceRef and SSOVersioningServiceRef perform the following: click on it to view the details. Select the first row, then click Attach Client Policy Set > CMIS client policy set. Click Assign Binding > CMIS client policy set binding.
Click Save and synchronize the nodes. Certain changes to policy sets or bindings require the server to be restarted. Now it’s a good time to do this as we just finished the required changes on the web service client = the IBM BPM side.
Configuring the CMIS web service provider to consume SAML tokens
Now, we switch to the CMIS provider side. Depending on what system you are using these steps will be different. I will continue my explanations for an ECM system based on WebSphere Application Server using FileNet as example.
The first thing you need to verify is if the CMIS implementation is deployed correctly. The deployment is typically done using the IBM Content Navigator Configuration and Deployment Tool. This graphical user interface allows to deploy new and update existing deployments for the IBM Content Navigator application and for the CMIS endpoint for IBM Content Manager and FileNet Content Manager.
As a step of a so-called deployment profile, there is the Configure the IBM CMIS client authentication method step. There you need to specify WS-Security Authentication instead of the default HTTP Basic Authentication. The authentication policy name is not so relevant here as we are going to replace this later.
Note: WS-Security Authentication is only available for the CMIS 1.0 implementation. It is not supported for the CMIS 1.1 implementation. This is not a problem because IBM BPM does not require any CMIS 1.1 capabilities.
To allow the provider to verify the signature of the SAML token, we need to make the trust store available to the ECM system. For this, we need to copy the IBM_BPM_SAML_TrustStore.jks file into the profile directory of the deployment manager. A good location is PROFILE_HOME/config/cells/CELL_NAME. After you placed the file there you need to perform a Full Resynchronize in the WAS admin console in System Administration > Nodes for all your nodes. This will distribute the file to the nodes.
We now need to import a policy set and binding that consumes a SAML token. And for that I prepared again something: CMIS provider policy set.zipView Details and CMIS provider policy set binding.zipView Details. Download these two files. These are a policy set and a matching binding that are configured in the same way as the CMIS for FileNet Content Manager default one’s – beside that they consume a SAML instead of a LTPA token.
In the WAS admin console go to Services > Policy sets > Application policy sets. Click Import > From Selected Location … and select the CMIS provider policy set.zip file. Then go to Services > Policy sets > General provider policy set bindings. Click Import … and select the CMIS provider policy set binding.zip.
Let’s look at what we just imported. Go back to the policy sets and open the details of the CMIS provider policy set. There, go to WS-Security > Main policy > Request token policies. There we can see that it requires a SAML 2.0 or Username token. The username token is required for interactions where IBM BPM sends the technical user. The interesting configuration is in the binding. So, go to the provider policy set bindings and open the details of the CMIS provider policy set binding. Go to WS-Security > Authentication and protection. There, two inbound authentication tokens are defined.
The configuration of the Username Token Consumer is straight-forward. Interesting are the details of the SAML Token Consumer. This verifies that the SAML token in the message is from a trusted issuer by verifying its signature.
It specifies that it uses the system provided wss.consume.saml JAAS login configuration. More relevant information is specified in the Callback handler. In its details you can see that the com.ibm.websphere.wssecurity.callbackhandler.SAMLConsumerCallbackHandler system class is used. The custom properties there may require customization.
Here is an explanation for these properties, the long names are shortened:
|trustedIssuer_1||This matches the IssuerURI of the token provider. You can specify multiple of them by using the trustedIssuer_n naming pattern.|
|trustedSubjectDN_1||This is the distinguished name of the key that is used for the issuer. Here again, the trustedSubjectDN_n naming pattern is used where issuer and distinguished name of the key are paired.|
|trustStoreType||The type of the trust store that you used when creating the store with the keytool command.|
|trustStorePassword||The password of the trust store as specified when you created the store with the keytool command. You can specify the password in clear text. WAS will automatically encode it.|
|trustStorePath||The path of the trust store file, if you chose a different file name or location, then you need to adjust this here.|
After you made required changes, click OK to confirm the changes.
With the authentication and protection settings we now verified that SAML token is from a trusted issuer. We still need to read the information about the BPM user and make it the caller of the web service request in the ECM system. These settings can be found in the binding is well, in WS-Security > Callers. There you find again two entries, one for the Username Token Caller to read the credentials in case a WSS-UsernameToken is in the request. Relevant for the SAML interaction is the SAML 2.0 Caller. Looking at its details, you can see, the com.ibm.websphere.wssecurity.callbackhandler.SAMLIdAssertionCallbackHandler callback and the wss.caller JAAS login being used:
The purpose of the callback handler here is to extract the user identity from the SAML token. More information about it can be found in Establishing security context for web services clients using SAML security tokens.
Now, we can configure the CMIS web service provider to use this policy set and binding. Go to Applications > Application Types > WebSphere enterprise applications. Go to the details of the application that contains the CMIS web module. Then, go to Service provider policy sets and bindings. There, select the first row and click Attach > CMIS provider policy set and Assign Binding > CMIS provider policy set binding. Finally, it should look like this (IBM_FileNet_CMIS_1.0 is the application name in my installation).
Click Save and synchronize the nodes. Certain changes to policy sets or bindings require the server to be restarted. Do this now as we are now also finished to configure the provider.
After your system restarted, you can try the Content Integration from IBM BPM to your ECM system with single sign-on enabled on the ECM server definition. If you want to debug, a good starting point is to see the SOAP messages that IBM BPM sends and receives. To see them, enable the following trace on the application cluster members:
Conclusion and outlook
We changed the web service client in IBM BPM to use self-issued SAML tokens instead of LTPA tokens. By doing this we now have a better chance to integrate with ECM systems that
- Are WebSphere based, but use a different user registry configuration that prevents using LTPA
- Are WebSphere based, but do not share LTPA keys (for example between on cloud and on premise)
- Are not WebSphere based and therefore unable to be integrated with LTPA
Still, there are limitations. Even within WebSphere systems we cannot yet integrate across different WebSphere cells that use different realms or that use different login attributes. To come around this, we will next week look at further advanced configuration options to customize the content of the SAML token that we send.
Other articles in this series:
- Single sign-on with an external Enterprise Content Management system - Part 1: LTPA based
- Single sign-on with an external Enterprise Content Management system - Part 3: SAML based with customized SAML token content
- Single sign-on with an external Enterprise Content Management system - Part 4: HTTP header based