Authorization using OAuth 2.0

OAuth 2.0 is an open standard for delegated authorization. With the OAuth authorization framework, a user can grant a third-party application access to information that is stored with another HTTP service without sharing their access permissions or the full extent of their data.

WebSphere® Liberty supports OAuth 2.0, and can be used as an OAuth service provider endpoint and an OAuth protected resource enforcement endpoint. Liberty supports persistent OAuth 2.0 services. See Configuring persistent OAuth 2.0 services for more information. Clients can be defined locally with the localStore and client elements. This guide will use local clients to enable OAuth 2.0 authorization.

Before you begin

SAF security is a common use-case in CICS, and this procedure uses SAF in the examples.

Ensure that the CICS® region is configured to use SAF security and is defined with SEC=YES as a system initialization parameter.

Optionally, you can grant an administrator user access to the SAF EJBROLE BBGZDFLT.com.ibm.ws.security.oauth20.clientManager. The security role clientManager controls access to the management interfaces, allowing local clients to be queried, and persistent local clients to be created. The administrator user controls OAuth 2.0 local clients.

Configure the Liberty angel process to provide authentication and authorization services to the Liberty JVM server; for more information see The Liberty server angel process.

For background information on OAuth, see oauth-2.0.

About this task

The following procedure covers how to:

Create an OAuth 2.0 service provided in a Liberty JVM server
Create a locally configured client
Use this local client to grant an OAuth 2.0 token to a relying party application, also known as a third-party web application
Use this token to access protected resources in an application

Restriction: Db2® JDBC type 2 connectivity is not supported for persistent OAuth 2.0 services.

Procedure

Configure an OAuth 2.0 service provider.
1. Add the oauth-2.0 and the cicsts:security-1.0 features to the featureManager element in server.xml.
```
<featureManager>
    ...
    <feature>oauth-2.0</feature> 
    <feature>cicsts:security-1.0</feature>
</featureManager>
...
```
2. Configure an OAuth 2.0 provider in server.xml.
```
<oauthProvider id="myProvider">
</oauthProvider>
```
Configure a local client for the relying party application. Local clients define the details of the relying party application, including the name, secret password and redirect URI of the application.
1. Define a meaningful local client name and create a secret password which is used by the server for authorization. The local client application listens on a URI, and the server supplies authorization codes.
2. Configure an OAuth 2.0 local client in the oauthProvider element of server.xml, supplying the local client ID, secret password and the redirect URI.
```
<oauthProvider id="myProvider">
    <localStore>        
        <client id="myClient" redirect="https://client.example.ibm.com/webApp/redirect" secret="mySecret" />
    </localStore>
</oauthProvider>
```
  Important:
  Although it is not shown in this example, it is important to encode passwords and limit access to server.xml configuration. Passwords can be encoded using the Liberty securityUtility, found in USS_HOME/wlp/bin/securityUtility. For more information, see Liberty: securityUtility command.
  
  Note: More than one local client can be configured in the localStore element.
When the relying party application requires access to protected resources on the server, the user must authorize access to these resources first.
1. The relying party application requires the user to authenticate with the server, and select the type of access for the relying party application by linking or redirecting the user to the authorization endpoint:
```
https://hostname:port/oauth2/endpoint/provider_name/authorize
```
  or
```
https://hostname:port/oauth2/declarativeEndpoint/provider_name/authorize
```
  Additional parameters are required in the query parameters of the URL. For the local client that was configured in step two, the following GET request is required:
```
https://zos.example.ibm.com/oauth2/endpoint/myProvider/authorize?response_type=code&client_id=myClient&client_secret=mySecret&redirect_uri=https://client.example.ibm.com/webApp/redirect
```
  When the user has selected the access for the relying party application, they are redirected back to the relying party application using the redirect URI:
```
https://client.example.ibm.com/webApp/redirect?code=access_code
```
  The relying party application must store this access code to request an OAuth token.
  
  Note: For local clients, the user must exist in a user register in the Liberty JVM server. See Authenticating users in a Liberty JVM server for more information on authenticating users in Liberty JVM servers.
2. The relying party application requests an OAuth 2.0 token by sending a POST request to the server:
```
https://hostname:port/oauth2/endpoint/provider_name/token
```
  The relying party application sends the authorization code received from the authorization endpoint, the local client ID, and secret password in the POST data:
```
POST https://zos.example.ibm.com/oauth2/endpoint/myProvider/token HTTP/1.1
Content-Type: application/www-form-urlencoded

grant_type=authorization_code&code=code&client_id=myClient&client_secret=mySecret&redirect_url=https://client.example.ibm.com/webApp/redirect
```
  This returns a JSON document containing the token.
Use the token to access protected resources.
1. Add the token to the Authorization header on the HTTP request.
  Authorization: Bearer <token>

Results

Users are able to authorize third-party applications to access their protected resources in a Liberty JVM server through OAuth 2.0 authorizations flows. The Liberty JVM server can configure the provider of these tokens and create locally configured clients.

There are several methods of granting tokens, for more information, see OAuth 2.0 service invocation.