Configuring an OpenID Connect Relying Party

You can configure a WebSphere® Application Server to function as an OpenID Connect (OIDC) Relying Party (RP, or client) to take advantage of web single sign-on using an OpenID Connect Provider as an identity provider.

Before you begin

Read OpenID Connect overview for more information on OpenID Connect.

Review the properties that you must configure for OpenID Connect Relying Party configuration options. Read OpenID Connect Relying Party custom properties for more information.

Avoid trouble:

If you are running in a cluster environment, the OpenID Connect Relying Party (RP) Trust Association Interceptor (TAI) requires session affinity.
If you are using an outbound proxy, the OpenID Connect RP does not provide a means to route requests through a proxy host automatically.
If you must use a proxy to access the OpenID Connect Provider (OP), the value that you enter for any OP-related URL property must contain the proxy host and port. The value that you enter for any OP-related URL property must not contain the external OP host and port.

Usually, you can replace the OP host and port with the proxy host and port. The URL that you enter must be visible to both the RP and client (browser or application). For further guidance on how to determine the correct URL to use, contact your proxy administrator.

Important:

When you run the steps in this task, you might add the OpenID Connect Relying Party TAI class to the com.ibm.websphere.security.InvokeTAIbeforeSSO security custom property. To determine whether you want to add the class, consider the following points:

If you add the OpenID Connect Relying Party TAI (OIDC RP TAI) to InvokeTAIbeforeSSO, the TAI is started each time that a request is made to the protected resource.

The first time a user logs in, they are redirected to the OpenID Connect provider (OP). A set of JSON Web Tokens (JWT) is sent to the application server for the user.
On the first request that the application server receives after the access token from the JWT expires, a refresh cycle begins. Depending on OIDC and OP settings, one of the following occurs:
- The user is redirected to the OP.
- The refresh token from the JWT is sent to the OP to get a new access token.

If you do not add the OpenID Connect Relying Party TAI class to the InvokeTAIbeforeSSO list, the server checks for LTPA cookies on the request before it starts the TAI.

The first time a user logs in, they are redirected to the OpenID Connect provider (OP). A set of JSON Web Tokens (JWT) is sent to the application server for the user.
On the first request that the application server receives after the LTPA expires, the user is redirected to the TAI.
If the access token expired, a refresh cycle begins.
If the access token did not expire, a new LTPA token is created.
If the LTPA expiration is longer than the expiration of the access token, it is possible to end up with expired JWTs on a user's WebSphere Subject. Consider this situation when down-stream applications use the JWTs stored on the WebSphere Subject.
If you share LTPA keys with other WebSphere cells in your environment, then the LTPA cookies that generate WebSphere cells are valid for access to the protected resources. Until the user is redirected to the OP after the LTPA expires, the Subject contains only what was placed on it by the other cell.

About this task

To configure a WebSphere Application Server to act as an OpenID Connect Relying Party, follow these steps:

Procedure

Make sure that your OIDC runtime is up to date.
- If an interim fix is available for your fix pack, install the OIDC interim fix for the latest OIDC runtime. See Obtaining WebSphere OpenID Connect (OIDC) latest version.
- You must have an IBM login with entitlement to download an interim fix from IBM Fix Central.
Install the OpenID Connect application.
Avoid Trouble: If you intend to use OIDC in multiple clusters load-balanced by IBM HTTP Server (IHS) with the web server plug-in, install the application to each cluster with a separate application name and context root.
- The web server plug-in requires distinct context roots to maintain affinity with back-end servers in each cluster.
- If you are using another product for load balancing, consult that product's documentation to determine whether distinct context roots are needed for session affinity.
Choose one of the following approaches:
- Using the administrative console, install the app_server_root/installableApps/WebSphereOIDCRP.ear file to your application server or cluster.
- Install the OpenID Connect application by using the python script.
  1. Navigate to the app_server_root/bin directory.
  2. Run the script installOIDCRP.py for each profile on which the OpenID Connect RP is to be installed.
```
cd <install_root>/bin 
wsadmin -f installOIDCRP.py install nodeName serverName
```
    or
```
wsadmin -f installOIDCRP.py install clusterName
```
    where nodeName is the node name of the target application server, serverName is the server name of the target application server, and clusterName is the name of the cluster on which OpenID Connect RP is to be installed.
Import the OpenID connect provider's SSL signer certificate to the WebSphere Application Server truststore.
1. In the administrative console, click Security > SSL certificate and key management > Key stores and certificates > NodeDefaultTrustStore > Signer certificates.
  Use CellDefaultTrustStore instead of NodeDefaultTrustStore for a deployment manager.
2. Complete one of the following actions.
  - Retrieve the signer certificate of the OP from its SSL port.
    1. Click Retrieve from the port.
    2. Enter the information that is required to retrieve the OP's signer certificate.
      
      In the Host field, enter the hostname of your OP.
      
      In the Port field, enter the SSL port of your OP.
      
      In the Alias field, enter an alias that is associated with the OP's signer certificate in your truststore.
    3. Click Retrieve signer information.
    4. Click Ok.
  - Retrieve the signer certificate of the OP from a file.
    1. Click Add.
    2. Enter the certificate information:
      
      In the File name field, enter the path to the file that contains the signer certificate of your OP.
      
      In the Alias field, enter an alias that is associated with the signer certificate of the OP in your truststore.
    3. Click OK.
Recommended: Add the OpenID Connect Relying Party TAI class to com.ibm.websphere.security.InvokeTAIbeforeSSO.
For more information, see the Important note in the Before you begin section for information on how the com.ibm.websphere.security.InvokeTAIbeforeSSO property works.
1. Click Security > Global security and then click Custom properties.
2. Check the list for com.ibm.websphere.security.InvokeTAIbeforeSSO.
  - If the com.ibm.websphere.security.InvokeTAIbeforeSSO property does not exist, click New, and define the following custom property information:
    - Name: com.ibm.websphere.security.InvokeTAIbeforeSSO
    - Value: com.ibm.ws.security.oidc.client.RelyingParty
  - If com.ibm.websphere.security.InvokeTAIbeforeSSO exists:
    1. Click com.ibm.websphere.security.InvokeTAIbeforeSSO.
    2. Add a comma to the end of the existing value.
    3. Add com.ibm.ws.security.oidc.client.RelyingParty to the end of the existing value.
3. Click OK.
Enable trust association.
1. In the administrative console, click Security > Global security > Web and SIP security > Trust association.
2. If Enable trust association is not checked, check it, then click Apply.
Add the OIDC interceptor.
1. Click Interceptors.
2. Click New to add an interceptor.
3. Enter the interceptor class name of com.ibm.ws.security.oidc.client.RelyingParty.

Add custom properties for the OIDC interceptor.

Read OpenID Connect Relying Party custom properties for a list of the properties.
You can configure the OIDC properties in the administrative console or you can use the configureInterceptor admin task.
Read configureInterceptor in SecurityConfigurationCommands command group for the AdminTask object for more details.

The following tables list required and recommended OIDC TAI properties for the OIDC interceptor:

Table 1. Required OIDC TAI properties
Property	Value	Comments
provider_1.identifier		You create this identifier and it is used to build the redirect URL that is registered with the OP.
provider_1.clientId
provider_1.clientSecret
One of the following properties: provider_1.interceptedPathFilter provider_1.filter		If a request matches the filter conditions for more than one provider, the provider configuration that the TAI chooses is indeterminate.

Table 2. Recommended OIDC TAI properties
Property	Value	Comments
provider_1.discoveryEndpointUrl		When you configure the discovery endpoint for your OP, you do not have to hardcode the values for many other properties. The hardcoded properties much match the OP's configuration. Therefore, it is recommended to obtain the settings directly from the OP. OIDC discovery URLs end with `/.well-known/openid-configuration`.
provider_1.useRealm	WAS_DEFAULT	This property and value designates your user and groups from your idToken or JWT to the WebSphere realm instead of the OP's external realm. When you use this setting, you are not required to add the OP's realm as an external trusted realm or map the trusted realms to your applications.
provider_1.signatureAlgorithm	HEADER	The signature algorithm is obtained from the header of each inbound token.

Table 3. Required OIDC TAI properties for cluster members
Property	Value	Comments
provider_1.createSession	true
provider_1.callbackServletContext		Use the context name that you chose in step 2. The context root for the OIDC application is unique for each cluster.

The following table lists OIDC TAI properties to consider to use for the OIDC interceptor:

Table 4. OIDC TAI properties to consider
Property	Value	Comments
provider_1.mapIdentityToRegistryUser		When this property is set to `true`, the user (by shortname) must be in the WebSphere registry, and group memberships are applied to the user. The default for this property is `false`.

Click Apply.
Recommended: To make your application trust your OpenID provider's realm, complete one of the following actions:
- If your application does not require knowledge of the original realm name, you can hardcode the realm name that the OIDC TAI specifies for core security. The realm name is used to create the Subject.
  Set the provider_<id>.useRealm OIDC TAI property to the value WAS_DEFAULT, which was recommended in step 7.
- If your application must have access to the provider's realm name in the Subject, the realm of your OP must be seen as a trusted realm. The principal name is (foreignRealmName)/(userName).
  1. Add the realm of your OP as a trusted realm.
    1. Click Security > Global Security.
    2. In the User account repository section, click Configure.....
    3. In the Related Items section, click Trusted authentication realms - inbound > Add External Realm.
    4. In the External Realm name field, enter the value for your idToken. Complete one of the following actions:
      
      If your idToken contains a realmName claim (like the Liberty OP does), enter the value for the realmName claim.
      
      If your idToken does not contain a realmName claim, enter the issuer name that is used by the OP.
      You can find your OP's issuer by loading your OP's discovery endpoint, https://(hostname:port)/(contextRoot)/.well-known/openid-configuration, in a browser. The issuer can be found on the issuer field in the endpoint's output.
    5. Click OK.
  2. Configure your application to trust the realm of the OP.
    1. Click Applications > Application Types > WebSphere enterprise applications.
    2. Click your application.
    3. In the Detail properties section, click Security role to user/group mapping.
    4. Check the Java Platform Enterprise Edition security role that your WebSphere user or group is mapped to for this test. If you use the WebSphere DefaultApplication, check All Role.
    5. Click Map Special Subjects, then select All Authenticated in Trusted Realms. If you do not see All Authenticated in Trusted Realms available as a selection, go back to the previous step and make sure that you added the trusted realm.
    6. Click OK.
Click Save
Restart WebSphere Application Server.

Results

The WebSphere Application Server can now communicate with an OpenID Connect provider as an OpenID Connect Relying Party. See related information for custom configurations.