Liberty Repository[8.5.5.4 or later]
This topic applies to WebSphere Application Server Liberty V8.5.5.9 and earlier. For the latest Liberty topics, see the WebSphere Application Server Liberty documentation.

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.

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.

Procedure

  1. Add the openidConnectClient-1.0 Liberty feature and any other needed features to the server.xml file. The ssl-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>ssl-1.0</feature>
  2. Configure an openidConnectClient element. The following is an example of a minimal configuration that works with the default Liberty server 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: 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>.
  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 for Liberty.
  4. Configure the truststore of the server to include the signer certificates of the OpenID Connect Providers that are supported. For information about keystores, see Enabling SSL communication 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.

  6. [8.5.5.5 or later]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 **** MISSING FILE ****.

  7. [8.5.5.5 or later]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 Liberty Repository[8.5.5.5 or later]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.

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.

Icon that indicates the type of topic Task topic



Timestamp icon Last updated: Tuesday, 12 December 2017
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=twlp_config_oidc_rp
File name: twlp_config_oidc_rp.html