Configuring SAML Web SSO

You can configure SAML Web SSO for the managed Liberty servers in your cell by using one of two methods. You can migrate the existing WebSphere Application Server SAML Web SSO ACSTrustAssociationInterceptor TAI configuration, or you can create a new SAML Web SSO configuration that is specific to the managed Liberty servers in your cell.

Considerations if you want to migrate the existing WebSphere Application Server SAML Web SSO ACSTrustAssociationInterceptor TAI configuration:

This method can be used for relatively simple SAML SSO configurations.
You cannot perform SP-Initiated SAML SSO by using this method.
Refer to the SAML Web SSO known issues and limitations page to find the restrictions for using this method.
Follow the instructions on Enabling your system to use the SAML web single sign-on (SSO) feature to use this method.
When you use this method, you must ensure that the filter that intercepts the URLs on WebSphere Application Server do not also intercept URLs on the managed Liberty servers. Migrated configurations utilize bookmark-style SAML IdP-initiated SSO. After the user logs in to the IdP, the IdP redirects the user back to the server with the SAMLResponse to a pre-configured URL. If the filter for a configuration entry can intercept URLs for both server types, the SAMLResponse might be redirected to the wrong server type.

Considerations if you want to create a new SAML Web SSO configuration that is specific to the managed Liberty servers in your cell:

This method provides all the SAML Web SSO features that are available in Liberty.
If this method is configured, the SAML Web SSO ACSTrustAssociationInterceptor TAI is not migrated to the managed Liberty servers.

Before you begin

This task assumes the following:

You are familiar with the SAML Web SSO feature.
Your key and trust stores are the default key stores or configured as WebSphere managed key stores through Security > SSL certificate and key management > Key stores and certificates or the corresponding wsadmin task.
Your keys and certificates are loaded into your key and trust stores. See the following documents:
If you use a front-end router, you must make sure that you have session affinity enabled for your managed Liberty servers because SAML SSO on a managed Liberty server requires session affinity.
- The URL to route is https://(host):(port)/ibm/saml20. This URL is emitted in the WebSphere WebServer Plug-in configuration file (plugin-cfg.xml).

About this task

This task shows how to create a new SAML Web SSO configuration that is specific to the managed Liberty servers in your cell. This task uses the administrative console. You can also use wsadmin to perform the same function.

Procedure

Determine the key and trust stores that your configuration will use. You can use the following short names for well-known key and trust stores.
- CellDefaultKeyStore
- CellDefaultTrustStore
- NodeDefaultKeyStore
- NodeDefaultTrustStore
If you want to use any other managed key or trust store, you can use the following format for the value when you configure a key or trust store reference property: name=STORE_NAME managementScope=(cell):CELL_NAME:(node):NODE_NAME. Refer to the following example:
- ```
name=myKeyStoreRef 
managementScope=(cell):myCell:(node):myNode
```
- You can find the value for the managementScope parameter in the Management Scope column for your key store in the table that you can find by navigating to Security > SSL certificate and key management > Key stores and certificates in the administrative console.
Find the HTTPS port of your managed Liberty servers.
1. Navigate to Servers > WebSphere application servers(server name).
2. Expand Ports.
3. The HTTPS port number is the value for the WC_defaulthost_secure parameter.
Enable the SAML Web SSO feature by using the TAI configuration panels in the administrative console.
1. In the administrative console, navigate to Security > Global security > Web and SIP security > Trust association..
2. If the Enable trust association checkbox is not checked, check it and click Apply.
3. Click Interceptors.
4. Click New and enter samlWeb-2.0 in the Interceptor class name field.
  - When you configure samlWeb-2.0 as the class name for a trust association interceptor, the following error message displays when start, in the SystemOut.log and SystemErr.log files. Disregard this message.
    - SECJ0125E: Trust Association Init Unable to load Trust Association class samlWeb-2.0.
Add Liberty custom properties to customize how the SAML SSO feature behaves.
1. See the Liberty samlWebSso20 properties page to find the attribute names and values that you can configure.
  - You can use the following substitution variables:
    - host name: ${BOOTSTRAP_ADDRESS_host}
    - HTTP port: ${httpEndpoint_port}
    - HTTPS port: ${httpEndpoint_secure_port}
2. Determine the number of SAML service providers (SPs) that you want to configure.
  - Each SAML SP that you configure migrates to a separate samlWebSso20 entry in the managed Liberty server server.xml file.
  - For each SP that you configure, you prepend client_(n). to the attribute that is specific to each SP. For example, if you have two SPs, you would use client_1. and client_2..
3. For each attribute that you want to configure, prepend the client_(n). prefix that you chose. For example:
  - allowCreate becomes client_1.allowCreate
  - Following is an example for how to configure a pkixTrustEngine value:
    - client_1.PKIXTrustEngine is set to the value
      trustAnchor=CellDefaultTrustStore, trustedIssuers=xyz
Add client_(n).authFilter_(n) properties to configure the requests that your SPs intercept.
- See the Liberty authFilter properties page to see the attribute names and values that you can configure.
- You can configure more than one authFilter; the authentication filter conditions are AND'd together. Example property names include client_1.authFilter_1 and client_1.authFilter_2
- The value that you enter for the property is dependent on the filter type that you choose. Examples:
  - client_1.authFilter_1 is set to to the value type=requestUrl, urlPattern=/SimpleServlet, matchType=contains
  - client_1.authFilter_2 is set to to the value type=remoteAddress, value=127.0.0.1, matchType=greaterThan
  - client_1.authFilter_3 is set to to the value type=cookie, name=MyCookie, matchType=equals
Once you are done entering properties, click OK, then Save.
Once the configuration is synchronized with each node, your SAML SSO configuration is available on all managed Liberty servers in your cell.
If you intend to perform SP-Initiated SSO, configure your IdP with your new managed Liberty SPs:
1. If you are not using an HTTP reverse proxy that routs requests:
  1. Download an spMetadata.xml file from each managed Liberty server.
    - For each managed Liberty server, obtain the spMetadata.xml files by accessing the following endpoint, where SPName is the value that you entered for the id property:
      
      https://(hostname):(httpsPort)/ibm/saml20/(SPName)/samlmetadata
    - You can find the HTTPS port of your managed Liberty server(s) with the following procedure:
      
      Servers > WebSphere application servers > (server name)
      
      Expand Ports.
      
      The HTTPS port number is the value for the WC_defaulthost_secure parameter.
  2. Follow the instructions for your IdP to import the spMetadata.xml files.
2. If are using an HTTP reverse proxy that routs requests:
  1. Make sure that you set the client_(n).spHostAndPort property to the same value for each client configuration.
  2. Download the spMetadata.xml files from one of your managed Liberty servers:
    - For each client configuration, obtain an spMetadata.xml file by accessing the following endpoint from one of your managed Liberty servers, where SPName is the value that you entered for the id property:
      
      https://(hostname):(httpsPort)/ibm/saml20/(SPName)/samlmetadata
  3. Follow the instructions for your IdP to import the spMetadata.xml files.