Configuring OAuth 2.0 protected resources in Liberty

You can configure a Liberty server to function as OAuth 2.0 protected resource server.

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, and enable the element as an OAuth 2.0 protected resource server by adding inboundPropagation="required". The following is an example of a minimal configuration that works with the Liberty server OpenID Connect Provider and the OAuth 2.0 Authorization Server.

   
   <openidConnectClient id="RS" inboundPropagation="required"
     clientId="client01"
     clientSecret="{xor}LDo8LTor"
     validationEndpointUrl="https://server.example.com:443/oidc/endpoint/OP/introspect">
   </openidConnectClient>

   Note: In this sample configuration, Liberty performs OAuth 2.0 Token Introspection by setting validationMethod="introspect". An authenticated subject is created from the JSON object that is returned from the introspection endpoint directly without the requirement of a user registry.

   Note: To allow Liberty to perform token introspection, the Liberty OAuth 2.0 resource server must register itself as an OAuth client to the OAuth Authorization server or the OpenID Connect Provider, and can perform a token introspection request. The clientId and clientSecret are provided by the authorization server.
3. Configure the truststore of the server to include the signer certificates of the authorization server and modify the SSL configuration of the server to use the configured truststore. For information about keystores, see Enabling SSL communication in Liberty.

   For information about keystores, see Enabling SSL communication in Liberty.

4. Optional: Configure a user registry.

   The user identity that is returned by the authorization server is not mapped to a registry user by default, so there is no user required in the user registry. However, if the mapIdentityToRegistryUser attribute of the openidConnectClient element is set to true, then there must be a user entry for the appropriate identity that is returned from the authorization server in order for authentication and authorization to succeed. For more information about configuring a user registry, see Configuring a user registry in Liberty.

5. Optional: Configure Authentication Filters.

   When the openidConnectClient-1.0 feature is enabled and the openidConnectClient element is not configured with an authFilterRef attribute, any unauthenticated request attempt is authenticated by this openidConnectClient element.

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

6. Optional: You can configure Liberty as an OAuth 2.0 resource server to work with multiple Authorization Servers and OpenID Connect Providers by creating multiple openidConnectClient elements and multiple Authentication Filters. Each openidConnectClient element defines one trust relationship with one authorization server or OpenID Connect Provider, and uses the authFilterRef attribute to reference to one Authentication Filter.
7. Optional: You can configure the Liberty resource server to validate a token and receive user information from the OpenID Connect userinfo endpoint by setting validationMethod="userinfo".
8. Optional: The Liberty resource server uses claims that are in JSON and received from the authorization server to create an authentication subject, and you can define rules of how to map the JSON to the subject, see userIdentifier, groupIdentifier, UserUniqueIdentifier, realmIdentifier, and realmName in OpenID Connect Client.
9. Optional: A Liberty OAuth 2.0 protected resource server expects each request to provide a valid access token, and will never use a single-sign-on cookie for authentication. However it is possible to configure Liberty to create a single-sign-on cookie by setting authnSessionDisabled="false".
10. Optional: You can also implement the com.ibm.wsspi.security.oauth.UserCredentialResolver SPI, to programmatically map a JSON to subject.