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 that allows you to use 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 further, see the following document provided by Google: Google Identity Platform, OpenID Connect.


    A video for doing these actions is available in the next section. That video was not created using this document.

    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 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 will display; answer the questions and click ACCEPT.
        • If you don't get this page, then you've logged in to the Google API Console with this Google ID before. You may have to run one of the other two procedures below.
    2. Since you've never created a project before, you'll 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 will be 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've 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 may not have used the Google API Console with this Google ID before. Do one of the following:
        • Login with a different Google ID that has used the Google API Console before.
        • Go back and use the Get Started procedure instead.
        • Proceed to the next step if you know for sure that you have used this Google ID with the Google API Console before; Google may have just 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 will be 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 will be 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've 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 may not have used the Google API Console with this Google ID before. Do one of the following:
        • Login with a different Google ID that has used the Google API Console before.
        • Go back and use the Get Started procedure instead.
        • Proceed to the next step if you know for sure that you have used this Google ID with the Google API Console before; Google may have just 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 will display
      • You will need this information when configuring your OIDC RP. You don't have to copy it now; you will 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 just created, for example, Web client 1
     
    • At the top, you'll 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.
  • Video: OpenID Quick Setup with Google
    The following video is an end-to-end task for using the Google OP with a Liberty RP. The steps performed in the Google console in this video apply to both Liberty and WebSphere traditional.

    This video was not created by using this document. It assumes that you've used the Google Console previously; Google takes you through a different path if you've never used the console before. Also, the Liberty steps gloss over some points, such as for obtaining and installing the SSL certificates. The manual steps in other sections of this document are complete.

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 outlined in the Setting up a Google™ API Console project to use the Google OP with a WebSphere traditional or Liberty OIDC RP procedure above.

    Please 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 may 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 you have WebSphereOIDCRP.ear installed, skip to the next major step.
      2. If you are not sure if you have WebSphereOIDCRP.ear 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 will be using provider_1. Be sure to use the prefix that you chose instead of provider_1 when entering 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.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://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 will 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 will intercept 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 will intercept 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 user/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 haven't already done 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 your OIDC RP has protected using the Google OP.
      • You should get the Google login screen
      • If you don't get the login screen, skip the next step and proceed to debug.
    12. Login
      • You should be 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 you have WebSphereOIDCRP.ear installed, skip to the next major step.
      2. If you are not sure if you have WebSphereOIDCRP.ear 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 will be 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.ws.security.oidc.client.RelyingParty 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. Bring up the server.xml 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 will be 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/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 will intercept 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 will intercept 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 should 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 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 using your Liberty OP.
      • You should get 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 should be 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 if 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 if 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 should be on a different thread.
        • On an app server with low activity, the web container my 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 if 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 if 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/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 how to do this in the Enabling programmatic logout for an OpenID Connect Relying Party IBM Docs article.

    Enabling programmatic logout, however, does not enable you to log out from your OP. You can perform RP-Initiated logout using an OP's end_session_endpoint. Here is an example of the discovery output from an OP that contains an end_session_endpoint: https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. If you set up a Liberty OP, it also has an end_session_endpoint.

    In order to perform RP-Initiated logout, in addition to performing the steps required to Enable programmatic logout for an OpenID Connect Relying Party, your application also needs to invoke the OPs end_session_endpoint itself. Here is an outline of the 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
    2. The OP does whatever it needs to do to log out the user
    3. The OP redirects to your configured logout URL
    4. Your logout URL is protected by the TAI and invokes HttpServletRequest.logout()
    5. The TAI does whatever it needs to do to clean up the WebSphere side
    6. Navigating to the app URL again requires an OP login

    WebSphere OIDC RP-Initiated logout with a Liberty OP

    Here are the 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
  • Video: OpenID Connect Quick Setup for Liberty
    This video is an OpenID tutorial, providing OpenID concepts and the steps required to get an OpenID OP and RP up and running on Liberty.

  • 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 above.

    Please 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.
      • You should skip all the steps and sub-steps that are related to the Liberty_OP since you will be using 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 will be 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/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. If you want to do this, 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 haven't already 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 has protected using the Google OP.
      • You should get the Google login screen
      • If you don't get the login screen, skip the next step and proceed to debug.
    6. Login
      • You should be 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 containing 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. This is 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":"LOB45","label":"Automation"},"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:
27 February 2022

UID

swg22014332