You can configure a Liberty server to function as OAuth 2.0 protected resource
server.
About this task
You can configure a Liberty server to act as an OAuth 2.0 protected resource server by enabling
the openidConnectClient-1.0 feature in Liberty, and by setting
inboundPropagation="required" in addition to other configuration information. The
configuration for the OAuth 2.0 resource server is similar to Configuring an OpenID Connect Client in Liberty.
Any party in possession of an OAuth bearer access_token can use that token to
get access to the associated resources in Liberty. The Liberty server remotely validates the
access_token to the OAuth authorization server or the OpenID Connect provider
directly by calling either the OAuth 2.0 Token Introspection endpoint or the OpenID Connect Userinfo Endpoint.
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, 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.
- 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.
- 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.
- 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.
- 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.
- 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".
- 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.
- 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".
- Optional: You can also implement the
com.ibm.wsspi.security.oauth.UserCredentialResolver SPI, to programmatically map a
JSON to subject.
Results
You have now established the minimum configuration that is required to configure a Liberty
server as an OAuth 2.0 protected resource server capable of communicating with an OAuth
authorization server or an OpenID Connect provider.