Configuring an OpenID Connect Client in Liberty

You can configure a Liberty server to function as an OpenID Connect Client, or Relying Party, to take advantage of web single sign-on and to use an OpenID Connect Provider as an identity provider.

[22.0.0.1 and later]Open Liberty Documentation for configuring an OpenID Connect Client in Liberty can be found on the Open Liberty website.

About this task

You can configure a Liberty server to act as an OpenID Connect Client by enabling the openidConnectClient-1.0 feature in Liberty, and in addition to other configuration information.

Note: To configure a client to accept JWT Tokens directly, see Configuring JSON Web Token authentication for OpenID Connect

Procedure

  1. Add the openidConnectClient-1.0 Liberty feature and any other needed features to the server.xml file. The transportSecurity-1.0 feature is also required for the openidConnectClient-1.0 feature. Add the following element declaration inside the featureManager element in your server.xml file:
    <feature>openidConnectClient-1.0</feature>
    <feature>transportSecurity-1.0</feature>
  2. Configure an openidConnectClient element.
    • Configure an openidConnectClient element that works with the default Liberty server OpenID Connect Provider. The following is an example of a minimal configuration that works with the default OpenID Connect Provider.

      The client must have a configured application available at the given URL pattern that can handle redirect requests from an OpenID Connect Provider. This URL must also precisely match the redirect URL registered for the client with the OP.

      Avoid trouble:

      If you are using an outbound proxy, note that the OpenID Connect RP does not provide a means to route requests through a proxy host automatically.

      If you must use a proxy to access the OpenID Connect Provider (OP), the value that you enter for any OP-related URL property must contain the proxy host and port, not the external OP host and port. In most cases, you can replace the OP host and port with the proxy host and port. The URL that you enter must be visible to both the RP and client (browser or application). For further guidance on how to determine the correct URL to use, contact your proxy administrator.

      In this example, the client expects the SSL port to be set to 443.

      <openidConnectClient id="client01"
          clientId="client01"
          clientSecret="{xor}LDo8LTor"
          authorizationEndpointUrl="https://server.example.com:443/oidc/endpoint/OidcConfigSample/authorize"
          tokenEndpointUrl="https://server.example.com:443/oidc/endpoint/OidcConfigSample/token">
      </openidConnectClient>
      In this sample minimal configuration, the following default values are assumed:
      • scope=openid profile: The scope of openid is required, and you can use the scope attribute to edit required scopes. For example, you can change the required scope to openid profile email.
      • This RP registers its redirect URL with the OP as https://<host name>:<ssl port>/oidcclient/redirect/client01, where both the host name and ssl port are automatically resolved, and client01 is the id of the openidConnectClient configuration element. If there is a proxy in front of the RP, you can override the host name and port with the attribute redirectToRPHostAndPort, and set redirectToRPHostAndPort to https://<host name>:<ssl port>.
    • Configure an openidConnectClient element with discovery. The following example shows a minimal configuration that automatically discovers the OpenID Connect provider.
      <openidConnectClient id="RP"
          clientId="ebb996943plm4450bdb674c211a9fab0"
          clientSecret="g12ciZL1zsVYk6yXTMa2iopa8TBwC178CGq42mdJCALYCdQT1kE1ecB010GE"
          discoveryEndpointUrl="https://example.server.com/oidc/endpoint/OidcConfigSample/.well-known/openid-configuration">
      </openidConnectClient>

      If a discovery endpoint is configured, other configured OIDC endpoints are ignored. All endpoints are replaced with the following discovered endpoints: "issuer", "authorization_endpoint", "token_endpoint", "userinfo_endpoint", "jwks_uri", and "revocation_endpoint".

  3. Configure a user registry. User identities that are returned by the OP are not mapped to a registry user by default, so no users are required to be configured in the registry. However, if the mapIdentityToRegistryUser attribute of the openidConnectClient element is set to true, there must be a user entry for the appropriate identity that is returned from the OP in order for authentication and authorization to succeed. For more information about configuring a user registry, see Configuring a user registry in Liberty.
  4. Configure the truststore of the server to include the signer certificates of the OpenID Connect Providers that are supported. For more information about keystores, see Enabling SSL communication in Liberty and Adding trusted certificates in Liberty.
  5. Modify the SSL configuration of the server to use the configured truststore.
    <sslDefault sslRef="DefaultSSLSettings" />
    <ssl id="DefaultSSLSettings" keyStoreRef="myKeyStore" trustStoreRef="myTrustStore" />
    <keyStore id="myKeyStore" password="{xor}EzY9Oi0rJg==" type="jks" location="${server.config.dir}/resources/security/BasicKeyStore.jks" />
    <keyStore id="myTrustStore" password="{xor}EzY9Oi0rJg==" type="jks" location="${server.config.dir}/resources/security/BasicTrustStore.jks" />

    OpenID Connect is configured to use the default SSL configuration that is specified by the server. Therefore, the default SSL configuration for the server must use the truststore that is configured for OpenID Connect.

    In addition to using the SSL default configuration as shown in the example, an outbound default SSL configuration can be configured on the sslDefault element with the outboundSSLRef attribute. If the outbound default attribute is specified, then the SSL configuration that is specified by the outboundSSLRef attribute is used for outbound connections. You can override the default and specify the host and port to use for an outbound connection by using outbound SSL filters in the SSL configuration. For more information, see Outbound filters for SSL configurations and Configuring SSL settings for outbound communications.

  6. Optional: Configure a third-party OpenID Connect provider.

    To configure the Liberty OpenID Connect client to use a third-party OpenID Connect Provider such as (Microsoft Azure or Google), you must configure the following attributes. The attribute values can be obtained by calling the OP's discovery endpoint, which provides a JSON document at the path that is formed by concatenating the string /.well-known/openid-configuration to the issuer.

    1. Set the jwkEndpointUrl attribute to the URL of the OP's JSON Web Key Set JWK document that is defined asjwks_uri in the discovery file. For example, to use Google's OP, you can set jwkEndpointUrl = "https://www.googleapis.com/oauth2/v2/certs".
    2. Set the issuerIdentifier attribute to the issuer as defined in the discovery file. An ID Token that does not contain this value as an iss claim is rejected. For example, you can set issuerIdentifier="accounts.google.com" if you are using Google as your OP.
    3. Set signatureAlgorithm="RS256". The Liberty OpenID Connect client's default signature algorithm is HS256.
    4. Set the userIdentityToCreateSubject attribute to a claim name used by the vendor's ID Token that represents a user's unique identifier. For example, you can set userIdentityToCreateSubject ="email" if you are using Google's OP, and userIdentityToCreateSubject ="upn" or userIdentityToCreateSubject ="unique_name" if you are using Microsoft Azure.
    5. Set the groupIdentifier attribute to the claim name that represents the user's group memberships or roles. For example, you can set groupIdentifier="groups" if you are using Microsoft Azure.

    For more OpenID Connect Client configuration options, see OpenID Connect Client.

  7. Optional: Authentication Filter.

    When the openidConnectClient-1.0 feature is enabled and the openidConnectClient element is not configured with an authFilterRef attribute, any unauthenticated request is authenticated through the OpenID Connect provider.

    For more information on configuring the authentication filter, see Authentication Filters.

  8. Support multiple OpenID Connect Providers.

    You can configure Liberty as an OpenID Connect Relying Party to multiple OpenID Connect Providers by creating multiple openidConnectClient elements and multiple Authentication Filters. Each openidConnectClient element defines one Single-Sign-On relationship with one OpenID Connect Provider, and use the authFilterRef attribute to reference to one Authentication Filter.

  9. Configure a supported ID Token signature algorithm.

    You can configure a Liberty OpenID Connect client to support the RS256 signature algorithm in an ID Token. The Liberty OpenID Connect client's default signature algorithm is HS256. If you configure RS256 as the ID Token's signature algorithm by setting signatureAlgorithm="RS256", you must configure both the trustStoreRef and trustAliasName, unless the OP supports a JWK endpoint.

  10. Optional: Configure an implicit grant type.

    The openidConnectClient-1.0 feature uses an Authorization Code grant type to request a user authentication token, and you can configure the Liberty openidConnectClient-1.0 feature to use an implicit grant type by adding grantType="implicit" to the server.xml file. If your Liberty server and OpenID Connect provider are in different firewalls, you must use this configuration option.

  11. Optional: The Liberty OpenID Connect relying party automatically creates a single-sign-on (SSO) token after the ID Token is processed. You can configure Liberty to not create an SSO token for the server, or an SSO token for the resource that is protected with OpenID Connect by adding the configuration property disableLtpaCookie="true". If setting disableLtpaCookie="true", then the Liberty OpenID Connect client will only accept authentication requests that have previously authenticated with the configured OpenID Connect provider, and the authentication session lifetime is limited to the ID Token's life time.
  12. Optional: You can configure an OpenID Connect Client to optionally accept a valid OAuth 2.0 bearer access token as an authentication token without redirecting the request to an OpenID Connect provider. If a request contains a valid OAuth 2.0 bearer access token, then the Liberty OpenID Connect Client will automatically validate the access token, and create an authenticated subject based on the token validation result. If the request does not contain an access token or the access token is invalid, then the Liberty OpenID Connect Client continues to redirect the user to an OpenID Connect provider. This function enables the Liberty server to serve both the browser client and non-browser client like a RESTful client. You can add inboundPropagation="supported" to the configuration to enable this function.
  13. If your hosting environment does not allow access to the /oidcclient context root, modify the context root by configuring the oidcClientWebapp element.

    By default, the Liberty OpenID Connect Client's redirect servlet listens on the /oidcclient context root, and its redirect URL format is https://<host_name>:<ssl_port>/oidcclient/redirect/<configuration_ID>. If you cannot use this context root, set a different context root in the server configuration.

    For example, if your hosting environment requires that you use the /acme/openid context root, add the following element:
    <oidcClientWebapp contextPath="/acme/openid" />

    The resulting redirect URL format is https://<host_name>:<ssl_port>/acme/openid/redirect/<configuration_ID>.

  14. Optional: Configure Liberty to pass additional request parameters to OpenID Connect.
    • To provide additional authorization parameters to OP, configure authzParameter elements. For example, the following configuration properties pass api_key and account parameters to the authorization endpoint.
      <authzParameter name="api_key" value="567890" />
      <authzParameter name="account" value="123456" />
    • To configure additional parameters for the token endpoint, use the tokenParameter element.

Results

You have now established the minimum configuration that is required to configure a Liberty server as an OpenID Connect Client capable of communicating with other Liberty servers configured as OpenID Connect Providers.