Getting started: Configuring an OpenID Connect Provider and Client in Liberty

This 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. The result is that client applications can verify the identity of a user by relying on authentication from an OpenID Connect Provider.

About this task

You can set up an OpenID Connect Provider and OpenID Connect Relying Party by completing these steps in the following procedure:
  1. Install Liberty.
  2. Create two servers.
  3. Download and install an IBM®-provided test application that includes the Snoop servlet.
  4. Configure the OpenID Connect Provider and OpenID Connect Relying Party to communicate with each other by using the localhost host name.
  5. Log in.
  6. Edit the OpenID Connect Provider and OpenID Connect Relying Party configurations to use your real host name.
  7. Log in.
The following points explain what is happening in the procedure:
  • The OpenID Connect Relying Party server and the OpenID Connect Provider server both run on the same system.
  • The OpenID Connect Relying Party server and the OpenID Connect Provider server start with the localhost host name. They do so to overcome issues that your system might have with a host that allows outside connections to itself.
  • A file-based registry is hardcoded in the server.xml file for the OpenID Connect Provider server. It contains two entries for the user name and password. One is for the Jackson user name and the Password password. The other is for the Andrea user name and the Password password. In a production environment, you might instead, for instance, use the LDAP User Registry since users authenticate to an OpenID Connect Provider. An OpenID Connect Provider is required to have a registry. The OpenID Connect Relying Party does not need a registry because it trusts the user artifacts, for instance tokens, that it gets from the OpenID Connect Provider.
  • The default keystores use plain text passwords. You can generate an encoded and encrypted password by using the securityUtility command.
  • The HS256 signature algorithm is used for simplicity. Support for the HS256 signature algorithm is not mandatory in the OpenID Connect specification. Many OpenID Providers do not support the HS256 signature algorithm.
  • You put the test application in the dropins directory for expedience, but avoid this practice in a production environment.
  • The OIDC trace is enabled so that you can view the trace.log file of the server if you encounter errors.

Procedure

  1. Install a Liberty Server.
    1. Download the WebSphere® Application Server Liberty .zip file.
      If you have an IBM login with entitlement, you can download Liberty from IBM Fix Central. Alternatively, you can download Liberty for developers. Choose one of the following options:
      Option 1: Obtain Liberty from IBM Fix Central with your IBM login.
      1. Navigate to Fix Central.
      2. In the Filter your content section, under the And Fix type filter criteria, select fix pack. This section includes options for both fix pack, in lowercase, and for Fix Pack. Select the lowercase fix pack option, not Fix pack.
      3. Under And Applies to filter criteria, scroll to the end of the list and click the highest fix pack number. For example.23.0.0.3.
      4. Click Submit.
      5. In the Filter fix details field, specify the following content.
        wlp-webprofile8
      6. From the resulting list of packages, select and download into a new directory the appropriate package for your workstation, for example wlp-webProfile8-23.0.0.3 or wlp-webProfile8-java8-win-x86_64-23.0.0.3.

        If you are not already logged in, you are prompted for your IBM ID credentials.

      Option 2: Obtain Liberty for developers
      1. Navigate to WebSphere Liberty for developers.
      2. Find the Download Package section at the end of the page.
      3. Download the package that most closely matches your system.
    2. Extract the downloaded file.
      For example, run the following command:
      unzip wlp-webProfile8-23.0.0.3
    3. Run the following commands from the wlp/bin directory: 
      featureUtility installFeature openidConnectClient-1.0
featureUtility installFeature openidConnectServer-1.0
  2. Download the sample Liberty default application.

    This default application is in the libertyDefaultApplication.ear file and contains the Snoop servlet that you use in this example procedure.

    If clicking the download link in this step does not download the file to your computer, right-click the link and select a Download or Save option for your browser. Alternatively, navigate to the parent directory, right-click the libertyDefaultApplication.ear file and select a Download or Save option for your browser.

  3. Create the Liberty servers.
    1. Create the OpenID Connect Relying Party server.
      Run the following command from the wlp/bin directory:
      server create Liberty_RP
    2. Create the OpenID Connect Provider server.
      Run the following command from the wlp/bin directory:
      server create Liberty_OP
  4. Create the server.xml file for the OpenID Connect Relying Party server.
    1. Change to the wlp/usr/servers/Liberty_RP directory.
    2. Replace the content of the server.xml file with the following content: 
      <server description="Liberty_RP">
    <featureManager>
        <feature>openidConnectClient-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"></keyStore>
    <openidConnectClient id="RP"
        clientId="oidcclient"
        clientSecret="password"
        authorizationEndpointUrl="https://localhost:9443/oidc/endpoint/OP/authorize"
        tokenEndpointUrl="https://localhost:9443/oidc/endpoint/OP/token" >
    </openidConnectClient>
    <logging  traceSpecification="*=info:
com.ibm.ws.security.*=all:com.ibm.ws.webcontainer.security.*=all:com.ibm.oauth.*=all:com.ibm.wsspi.security.oauth20.*=all:com.ibm.ws.transport.http.*=all:org.apache.http.client.*=all" traceFileName="trace.log" maxFileSize="20" maxFiles="10" traceFormat="BASIC" />
</server>
  5. Create the server.xml file for the OpenID Connect Provider.
    1. Change 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="9080" httpsPort="9443" id="defaultHttpEndpoint"/>
    <keyStore id="defaultKeyStore" password="Password"/>
    <basicRegistry>
        <user name="Jackson" password="Password"/>
        <user name="Andrea" password="Password"/>
    </basicRegistry>
    <openidConnectProvider id="OP" oauthProviderRef="oauth"/>
    <oauthProvider id="oauth">
        <localStore>
            <!-- The default redirect URL pattern is: https://<hostname>:<sslport>/oidcclient/redirect/<openidConnectClientID> -->
            <client name="oidcclient"  secret="password" scope="openid" redirect="https://localhost:9444/oidcclient/redirect/RP" />
        </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  traceSpecification="*=info:
com.ibm.ws.security.*=all:com.ibm.ws.webcontainer.security.*=all:com.ibm.oauth.*=all:com.ibm.wsspi.security.oauth20.*=all:com.ibm.ws.transport.http.*=all:org.apache.http.client.*=all" traceFileName="trace.log" maxFileSize="20" maxFiles="10" traceFormat="BASIC" />
</server>
  6. Create the default keystores and keys.
    Run the following commands from the wlp/bin directory:
    server start Liberty_RP
server stop Liberty_RP
server start Liberty_OP
server stop Liberty_OP
  7. Add the signer certificate for the Liberty_OP server to the Liberty_RP server as a trusted certificate.
    1. Export the personal certificate from the keystore of the Liberty_OP server.
      1. Change the directory to wlp/usr/servers/Liberty_OP/resources/security.
      2. Export the default personal certificate of the Liberty_OP server:
        keytool -exportcert -keystore key.p12 -storepass Password -alias default -file libertyOP.cer
        If you are using the JKS keystore through 19.0.0.2, use your default keystore file, for instance, the key.jks file.
        keytool -exportcert -keystore key.jks -storepass Password -alias default -file libertyOP.cer
        This default personal certificate for the Liberty_OP server is a signer certificate.
    2. Import the signer certificate from the Liberty_OP server into the keystore of the Liberty_RP server.
      1. Copy the libertyOP.cer file to the wlp/usr/servers/Liberty_RP/resources/security directory.
      2. Change the directory to wlp/usr/servers/Liberty_RP/resources/security.
      3. Run the following command to do the import: 
        keytool -importcert -keystore key.p12 -storepass Password -alias libertyop -file libertyOP.cer -noprompt
        If you are using the JKS keystore through 19.0.0.2, use your default keystore file, for instance, the key.jks file.
        keytool -importcert -keystore key.jks -storepass Password -alias libertyop -file libertyOP.cer -noprompt
    3. Optional: View the keystore of the Liberty_RP server: 
      keytool -list -v -keystore key.p12 -storepass Password
      If you are using the JKS keystore through 19.0.0.2, use your default keystore file, for instance, the key.jks file.
      keytool -list -v -keystore key.jks -storepass Password
  8. Install the Liberty default application onto the Liberty_RP server.

    Copy the libertyDefaultApplication.ear file that you downloaded in a previous step to the wlp/usr/servers/Liberty_RP/dropins directory.

  9. Start the Liberty_OP server and the Liberty_RP server.
    Run the following commands from the wlp/bin directory:
    server start Liberty_RP
server start Liberty_OP
  10. Open the login page of the Liberty_RP server.
    1. In the address bar of your browser, enter the URL of the Liberty_RP server: 
      http://localhost:9081/snoop
    2. Press Enter.

      A login window displays.

      Important: If you get a browser warning that the connection is not secure, go through steps in your browser to allow the connection.
  11. Log in to the Liberty_OP server and authorize the Liberty_RP server.
    1. Authenticate the user to the Liberty_OP server.
      1. Log in with Jackson as the user name and Password as the password.
      2. Click Login.

        The Allow client to access the following data page displays with the openid entry checked.

    2. Authorize the Liberty_OP server to allow the Liberty_RP server access to the user's personal information.

      Click Allow once or Allow, remember my decision.

      Important: If you get a browser warning that the connection is not secure, go through steps in your browser to allow the connection. You might receive this warning because the keystores used by the httpEndpoint element on both the Liberty_RP server and the Liberty_OP server contain only self-signed certificates.
    If you successfully log in, the Snoop servlet displays on the Snoop Servlet - Request/Client Information page.
    Important: To log in again, complete at least one of the following options:
    • Log in from a different browser product.
    • Clear your cookies in the current browser and follow the previous steps about logging in.
    • Close all windows of the browser that you used to log in, reopen the browser, and log in.
    • Restart the Liberty_RP server and then follow the previous steps about logging in.
  12. Fully qualify your server names.
    1. Change the localhost host name in the server.xml file of the Liberty_RP server to its fully qualified name.
      1. Edit the wlp/usr/servers/Liberty_RP/server.xml file.
      2. Add the following attribute to the httpEndpoint element: host="*".
      3. Change the authorizationEndpointUrl and tokenEndpointUrl attributes of the openidConnectClient element to use your server host name instead of the localhost host name.

        The following example code specifies the fully qualified server host name:

        <openidConnectClient id="RP"
    clientId="oidcclient"
    clientSecret="password"
    authorizationEndpointUrl="https://wks1.acme.com:9443/oidc/endpoint/OP/authorize"
    tokenEndpointUrl="https://wks1.acme.com:9443/oidc/endpoint/OP/token" >
</openidConnectClient>
      4. Save the file.

        When you save the file, a Liberty configuration change is triggered so that you do not have to restart the server.

    2. Change the localhost host name in the server.xml file of the Liberty_OP server to its fully qualified name.
      1. Edit the wlp/usr/servers/Liberty_OP/server.xml file.
      2. Add the following attribute to the httpEndpoint element: host="*".
      3. Change the redirect attribute of the client element (oauthProvider/localStore/client) to use your fully qualified server host name instead of the localhost host name.
        The following example code specifies the full-qualified server host name:
        <client name="oidcclient" secret="password" scope="openid" redirect="https://wks1.acme.com:9444/oidcclient/redirect/RP" />
      4. Save the file.

        When you save the file, a Liberty configuration change is triggered so that you do not have to restart the server.

  13. Open the login page by using the fully qualified host name.
    1. In the address bar of a browser, enter the URL that includes the Liberty_RP server:
      http://<host_name>:9081/snoop
    2. Press Enter.

      A login window displays.

      Important: If you get a browser warning that the connection is not secure, go through steps in your browser to allow the connection.
  14. Log in to the Liberty_OP server and authorize the Liberty_RP server.
    1. Authenticate the user to the Liberty_OP server.
      1. Log in with Jackson as the user name and Password as the password.
      2. Click Login.

        The Allow client to access the following data page displays with the openid entry checked.

    2. Authorize the Liberty_OP server to allow the Liberty_RP server access to the user's personal information.

      Click Allow once or Allow, remember my decision.

      Important: If you get a browser warning that the connection is not secure, go through steps in your browser to allow the connection. You might receive this warning because the keystores used by the httpEndpoint element on both the Liberty_RP server and the Liberty_OP server contain only self-signed certificates.
    If you successfully log in, the Snoop servlet displays on the Snoop Servlet - Request/Client Information page.

Results

You have a Liberty server that contains the Snoop servlet that is protected by an OpenID Connect Relying Party. The OpenID Connect Relying Party uses your OpenID Connect Provider for authentication.

Table 1. Question about the results
Question Answer
Why was the test application protected by the OpenID Connect Relying Party even though the Snoop servlet and the libertyDefaultApplication test application are not mentioned in the OpenID Connect configuration? The test application was protected because its web.xml file contains a security constraint that any Java™ EE security-enabled container supports. When the OpenID Connect Relying Party is running on Liberty, by default the Relying Party attempts to authorize all requests to any URL that has security constraints. Since the test application has security constraints on the URL that is being used, the Relying Party authorizes the requests.