IBM Support

Examples: OpenID Connect, Liberty and WebSphere traditional

Troubleshooting


Problem

This document contains sample configuration tasks for OpenID Connect for both WebSphere® Application Server traditional and Liberty.

Resolving The Problem


Component:
General examples
  • Setting up a Google™ API Console project to use the Google OP with a WebSphere traditional or Liberty OIDC RP
    If you want to use the Google OP with either the Liberty or WebSphere traditional OIDC RP, you must first have a Google API Console project. Your console project must have at least one web client configuration.


    During configuration of the OIDC RP, you provide information about your Google API web client. You also add information about the OIDC RP to your Google API web client.

    This example task is a fast path that achieves a minimum configuration for the Google OP with the OIDC RP. The Google API Console provides many options for their OpenID Connect provider. If you want to explore those options further, see the following document provided by Google: Google Identity Platform, OpenID Connect.



    This example task is split into three parts:
    1. Create or select the project and present the new creds screen.
      • There are three different paths through this step. You choose which path that you want to use based on:
        • You did not login to the Google API Console before.
        • You did not use the Google API Console before and you want to create a new project for this task.
        • You did use the Google API Console before and you want to use an existing project for this task.
    2. Complete the panels to obtain creds.
    3. View Client ID, Client secret and add Authorize redirect URIs.

    If you already have a Google API Console project, client ID and secret that you want to use, open your project, then proceed to step #3.
     
    1. Create or select the project and present the new creds screen

    Perform one of the following procedures. Find the best fit for your situation on the left, then perform the procedure on the right.
    Audience
    Procedure
    Get Started

    You have no existing Google API project or credentials.
    1. In a browser, navigate to Goole API Console, Credentials
      • If prompted, login with your Google credentials
      • A terms of service page displays; answer the questions and click ACCEPT.
        • If you don't get this page, then you are logged in to the Google API Console with this Google ID before. You might have to run one of the other two procedures described later in this document.
    2. Since you never created a project before, you see a dialog titled APIs & Services Credentials that includes a Create button:
    3. Click Create
      1. Enter Project name and ID
        • The Project name and ID are pre-filled with defaults. If you want to change the values, do that now. You cannot change these values after the project is created.
      2. Click Create
        • A dialog titled APIs Credentials that includes a Create credentials button is displayed.
    4. Click Create credentials > OAuth client ID
    5. Click Configure consent screen
    6. Enter a product name, for example "Company.com application"
    7. Click Save
    8. Proceed to Step '2. Complete the panels to obtain creds' below this box.
    You used the Google API Console before and have at least one project.

    You want to create a new project.
    1. In a browser, navigate to the Goole API Console, Credentials
      • If prompted, login with your Google credentials
      • If you get a terms of service page, you might not have used the Google API Console with this Google ID before. Do one of the following:
        • Login with a different Google ID that used the Google API Console before.
        • Go back and use the Get Started procedure instead.
        • If you know with certainty that you used this Google ID with the Google API Console before, proceed to the next step.  Google might have updated their terms of service and is forcing you to accept the new terms.
    2. Note the current project
      • If you want to use this project, use the next procedure instead.
    3. Click the project drop-down
      • If the project that you want to use is displayed in the window, use the next procedure instead
    4. Click NEW PROJECT
      1. Enter Project name and ID
        • The Project name and ID are pre-filled with defaults. If you want to change the values, do that now. You cannot change these values after the project is created.
      2. Click Create
    5. Click the project drop-down again.
    6. Do one of the following:
      • If you see your new project on the RECENT tab, click your new project
        • A dialog titled APIs Credentials that includes a Create credentials button is displayed.
      • If you don't see your project on the RECENT tab, click ALL, then click your new project.
        • A dialog titled APIs Credentials that includes a Create credentials button is displayed.
    7. Click Create credentials > OAuth client ID
    8. Click Configure consent screen
    9. Do the following:
      • Enter an Application name, for example "Company.com application"
      • In the Authorized domains field, enter the domain name of your application server.  For instance, if your server name is test.ibm.com, your domain name is ibm.com.
      • Click Save
      • If you still see the warning that you need to configure a consent screen, reload the page.
    10. Proceed to Step '2. Complete the panels to obtain creds' below this box.
    You used the Google API Console before and have at least one project.

    You want to use an existing project.
    1. In a browser, navigate to Goole APIs & Services, Credentials
      • If prompted, login with your Google credentials
      • If you get a terms of service page, you might not have used the Google API Console with this Google ID before. Do one of the following:
        • Login with a different Google ID that used the Google API Console before.
        • Go back and use the Get Started procedure instead.
        • If you know with certainty that you used this Google ID with the Google API Console before, proceed to the next step.  Google might have updated their terms of service and is forcing you to accept the new terms.
    2. Note the current project
      • If you want to use this project, continue to the next major step.
      • Otherwise, click the project drop-down, then click the project that you want to use.
    3. Click Create credentials > OAuth client ID
    4. If you get a warning that you need to configure a consent screen, do the following:
      • Enter an Application name, for example "Company.com application"
      • In the Authorized domains field, enter the domain name of your application server then press Enter.  For instance, if your server name is test.ibm.com, your domain name is ibm.com.
      • Click Save
      • If you still see the warning that you need to configure a consent screen, reload the page.
    5. Proceed to Step '2. Complete the panels to obtain creds' below this box.

    2. Complete the panels to obtain creds
    1. Select Web Application
    2. Click Create
      • A page with your client ID and client secret displays
      • You need this information when you configure your OIDC RP. You don't have to copy it now; you have access to the information later.
    3. Click OK

    3. View Client ID, Client secret and add Authorize redirect URIs
    Click the web client that you created, for example, Web client 1
     
    • At the top, you see the Client ID and Client secret that you can copy into your OIDC RP configuration.
    • At the bottom, you can add or remove Authorized redirect URIs.
      • For WebSphere traditional, add https://(host):(port)/oidcclient/(identifier), where (identifier) is your provider_1.identifier OIDC TAI custom property for this OP. 
        • For instance, https://company.com:9443/oidcclient/client1
      • For Liberty, add https://(host):(port)/oidcclient/redirect/(id), where (id) is the id attribute of your openidConnectClient configuration.  
        • For instance, https://company.com:9443/oidcclient/redirect/client1

    The steps and screen captures in this procedure were obtained from a browser on a Windows workstation on 03/02/2018.
  • Setting up Microsoft® Azure™ or Entra™ ID to use as an OP for a WebSphere traditional or Liberty RP
    If you want to use the Microsoft Azure or Entra ID provider with either the Liberty or WebSphere traditional OIDC RP, you must configure your Azure/Entra tenant with the information that is required to acknowledge your WebSphere traditional or Liberty RP.  See the following example tasks to assist with your Microsoft Azure setup:
WebSphere traditional examples
  • Setting up the WebSphere traditional OIDC RP TAI to use the Google™ OP

    You can configure the WebSphere traditional OIDC RP to use the Google as the OP server. This example procedure assumes that you already have Google API credentials.

    If you don't have a Google Console project with web credentials or you don't know what they are, you can follow the procedure shown in the Setting up a Google™ API Console project to use the Google OP with a WebSphere traditional or Liberty OIDC RP procedure shown previously.

    See the following document provided by Google:
    Google Identity Platform, Google OpenID Connect

    You can set up or check your web client credentials with Google here:
    Google API Console, Credentials

    This procedure is a starting point for your OIDC configuration with the Google OP. You might want to consult the Configuring an OpenID Connect Relying Party topic in the IBM Documentation to read more about setting the com.ibm.websphere.security.InvokeTAIbeforeSSO security custom. Step 7 discusses the pros and cons of setting the property and step 8 describes how to set it.

    Perform the following steps to set up the OIDC TAI in WebSphere traditional to use Google for the OP:
    1. Browse to the Google discovery endpoint:
      https://accounts.google.com/.well-known/openid-configuration
    2. In a separate browser window, start the WebSphere traditional administrative console and login as administrator.
    3. Install the OIDC TAI application
      1. If you know that WebSphereOIDCRP.ear is installed, skip to the next major step.
      2. If you are not sure if WebSphereOIDCRP.ear is installed, do the following:
        1. Navigate to Applications > Application Types > WebSphere enterprise applications
        2. Check your application list for WebSphereOIDCRP.ear. If you find it, skip to the next major step.
      3. Click Install
      4. Click Browse
      5. Enter the path to (WAS_HOME)/installableApps. For example, c:\was90\WebSphere\AppServer\installableApps
      6. Select WebSphereOIDCRP.ear, then click Open
      7. Click Next through the subsequent panels, taking all defaults, then click Finish
      8. Click Save
    4. Configure the OIDC TAI for the Google OP
      1. Navigate to Security > Global security
      2. Under Authentication, click Web and SIP security > Trust association
      3. If 'Enable trust association' is not checked, do the following:
        1. Check Enable trust association
        2. Click Apply
      4. Click Interceptors
      5. If com.ibm.ws.security.oidc.client.RelyingParty is not listed, do the following:
        1. Click New
        2. Enter the following value for the Interceptor class name:
          com.ibm.ws.security.oidc.client.RelyingParty
        3. Click OK
      6. Click com.ibm.ws.security.oidc.client.RelyingParty
      7. Choose your provider prefix
        1. If you do not have any existing custom properties, use provider_1
        2. If you have existing custom properties that you do not want to use, remove them and use provider_1
        3. If you have existing custom properties and you want to keep them, choose a provider prefix that is not already used.
          • The rest of this example is assuming that you are using provider_1. Be sure to use the prefix that you chose instead of provider_1 when you enter your new properties.
      8. Do one of the following:
        • Preferred: Add the following custom property to specify the Google discovery endpoint URL to obtain most of the information required for the OIDC TAI configuration:
          Property Name Example value
          provider_1.discoveryEndpointUrl https://accounts.google.com/.well-known/openid-configuration
          Optionally, add this custom property if you do not want to invoke the userinfo endpoint after the user logs in:

          provider_1.userinfoEndpointEnabled          		 false
          When you use discovery, your minimum configuration is only five properties: identifier, discoveryEndpointUrl, clientId, clientSecret, and a filter.
        • -OR- Add the following set of custom properties; get the value for each property from the output from the discovery endpoint that you obtained on step #1.
          Property Name Attribute from discovery Example value
          provider_1.authorizeEndpointUrl authorization_endpoint https://accounts.google.com/o/oauth2/v2/auth
          provider_1.tokenEndpointUrl token_endpoint https://oauth2.googleapis.com/token
          provider_1.jwkEndpointUrl jwks_uri https://www.googleapis.com/oauth2/v3/certs
          provider_1.signatureAlgorithm id_token_signing_alg_values_supported RS256
          provider_1.issuerIdentifier issuer https://accounts.google.com
      9. Add the following set of custom properties that are specific to your Google web client credentials:
        Property Name Description
        provider_1.clientId Your Google Console web client's client ID
        provider_1.clientSecret Your Google Console web client's client secret
        provider_1.identifier This identifier is used to build the redirect URL. For example, with provider_1.identifier=abc, the redirect URL is https://(hostname):(port)/oidcclient/abc

        You register the redirect URL with your Google Console web client.
      10. Add one of the following custom properties that is specific to your application to ensure that the TAI intercept sthe request:
        Property Name Description
        provider_1.interceptedPathFilter Specifies a comma-separated list of regular expression patterns that are compared against the request URI to see whether the TAI intercepts the request. To intercept ALL requests use “/.*”.
        For example: /abcCompanyApps.*, /snoop
        provider_1.filter This property is used to specify a condition that is checked against the request to see whether the TAI protects this request. The format for this property is the same as for the SAML sso_<id>.sp.filter property.
        Example filters:
        For the application URL = https://(host):(port)/snoop and provider_1.identifier = ibmapp1        		 provider_1.filter=
        request-url^=ibmapp1|snoop
        provider_1.interceptedPathFilter=/snoop
      11. Click OK
    5. Add Google's SSL signer certificate
      1. Navigate to Security > SSL Certificate and Key Management > Keystores and Certificates
      2. Select one of the following:
        • If you are running on a stand-alone server, select NodeDefaultTrustStore
        • Otherwise, select CellDefaultTrustStore
      3. Click Signer certificates
      4. Click Retrieve from port, then enter the following information:
        Field Example value Instructions
        Host oauth2.googleapis.com Get the value for this property from the host name in the token_endpoint attribute in the output from the discovery endpoint that you obtained on step #1.
        Port 443
        Alias googleapis
      5. Click Retrieve signer information
      6. Click OK
    6. Add Google's realm as a WebSphere trusted realm:
      1. In the admin console, navigate to Security > Global Security
      2. Under user account repository, click Configure
      3. Under Related Items, click 'Trusted Authentication Realms - Inbound'
      4. Click Add External Realm
      5. Enter the following value:
        Example value Instructions
        https://accounts.google.com Get the value for this property from the issuer attribute in the output from the discovery endpoint that you obtained on step #1.
      6. Click OK
    7. Configure your application to trust the Google realm
      1. Navigate to Applications > Application Types > WebSphere enterprise applications
      2. Click your application
      3. Under Detail Properties, click 'Security role to user/group mapping'
      4. Check the JEE security role to which you'd like to map your WebSphere users and groups for this test.
        • If you are using the WebSphere DefaultApplication for this test, check 'All Role' in this step.
      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
    8. Click Save
    9. Restart the application server
    10. If you did not do so, register your redirect URL with your Google Console web client at Google API Console, Credentials:
      Value Sample value
      https://(hostname):(port)/oidcclient/(identifier) https://company.com:9443/oidcclient/client1
    11. Using a web browser, send a request to a URL that is protected by your OIDC RP with tfhe Google OP.
      • You see the Google login screen
      • If you don't get the login screen, skip the next step and proceed to debug.
    12. Login
      • You are redirected to your application
      • If you are not redirected to your application, see continue to the next step.
    13. If you encounter any issues, attempt to debug the problem
  • Setting up the WebSphere traditional OIDC RP TAI to use a Liberty OP

    If you do not already have a Liberty OP, perform the following steps:

    1. Install WebSphere® Liberty.
      1. Download the All GA Features package from openliberty.io into a new directory for your installation.
      2. Extract the downloaded file, for example 
        unzip openliberty-22.0.0.2.zip

        Any paths that follow in this example are relative to the directory that you created for your installation.
    2. Create the Liberty OpenID Connect Provider server
      From the wlp/bin directory, run the following command: 
      server create Liberty_OP
    3. Create the server.xml file for the OpenID Connect Provider.
      1. Change directory to the wlp/usr/servers/Liberty_OP directory.
      2. Replace the content of the server.xml file with the following content: 
        <server description="Liberty_OP">
    <featureManager>
        <feature>openidConnectServer-1.0</feature>
        <feature>appSecurity-2.0</feature>
    </featureManager> <!-- To access this server from anything other than localhost or the loopback address, add a host attribute to the following element, e.g. host="*" -->
    <httpEndpoint httpPort="9081" httpsPort="9444" id="defaultHttpEndpoint"/>
    <keyStore id="defaultKeyStore" password="Password"/>
    <basicRegistry>
        <user name="Jackson" password="Password"/>
        <user name="Andrea" password="Password"/>
    </basicRegistry>
    <openidConnectProvider id="OP" oauthProviderRef="oauth" signatureAlgorithm="RS256" jwkEnabled="true"/>
    <oauthProvider id="oauth">
        <localStore> <!-- The default redirect URL pattern is: https://<hostname>:<sslport>/oidcclient/<oidcClientID> -->
            <client name="WASRP" secret="password" scope="openid" redirect="https://localhost:9443/oidcclient/client1" />
        </localStore>
    </oauthProvider> <!-- To grant all authenticated users access to the OIDC protected resource, grant them the oauth-role authenticated -->
    <oauth-roles>
        <authenticated>
            <special-subject type="ALL_AUTHENTICATED_USERS"/>
        </authenticated>
    </oauth-roles>
    <logging traceFileName="trace.log" maxFileSize="20" maxFiles="10" traceFormat="BASIC" traceSpecification="*=info:com.ibm.ws.security.*=all: com.ibm.ws.webcontainer.security.*=all:com.ibm.oauth.*=all: com.ibm.wsspi.security.oauth20.*=all:org.apache.http.client.*=all"/>
</server>
      3. Find the redirect attribute on the oauthProvider > localStore > client entry. Replace localhost:9443 with the hostname and SSL port of your WebSphere traditional server.
    4. Create the default keystore and keys.
      From the wlp/bin directory, run the following commands: 
      server start Liberty_OP
server stop Liberty_OP
    5. Start your Liberty OP.
      From the wlp/bin directory, run the following commands: 
      server start Liberty_OP
     

    If you do not already have the OpenID Connect TAI configured on your WebSphere traditional server, perform the following steps:

    1. Start your WebSphere traditional application server.
    2. In a browser window, start the WebSphere traditional administrative console and login as administrator.
    3. Install the OIDC TAI application
      1. If you know that WebSphereOIDCRP.ear is installed, skip to the next major step.
      2. If you are not sure if WebSphereOIDCRP.ear is installed, perform the following steps:
        1. Navigate to Applications > Application Types > WebSphere enterprise applications
        2. Check your application list for WebSphereOIDCRP.ear. If you find it, skip to the next major step.
      3. Click Install
      4. Click Browse
      5. Enter the path to (WAS_HOME)/installableApps. For example, c:\was90\WebSphere\AppServer\installableApps
      6. Select WebSphereOIDCRP.ear, then click Open
      7. Click Next through the subsequent panels, taking all defaults, then click Finish
      8. Click Save
    4. 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 selected, select it, then click Apply
    5. Add the OpenID Connect Relying Party TAI as an interceptor
      1. Click Interceptors.
      2. If com.ibm.ws.security.oidc.client.RelyingParty is already in the list, skip to the next major step.
      3. Click New to add an interceptor.
      4. Enter the interceptor class name of com.ibm.ws.security.oidc.client.RelyingParty.
        • Custom properties are added later in this task.
      5. Click OK.
    6. Add the OpenID Connect Relying Party TAI class to com.ibm.websphere.security.InvokeTAIbeforeSSO
      1. Click Security > Global security > 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 property 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
    7. Click Save
     

    Configure the OIDC TAI to use your Liberty OP:

    1. Browse to the your Liberty OP's discovery endpoint:
      https://(liberty_hostname):(liberty_sslport)/oidc/endpoint/(provider_id)/.well-known/openid-configuration
      Using the Liberty server.xml in this example:
      https://(liberty_hostname):9444/oidc/endpoint/OP/.well-known/openid-configuration
    2. Determine your Liberty OP's realm name. Perform the following steps:
      1. Open the server.xml file for your Liberty server in an editor.
      2. Search for the basicRegistry entry. For example:
        <basicRegistry id="basic" realm="WebRealm">
      3. The realm name is:
        • The value for the "realm" attribute on the basicRegistry entry.
        • BasicRegistry if there is no "realm" attribute on the basicRegistry entry.
          • Since there is no realm attribute on the basicRegistry entry in the Liberty server.xml provided with this example, its realm name BasicRegistry.
    3. If your WebSphere traditional application server isn't already started, start it.
    4. In a browser window, start the WebSphere traditional administrative console and login as administrator.
    5. In the administrative console, click Security > Global security > Web and SIP security > Trust association > Interceptors > com.ibm.ws.security.oidc.client.RelyingParty
    6. Choose your provider prefix
      1. If you do not have any existing custom properties, use provider_1
      2. If you have existing custom properties that you do not want to use, remove them and use provider_1
      3. If you have existing custom properties and you want to keep them, choose a provider prefix that is not already used.
        • The rest of this example is assuming that you are using provider_1. Be sure to use the prefix that you chose instead of provider_1 when entering your new properties.
    7. Do one of the following:
      • Preferred: Add the following custom property to specify your Liberty discovery endpoint URL to obtain most of the information required for the OIDC TAI configuration:
        Property Name Example value
        provider_1.discoveryEndpointUrl https://acme.co:9444/oidc/endpoint/OP/.well-known/openid-configuration
        Optionally, add this custom property if you do not want to invoke the userinfo endpoint after the user logs in:

        provider_1.discoveryEndpointEnabled        		 false
        When you use discovery, your minimum configuration is only five properties: identifier, discoveryEndpointUrl, clientId, clientSecret, and a filter.
      • -OR- Add the following set of custom properties; get the value for each property from the output from the discovery endpoint that you obtained on step #1.
        Property Name Attribute from discovery Example value
        provider_1.authorizeEndpointUrl authorization_endpoint https://acme.co:9444/oidc/endpoint/OP/authorize
        provider_1.tokenEndpointUrl token_endpoint https://acme.co:9444/oidc/endpoint/OP/token
        provider_1.jwkEndpointUrl jwks_uri https://acme.co:9444/oidc/endpoint/OP/jwk
        provider_1.signatureAlgorithm id_token_signing_alg_values_supported RS256
        provider_1.issuerIdentifier issuer https://acme.co:9444/oidc/endpoint/OP
    8. Add the following set of custom properties for your client credentials:
      Property Name Description Value from sample server.xml file
      provider_1.clientId The client ID that is registered with the OP WASRP
      provider_1.clientSecret The client secret that is registered with the OP password
      provider_1.identifier This identifier is used to build the redirect URL. For example, with provider_1.identifier=client1, the redirect URL is https://(hostname):(port)/oidcclient/client1

      This redirect URL is registered with your Liberty OP.      		 client1
    9. Add one of the following custom properties that is specific to your application to ensure that the TAI intercepts the request:
      Property Name Description
      provider_1.interceptedPathFilter Specifies a comma-separated list of regular expression patterns that are compared against the request URI to see whether the TAI intercepts the request. To intercept ALL requests use “/.*”.
      For example: /abcCompanyApps.*, /snoop
      provider_1.filter This property is used to specify a condition that is checked against the request to see whether the TAI protects this request. The format for this property is the same as for the SAML sso_<id>.sp.filter property.
      Example filters:
      For the application URL = https://(host):(port)/snoop and
      provider_1.identifier = client1      		 provider_1.filter=
      request-url^=client1|snoop
      provider_1.interceptedPathFilter=/snoop
    10. Click OK
    11. Import your Liberty OP's signer certificate
      1. Navigate to Security > SSL Certificate and Key Management > Keystores and Certificates
      2. Select one of the following:
        • If you are running on a stand-alone server, select NodeDefaultTrustStore
        • Otherwise, select CellDefaultTrustStore
      3. Click Signer certificates
      4. Click Retrieve from port, then enter the following information:
        Field Example value Instructions
        Host acme.co Get the value for this property from the host name in the token_endpoint attribute in the output from the discovery endpoint that you obtained on step #1.
        Port 9444 Get the value for this property from the port in the token_endpoint attribute in the output from the discovery endpoint that you obtained on step #1.
        Alias libertyOp This is the alias name that you want to give the Liberty OP's signer certificate in your truststore.
      5. Click Retrieve signer information
        • You see the results of the retrieved signer information.
      6. Click OK 
    12. Add your Libert OP's realm as a WebSphere trusted realm:
      1. In the admin console, navigate to Security > Global Security
      2. Under user account repository, click Configure
      3. Under Related Items, click 'Trusted Authentication Realms - Inbound'
      4. Click Add External Realm
      5. Enter the value for your Liberty OP's realm that you determined at the beginning of this section.
        • If you are using the Liberty server.xml file in this example, the value is the default: BasicRegistry.
      6. Click OK
    13. Configure your application to trust your Liberty OP's realm
      1. Navigate to Applications > Application Types > WebSphere enterprise applications
      2. Click your application
      3. Under Detail Properties, click 'Security role to user/group mapping'
      4. Check the JEE security role to which you'd like to map your WebSphere user/groups for this test.
        • If you are using the WebSphere DefaultApplication, check 'All Role' in this step.
      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
    14. Click Save
    15. Restart the application server
     

    If you are using an existing Liberty OP instead of the sample one created in this example, register your redirect URL with your Liberty OP:

    1. Load the server.xml file for your Liberty OP into an editor
    2. Find the openidConnectProvider entry that is being used by your issuer, for instance:
      https://acme.co:9444/oidc/endpoint/OP
      would look similar to 
      <openidConnectProvider id="OP" oauthProviderRef="oauth" signatureAlgorithm="RS256" jwkEnabled="true"/>
    3. Find the OauthProvider associated with the OauthProviderRef, for instance 
      <oauthProvider id="oauth">
    4. To the localStore element in the referenced oauthProvider, add a client entry for your WebSphere traditional OIDC TAI RP. For example: 
      <!-- The default redirect URL pattern is: https://<hostname>:<sslport>/oidcclient/<oidcClientID> -->
<client name="WASRP" secret="password" scope="openid" redirect="https://localhost:9443/oidcclient/client1" />
     

    Test your configuration:

    1. Using a web browser, send a request to a URL that your OIDC RP has protected with your Liberty OP.
      • You see your Liberty login screen
      • If you don't get the login screen, continue to the next section to debug the problem.
    2. Login with a username and password that is valid for the Liberty OP
      • If you used the sample Liberty server.xml in this example, you can use Jackson and Password.
    3. Click of the buttons to allow consent
      • You are redirected to your application
      • If you are not redirected to your application, continue to the next section to debug the problem.
     

    If you encounter any issues, attempt to debug the problem:

    image 1414 If you get Error 403: Authentication Failed in the browser window, check for SSL errors:

    1. On your WebSphere traditional server, change directory to (profileRoot)/logs/ffdc
    2. Find the last ffdc file that contains the string "CWTAI2007E"
      [8/13/19 17:25:53:989 EDT] FFDC Exception:com.ibm.websphere.security.WebTrustAssociationFailedException SourceId:com.ibm.ws.security.web.WebAuthenticator.handleTrustAssociation ProbeId:519 Reporter:com.ibm.ws.security.web.WebAuthenticator@43905a69 com.ibm.websphere.security.WebTrustAssociationFailedException: CWTAI2007E: The OpenID Connect relying party (RP) encountered a failure during the login. The exception is [Failed to make a request to OP server]. Check the logs for details that lead to this exception.
    3. Look at the stack for entries like javax.net.ssl.SSLHandshakeException and java.security.cert.CertPathBuilderException
      • If you see one or more of these, go back to the section titled Configure the OIDC TAI to use your Liberty OP, then run the steps under Import your Liberty OP's signer certificate.
     

    image 1414 If you get an error from the OP that the redirectUrl is not recognized, check to see whether your redirect URI is configured correctly:

    CWOAU0062E: The OAuth service provider could not redirect the request because the redirect URI was not valid. Contact your system administrator to resolve the problem.
     
    1. Find the redirect to the OP in the trace; search for Redirect to OP.
      • The redirectUri parameter is in that string, or you can look backwards a couple of lines for getSigninCB, for example:
        [8/12/19 18:49:36:378 EDT] 000000cc RelyingParty > getSigninCB(HttpServletRequest) returns [https://company.com:9443/oidcclient/client1] Entry
    2. Check the client entry in your Liberty server.xml to make sure that the redirect attribute matches the one shown in the trace.
      • Use the section above titled If you are using an existing Liberty OP instead of the sample one created in this example, register your redirect URL with your Liberty OP to find the client entry.
      • If the redirect attribute does not match, do the following:
        1. Change the redirect attribute to the correct value.
        2. Save the file.
        3. Retest.
     

    image 1414 If you get a form login page that says Authentication Required

    • Check whether your Liberty OP's realm is configured correctly as a trusted realm on your WebSphere traditional server:
      1. Find the redirect to the OP in the trace; search for Redirect to OP.
      2. From that position, search for setIdToken; it is on a different thread.
        • On an app server with low activity, the web container might re-assign the same thread ID to the new thread.
      3. Look at the next line in the trace that shows the beautified ID token. For example:
        [8/13/19 16:06:57:877 EDT] 000000ae SessionData 3 id token[ header[{ "kid": "DR9l4WpaluKaCzJMGpkh", "alg": "RS256"}], claims[{"sub": "Jackson", "realmName": "BasicRegistry", "uniqueSecurityName": "Jackson", "at_hash": "jaiUAEmlqG6BbF34zDfqRw",
        "iss": "https://company.com:9444/oidc/endpoint/OP", "aud": "WASRP", "exp": 1565734017, "iat": 1565726817}]]
      4. Get the realm name from the ID token:
        • Use the value of the "realmName" claim if it exists; BasicRegistry in this example.
        • Use the value of the "iss" claim if the "realmName" claim does not exist.
      5. Check the trusted realms configured on your WebSphere traditional server:
        1. In the admin console, navigate to Security > Global Security
        2. Under user account repository, click Configure
        3. Under Related Items, click 'Trusted Authentication Realms - Inbound'
        4. Check whether the realm from your ID token is in the list. If not, add it:
          1. Click Add External Realm
          2. Enter the realm from your ID token.
          3. Click OK
          4. Click Save
          5. Restart the application server
          6. Retest
    • Check whether your application is configured for 'All Authenticated in Trusted Realms':
      1. In the admin console, navigate to Applications > Application Types > WebSphere enterprise applications
      2. Click your application
      3. Under Detail Properties, click 'Security role to user/group mapping'
      4. If you do not have your preferred JEE security role mapped to the Special subjects='All Authenticated in Trusted Realms', perform the following steps:
        1. Check the JEE security role to which you'd like to map your WebSphere user and groups for this test.
          • If you are using the WebSphere DefaultApplication for this test, check 'All Role' in this step.
        2. Click 'Map Special Subjects', then select 'All Authenticated in Trusted Realms'
        3. Click OK
        4. Click Save
        5. Restart the application server
        6. Retest
  • Setting up the WebSphere traditional OIDC RP TAI and your application to perform RP-Initiated logout

    You can enable programmatic logout for an application that is secured by the OpenID Connect (OIDC) Relying Party (RP) Trust Association Interceptor (TAI). When programmatic logout is enabled, logging out of the application clears any Open ID Connect cookies and Lightweight Third Party Authentication (LTPA) cookies. You can find the procedure in the Enabling programmatic logout for an OpenID Connect Relying Party IBM Docs article.

    When you enable programmatic logout in your application, however, it does not guarantee that a user is logged out of the OP.  The HttpServletRequest.logout() and form logout methods make the OIDC TAI remove the information to log out a single sign-on (SSO) user from the WebSphere Application Server. Some OpenID Connect providers leave information in the browser that keeps the user logged in to the OP to preserve the functions of SSO. If the user goes to a URL protected by the OP again, credentials are not needed even though the user logged out of the WebSphere Application Server. This behavior might not be desirable for some use cases.

    If you also want the user logged out of the OP, further configuration of the OIDC TAI is required.  You can find the procedure in the Configuring the OIDC TAI to perform RP-initiated logout IBM Docs article.

    • WebSphere OIDC RP-Initiated logout with a Liberty OP  (the easy way)

      In APAR PH48083 that is included in OIDC 1.4.0, WebSphere 8.5.5.23, and 9.0.5.14 and later, the RP-Initiated logout feature was added to the OIDC TAI.

      • There is a task in IBM DOCS that describes RP-Initiated logout at Configuring the OIDC TAI to perform RP-initiated logout.  
      • An example for configuring a WebSphere OIDC TAI to perform RP-Initiated logout with a Liberty OP are given later in this section.
      • If you have a Microsoft Azure OP, you can find example steps under What to do next in this document on github: Setting up Azure as an OIDC OP for WebSphere Application Server and Liberty clients.
      • When you use this "easy way" method, the choice for performing RP-Initiated logout is left up to the administrator.  All the application needs to do is the expected HttpServletRequest.logout().
        • When you use "the hard way" method, the application must know much more about logout and be tied directly to the WebSphere Application Server's OIDC TAI APIs to retrieve the user's id_token.

      Note the following are general steps WebSphere OIDC TAI to perform RP-Initiated logout with a Liberty OP and are not intended to be an operational example:

      1. Perform the steps previously described for Setting up the WebSphere traditional OIDC RP TAI to use a Liberty OP.
      2. Perform the steps for Enabling programmatic logout for an OpenID Connect Relying Party.
      3. Decide where you want your users to be redirected after logout.
        • You might want them redirected back to your login page, a "you are logged out" page, or your company's home page.
        • This example is using a company home page.
      4. Configure the logout landing page in your Liberty server's server.xml file with the postLogoutRedirectUris attribute.
        • The postLogoutRedirectUris attribute belongs to the oauthProvider > localStore > client entry and can be found on the OpenID Connect Server Provider (openidConnectProvider) IBM Docs page.
        • Example: 
          <client name="WASRP"
    secret="p"
    scope="openid"
    redirect="https://localhost:9443/oidcclient/client1"
    postLogoutRedirectUris="https://www.sampleco.com"/>
      5. Set the following OIDC TAI properties:
        provider_1.endSessionEndpointEnabled=true
        provider_1.endSessionRedirectUrl=https://www.sampleco.com
      6. Set the following global security custom property:
        com.ibm.websphere.security.allowAnyLogoutExitPageHost=true
      Result:
      When these steps are complete, when a protected endpoint invokes the HttpServletRequest.logout() method, the following flow is initiated:
      1. The user is logged out of WebSphere
        • The LTPA cookie is deleted (if present)
        • The OIDC session cookie is delted
      2. The logout request is redirected to the OP's end_session_endpoint for the OP to clean up it's data for the user. 
      3. The OP redirects the request to https://www.sampleco.com 
      4. Navigating to the app URL again requires an OP login.
    • WebSphere OIDC RP-Initiated logout with a Liberty OP  (the hard way)
      Instead of having the OIDC TAI perform the steps for RP-Initiated logout, your application can do the steps itself.  This procedure was required before the RP-Initiated logout feature was added to the OIDC TAI in APAR PH48083.  PH48083 is included in OIDC 1.4.0, WebSphere 8.5.5.23, and 9.0.5.14 and later.
      Outline:
      Here is an outline of the "hard way" RP-Initiated logout process; your application is responsible for providing the steps in red :
      1. Your application invokes the end_session_endpoint on the OP
        • Obtain the idToken using APIs, then pass it on the id_token_hint parameter
        • Pass your logout endpoint on the post_logout_uri parameter
      2. The OP cleans up it's data for the user
      3. The OP redirects to your logout URL
      4. Your logout URL is protected by the TAI and invokes HttpServletRequest.logout()
      5. The user is logged out of WebSphere
        • The LTPA cookie is deleted (if present)
        • The OIDC session cookie is deleted
      6. Navigating to the app URL again requires an OP login
      Procedure:
      Here are the "the hard way" steps required for your application and the WebSphere OIDC TAI to perform RP-Initiated logout with a Liberty OP. Note that these are general steps only and are not intended to be an operational example:
      1. Perform the steps previously described for Setting up the WebSphere traditional OIDC RP TAI to use a Liberty OP.
      2. Perform the steps for Enabling programmatic logout for an OpenID Connect Relying Party.
      3. Configure your logout endpoint in your Liberty server's server.xml file with the postLogoutRedirectUris attribute.
        • The postLogoutRedirectUris attribute belongs to the oauthProvider > localStore > client entry and can be found on the OpenID Connect Server Provider (openidConnectProvider) IBM Docs page.
        • Example: 
          <client name="WASRP"
    secret="p"
    scope="openid"
    redirect="https://localhost:9443/oidcclient/client1"
    postLogoutRedirectUris="https://localhost:9443/myApp/secure/logout.jsp"/>
      4. Enable your application to invoke your OP's end_session_endpoint .
        • You can refer to the OpenID Connect RP-Initiated Logout 1.0 specification.
        • Use the OidcClientHelper API to obtain the end_session_endpoint and idToken that you'll need for your request:
          String idToken = OidcClientHelper.getIdTokenFromSubject();
          String endSessionUrl = OidcClientHelper.getEndSessionEndpoint();
      5. Invoke the end session endpoint using the idToken and logout url:
        (endSessionUrl)?post_logout_uri=(your_logout_url)&id_token_hint=(idToken)
  Liberty examples
  • Setting up a Liberty OIDC RP to use the Google™ OP

    You can configure the Liberty OIDC RP to use the Google as the OP server. This example procedure assumes that you already have a Google Console project with web credentials.

    If you don't have a Google Console project with web credentials or you don't know what they are, you can follow the procedure outlined in the Setting up a Google™ API Console project to use the Google OP with a WebSphere traditional or Liberty OIDC RP procedure described previously in this document.

    See the following document provided by Google:
    Google Identity Platform, Google OpenID Connect

    You can set up or check your web client credentials with Google here:
    Google API Console, Credentials
     
    You can perform this task as a follow-on to the new IBM Docs task Getting started: Configuring an OpenID Connect Provider and Client in Liberty. This is an end-to-end task that takes you from installing Liberty and a sample application through configuring an OpenID Connect OP and RP.
    • If you have already run that task, you can continue with this task to configure your Liberty_RP server to use a Google OP.
    • If you have not, and you would like to run through steps to get a new Liberty instance, create an RP server and install a sample application:
      • You can run steps 1 through 7 on that document.
      • Skip all the steps and sub-steps that are related to the Liberty_OP since you are the Google OP instead.

    Perform the following steps to set up the Liberty OIDC RP to use Google for the OP:
    1. Browse to the Google discovery endpoint:
      https://accounts.google.com/.well-known/openid-configuration
    2. Set up your Liberty RP for SSL communication with the Google OP:
      1. Download the Google G3 signer certificate:
        1. In a browser, go to Google Trust Services, Repository of Documentation and Certificates
        2. Right click and download the DER file associated with GTS GIAG3
          • If you left click DER, the certificate is installed on your browser and that is not what you intend to do here.
          • The file name is GTSGIAG3.crt
      2. Import the Google G3 certificate into your Liberty RP server's keystore:
        1. Change directory to (install_dir)/wlp/usr/servers/(liberty_rp)/resources/security
        2. Run the following command to import the certificate: 
          keytool -importcert -keystore key.jks -storepass (password) -alias googleG3 -file (path)/GTSGIAG3.crt -noprompt
      3. Open the server.xml for your Liberty RP and note the value for the id attribute for openidConnectClient.
    3. Edit server.xml for your Liberty RP to communicate with the Google OP:
      1. Ensure that a value is provided for the host attribute on the httpEndpoint element. If you do not have a host attribute, add the following attribute and value pair:
        host="*"
      2. Add or update following set of attributes for openidConnectClient that are specific to your Google Console web client credentials:
        Property Name Description
        clientId Your Google Console web client's client ID
        clientSecret Your Google Console web client's client secret
      3. Do one of the following:
        • If you are running Liberty fix pack 19.0.0.1 or later, instead of configuring each attribute individually, you can configure the OpenID Connect to obtain settings from Google's discovery endpoint. Add the following following attribute to your openidConnectClient configuration:
          Property Name Value
          discoveryEndpointUrl https://example.server.com/oidc/op/.well-known/openid-configuration
        • Add or update following set of attributes for your openidConnectClient configuration; get the value for each property from the output from the discovery endpoint that you obtained on step #1:
          Property Name Attribute from discovery Example value
          authorizeEndpointUrl authorization_endpoint https://accounts.google.com/o/oauth2/v2/auth
          tokenEndpointUrl token_endpoint https://oauth2.googleapis.com/token
          jwkEndpointUrl jwks_uri https://www.googleapis.com/oauth2/v3/certs
          signatureAlgorithm id_token_signing_alg_values_supported RS256
          issuerIdentifier issuer https://accounts.google.com
    4. If you have not done so, register your redirect URL with your Google Console web client at Google API Console, Credentials:
      Value Example Value Description
      https://(host):(port)/oidcclient/recirect/(id) https://company.com:9443/oidcclient/recirect/rp1 The id attribute from your openidConnectClient configuration must used to build your redirect URL.

      Following are examples of openidConnectClient configurations that shows where you would obtain the id attribute:
      Example 1 
      <openidConnectClient id="rp1" clientId="(googleClientId)" clientSecret="(googleClientSecret)"
authorizationEndpointUrl="https://accounts.google.com/o/oauth2/v2/auth"
tokenEndpointUrl="https://oauth2.googleapis.com/token"
jwkEndpointUrl="https://www.googleapis.com/oauth2/v3/certs"
signatureAlgorithm="RS256"
issuerIdentifier="https://accounts.google.com" >
      Example 2 
      <openidConnectClient 
id="rp2" 
clientId="(googleClientId)" 
clientSecret="(googleClientSecret)"
discoveryEndpointUrl="https://example.server.com/oidc/op/.well-known/openid-configuration" >
    5. Using a web browser, send a request to a URL that your Liberty OIDC RP protected by using the Google OP.
      • You see the Google login screen
      • If you don't get the login screen, skip the next step and proceed to debug.
    6. Login
      • You are redirected to your application
      • If you are not redirected to your application, see continue to the next step.
    7. If you encounter any issues, attempt to debug the problem
  • Setting up a Liberty OIDC RP for RS256
    Both the Liberty OpenID Connect RP and OP default to using HS256 (HMAC with SHA-256) for the signature algorithm. Your RP signature algorithm must match the OP's signature algorithm and many OPs do not support HS256. To update your Liberty OIDC RP to use RS256, do the following:
    1. Edit the server.xml for your OpenID Connect RP.
    2. To the openidConnectClient element, add the following attribute/value pair:
      signatureAlgorithm="RS256"
    3. Do at least one of the following:
      • If your OP supports a JWK endpoint, configure your RP to use it:
        • Add the following attribute to your openidConnectClient configuration:
          Value Description
          jwkEndpointUrl Specifies the OP's JWK endpoint URL.
      • Configure the RP to use a local key:
        • Add the following attributes to your openidConnectClient configuration:
          Value Description
          trustStoreRef The keystore that contains the public key necessary for verifying the signature of the ID token.
          trustAliasName Key alias name to locate public key for signature validation with asymmetric algorithm. The public certificate of the OP's private key that was used to produce the signature.
  Liberty sample links
 
Topic
Description
Getting started: Configuring an OpenID Connect Provider and Client in Liberty This IBM Docs end-to-end example helps you get familiar with configuring OpenID Connect (OIDC) in Liberty since it takes you from installing Liberty through configuring OpenID Connect.
Configuring an OpenID Connect Provider in Liberty This IBM Docs task shows how to set up an OpenID provider in Liberty.
Configuring an OpenID Connect Client in Liberty This IBM Docs task shows how to set up an OpenID client, or Relying Party, in Liberty.
How to learn and use WebSphere Liberty OpenID Connect The IBM Developer article presents some basic OpenID connect concepts and actions.
Single sign-on with Google on Liberty This IBM Developer article shows how to configure a Liberty RP to use Google for the OP. It is an end-to-end task that uses a sample application.
Configuring an HTTP Server to use Liberty as OpenID Connect Provider This IBM Developer article shows how to configure Apache mod_auth_openidc to work with the Liberty OpenID Connect provider.
Configuring an OpenID Connect Provider to use the RSA-SHA256 algorithm for signing of ID tokens This IBM Docs task describes how to configure your Liberty OP to use HS256.
Note: This document uses the term WebSphere traditional to refer to WebSphere Application Server v9.0 traditional, WebSphere Application Server v8.5 full profile, WebSphere Application Server v8.0 and earlier, WebSphere classic, traditional WebSphere, traditional WAS and tWAS.
 

[{"Line of Business":{"code":"LOB67","label":"IT Automation \u0026 App Modernization"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"ARM Category":[{"code":"a8m50000000CdESAA0","label":"Security-\u003ESSO-\u003EOpenId Connect"}],"ARM Case Number":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"8.5.5;9.0.0;CD0"}]

Document Information

Modified date:
14 February 2024

UID

swg22014332

Page Feedback