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
- 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>
- 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.
Note: 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 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.
- 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
- 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.
- 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.
- 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".
- 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.
- Set signatureAlgorithm="RS256". The Liberty OpenID Connect client's default signature algorithm is HS256.
- 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.
- 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
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>.
Results
Subtopics
- Invoking the Authorization Endpoint for OpenID Connect
In OpenID Connect the authorization endpoint handles authentication and authorization of a user. - Invoking the Token Endpoint for OpenID Connect
In the OpenID Connect Authorization Code Flow, the token endpoint is used by a client to obtain an ID token, access token, and refresh token. - Invoking the Introspection Endpoint for OpenID Connect
The introspection endpoint enables holders of access tokens to request a set of metadata about an access token from the OpenID Connect Provider that issued the access token. The access token must be one that was obtained through OpenID Connect or OAuth authentication. - Invoking the coverage map service
The coverage map service is an unprotected endpoint that returns a JavaScript Object Notation (JSON) array of slash-terminated URI prefixes. The array of URI prefixes designates which web contexts are part of a Single Sign On (SSO) group, thus enabling clients to know whether a URI destination is deemed safe to send an access token. - Invoking the UserInfo Endpoint for OpenID Connect
The UserInfo endpoint returns claims about a user that is authenticated with OpenID Connect authentication. - Invoking the Session Management Endpoint for OpenID Connect
The session management endpoint enables OpenID Connect Relying Parties to monitor the login status of a user with a particular OpenID Connect Provider (OP) while minimizing network traffic. With the help of the session management endpoint, a Relying Party (RP) can log out a user who logged out of the OpenID Connect Provider.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-libcore-mp&topic=twlp_config_oidc_rp
File name: twlp_config_oidc_rp.html