Authorizing applications by using OAuth 2.0

OAuth 2.0 is an open standard for delegated authorization. The OAuth authorization framework enables a user to 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. Clients can be defined locally with the localStore and client elements. The following procedure uses 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. See The Liberty server angel process.

For more information about 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 that 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 by using the Liberty securityUtility, found in USS_HOME/wlp/bin/securityUtility. For more information, see 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 2, the following GET request is required (all one line):
```
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
```
  After the user selects 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. For more information about authenticating users in Liberty JVM servers, see Authenticating users in a Liberty JVM server.
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 that is received from the authorization endpoint, the local client ID, and the secret password in the POST data (grant_type is all one line):
```
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 that contains 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.

Several methods to grant tokens are available. For more information, see OAuth 2.0 service invocation.