Configuring an OpenID Connect Provider in Liberty

You can configure a Liberty server to function as an OpenID Connect Provider, or authorization server, to take advantage of web single sign-on.

About this task

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

Procedure

  1. Add the openidConnectServer-1.0 Liberty feature and any other needed features to the server.xml file. The ssl-1.0 feature is also required for the openidConnectServer-1.0 feature.
    <feature>openidConnectServer-1.0</feature>
    <feature>ssl-1.0</feature>
  2. Define an OAuth service provider. OpenID Connect is built on top of the OAuth 2.0 protocol and you must configure a valid OAuth service provider. The configuration of an OAuth service provider includes the appropriate oauth-roles, oauthProvider, and user registry elements. Any user that is authorized to use OpenID Connect must also be mapped to the authenticated oauth-role. For more information, see Defining an OAuth service provider.

    The OAuth metadata is updated for OpenID Connect, and the main additions are in the client metadata. If you use the databaseStore mode for client registration, see Configuring an OpenID Connect Provider to accept client registration requests. It is suggested that you follow the document to manage clients. If you use the localStore mode for client registration, you can register the scope, preAuthorizedScope, grantTypes, responseTypes, introspectTokens, and functionalUserId, as well as other attributes.

  3. Add an openidConnectProvider element whose oauthProviderRef attribute references the configured oauthProvider. Each oauthProvider can be referenced only by one openidConnectProvider, and two or more openidConnectProvider elements cannot reference to the same oauthProvider. The name attribute and the secret attribute of the client element must match the client ID and the client secret of the corresponding OpenID Connect Client. This example works with the default Liberty server OpenID Connect Client.
    Note: In this example, the OP expects the client's SSL port to be set to 443.
    <openidConnectProvider id="OidcConfigSample" oauthProviderRef="OAuthConfigSample" /> 
    
    <oauthProvider id="OAuthConfigSample"> 
    <localStore> 
    <client name="client01" secret="{xor}LDo8LTor" 
    displayname="client01" 
    scope="openid profile email" 
    redirect="https://server.example.com:443/oidcclient/redirect/client01"/> 
    </localStore> 
    </oauthProvider>
    Note: A valid client must register its name, redirect, scope, and secret for authorization_code grant type.
  4. Configure the truststore of the server to include the signer certificates of the OpenID Connect Relying Parties, or clients, 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}Lz4sLCgwLTs=" type="jks" location="${server.config.dir}/resources/security/BasicKeyStore.jks" /> 
    <keyStore id="myTrustStore" password="{xor}Lz4sLCgwLTs=" 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.

    The user consent form in OpenID Connect is pluggable, which allows providers to create and maintain their own consent form. Because this form is retrieved over SSL, you must configure the truststore to include the signer certificate of the server on which the consent form is hosted. If the default consent form is used and the truststore used for OpenID Connect is configured to be different from the keystore used by the Liberty server, you must import the Liberty server's signer certificate into the OpenID Connect truststore.

    Note: To use OpenID Connect, the scope attribute must include openid in the scope list.

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

    For more OAuth configuration options, see OAuth.

  6. [16.0.0.3 and later]Optional: Configure your Liberty OpenID Connect Provider to issue JSON Web Token (JWT) tokens as access_token tokens.

    By default, Liberty issues opaque access_token tokens. Opaque tokens require that the token recipient call back to the server that issued the token. You can configure the Liberty OpenID Connect Provider to instead issue JWT tokens as access_token tokens, which include the token verification mechanism within the token, by setting jwtAccessToken="true" on the oauthProvider configuration element or implementing the com.ibm.wsspi.security.oauth20.JwtAccessTokenMediator service programming interface (SPI).

    For more information about the interface, see WebSphere OAuth 2.0 web single sign-on SPI or the Java documentation that is provided with the product in the ${wlp.install.dir}/dev/spi/ibm/ directory.

  7. [16.0.0.4 and later]Optional: Customize the contents of the id_token token that the Liberty OpenID Connect Provider sends.
    By default, the Liberty OpenID Connect Provider issues id_token tokens that contain user name and group membership information. You can customize the token contents in the following ways:
    • Fully customize the id_token contents by implementing the com.ibm.wsspi.security.openidconnect.IDTokenMediator SPI. The SPI provides the most flexibility, so you can build your own custom token.

      For more information about the interface, see WebSphere OAuth 2.0 web single sign-on SPI or the Java documentation that is provided with the product in the ${wlp.install.dir}/dev/spi/ibm/ directory.

    • Fetch additional user attributes from the Federated User Registry by listing the additional claims on the customClaims attribute of the openidConnectProvider element in the server configuration. If the claim name is different from the attribute name in the Federated User Registry, map the claim name to the attribute on the claimToUserRegistryMap element.
      For example, the following configuration adds several claims and maps the alias claim to the seeAlso registry attribute and the lastName claim to the sn attribute:
      <openidConnectProvider id="MyOP" oauthProviderRef="MyOauth" customClaims= "alias, email, lastName, employeeType, office">
          <claimToUserRegistryMap alias="seeAlso" lastName="sn"/> 
          ...
      </openidConnectProvider>

      For more information, see Configuring claims returned by the UserInfo endpoint.

Results

You completed the minimum configuration that is required to configure a Liberty server as an OpenID Connect Provider capable of communicating with other Liberty servers configured as OpenID Connect Clients.

Icon that indicates the type of topic Task topic



Timestamp icon Last updated: Monday, 5 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_config_oidc_op
File name: twlp_config_oidc_op.html