Configuring an OpenID Connect Relying Party

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

1. In the administrative console, clickSecurity > Global security > Web and SIP security > Trust association
2. If Enable trust association is not checked, check it, then click Apply.
3. Click Interceptors.
4. Click New to add an interceptor.
5. Enter the interceptor class name of com.ibm.ws.security.oidc.client.RelyingParty.
6. Add custom properties for your environment. Read OpenID Connect Relying Party custom properties for a list of the properties.
   Note:

   If you are running in a cluster, be sure to add the provider_<id>.createSession=true property.

7. Click Apply and Save the configuration updates.
   Important: Do not clickSave without clicking Apply first or the custom properties are discarded.
8. Determine whether you need to add the OpenID Connect Relying Party TAI class to the com.ibm.websphere.security.InvokeTAIbeforeSSO security custom property. Consider these points:

   If you do add the OpenID Connect Relying Party TAI (OIDC RP TAI) to InvokeTAIbeforeSSO, the TAI is invoked 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) and 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 invokes the TAI.

   • The first time a user logs in, they are redirected to the OpenID Connect provider (OP) and 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 has also expired, a refresh cycle begins.
   • If the access token has not expired, 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 if 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 are already generated by those 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.
9. Optional: To add the OpenID Connect Relying Party TAI class to com.ibm.websphere.security.InvokeTAIbeforeSSO :
   1. Click Security > Global security and then click Custom properties
   2. Check the list for com.ibm.websphere.security.InvokeTAIbeforeSSO
      • If Value: com.ibm.ws.security.oidc.client.RelyingParty 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:
        • Click on com.ibm.websphere.security.InvokeTAIbeforeSSO
        • Add a comma to the end of the existing value.
        • Add com.ibm.ws.security.oidc.client.RelyingParty to the end of the existing value.
   3. Click ok
10. 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:
       • Perform the following steps to retrieve the OP's signer certificate from its SSL port:
         1. Click Retrieve from the port.
         2. Fill in the information that is required to retrieve the OP's signer certificate:
            • In the Host field, enter the host name of your OP.
            • In the Port field, enter the SSL port of your OP.
            • In the Alias field, enter an alias that will be associated with the OP's signer certificate in your trust store.
         3. Click Retrieve signer information.
         4. Click Ok.
       • Perform the following steps to retrieve the signer certificate of the OP from a file.
         1. Click Add.
         2. Fill in 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 will be associated with the signer certificate of the OP in your trust store.
         3. Click Ok.
11. 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 will contain a realmName claim (like the Liberty OP does), enter the value for the realmName claim.
       • If your idToken will not contain a realmName claim, enter the issuer name that is used by our 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.
12. Configure your application to trust the realm of the OP.
    1. Navigate to Applications > Application Types > WebSphere enterprise applications.
    2. Click on your application.
    3. In the Detail properties section, click Security role to user/group mapping.
    4. Check All Role.
    5. Click Map Special Subjects, then select All Authenticated in Trusted Realms.
    6. Click OK.
13. Install the OpenID Connect application.
    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.
    The commands that are needed to install the OpenID Connect application resemble the following example:

    cd <install_root>/bin 
    wsadmin -f installOIDCRP.py install nodeName serverName

    To install in a cluster environment, the wsadmin command resembles the following example:

    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.

    clusterName

    is the name of the cluster on which OpenID Connect RP is to be installed.

14. Restart WebSphere Application Server.