Sample OAuth 2.0 Client Credentials Use Case

Introduction

This articles details a Forum Sentry use case utilizing the OAuth 2.0 Client Credentials grant type.  This grant type is often referred to as "2 legged OAuth 2.0".  Note that "2 legged OAuth" with OAuth 1.0 works differently, and this article only applies to OAuth 2.0.  

The OAuth 2.0 Client Credentials grant type should only be used when the client requesting an access token is secure.  This is because the client ID and client secret are all that is required to obtain an access token, and these values need to be stored on the client. For instance, if the client is confidential (secure) such as a website, using the Client Credentials grant type may be a good option.  However, if the client is public, e.g. a mobile app, the Client Credentials grant type can still be used, but the credentials may not be secure.

 

Forum Sentry plays two roles in this use case scenario:

1. API Security Gateway  - Securing the online OpenWeatherMap REST API, requiring a valid OAuth access token in order to access the API.

2. OAuth Server - Validating a pre-shared client ID and client secret and returning an access token. Later, the Sentry OAuth policy (Authorization Server) also validates the provided access tokens and returns the corresponding scope.

 

Notes

Forum Sentry (the same instance or a different instance) could also play the role of the secure client application (OAuth Client) calling into the OAuth Server Policy (Authorization Server).

 

Outline of Use Case Flow

The use case flow can be broken down into 5 basic steps, illustrated in the following diagram and detailed below.

 

1. The client requests an access token from the /token Sentry OAuth policy directory, using the Client Credentials grant type.  This is a urlencoded HTTP Post with the grant type specified in the message payload and the client ID and client secret provided in the Basic Auth header.

HTTP Headers

POST /token HTTP/1.1
User-Agent: Crosscheck Networks SOAPSonar
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: Basic Y2xpZW50MTpwYXNzd29yZA==
Content-Length: 29

Message Body

grant_type=client_credentials

 

The Sentry OAuth policy returns a JSON document with the access token.

 {

  "scope": "default",
  "expires_in": "7200",
  "token_type": "Bearer",
  "access_token": "2yI2symsa348pDcS1U7nWQ=="
}

 

2. The client accesses the Sentry secure API virtual directory while supplying the access token inside of an HTTP Authorization header.

 

http://192.168.82.203:8080/data/2.5/weather?q=london&appid=4eab62f56a00fd9413bd0da4f898afb3

Authorization: Bearer 2yI2symsa348pDcS1U7nWQ==

 

3. The User Identity and Access Control (UIDAC) task enabled on the Sentry virtual directory calls the /attributes directory of OAuth policy to validate the provided access token.  

 

4. The Sentry OAuth policy validates the token and returns the scope and username.

{
"scope": "default",
"username": "user"
}

 

5.  The client is allowed access to the API through Sentry, and the access token is cached so that subsequent calls with the same access token can be validated without calling the OAuth policy.

 

Sample Sentry Policies (FSG Files)

There are two sample Sentry policies attached to this article. The first is the REST policy for securing the public OpenWeatherMap API.  The second is the Sentry OAuth policy that generates and validates the access tokens. Both can be imported into the same Sentry instance.

1. REST Policy (OpenWeatherMapAPI_OAuthTokenRequired_v8.5.fsg) - This is a Sentry REST policy that will proxy API calls to the OpenWeatherMap API.  The REST policy requires the client to provide a valid access token in order to access the API.

2. OAuth Policy (OAuth_Client_Credentials_Sample_v8.5.fsg) - This is a Sentry OAuth policy (Authorization Server policy) configured for the Client Credentials grant type. On the /token directory, this policy validates the client id and client secret provided by the client and returns an access token.  On the /attributes directory it will validate the token when it is provided by the UIDAC task on the Sentry REST policy.

 Notes:

• Both FSG files can be imported on the System>>Configuration>>Import screen.
• The import password for both files is "password" without the quotes.
• Both FSG files were created with Sentry v8.5 and will import into v8.5 and later versions of Forum Sentry. If you would like v8.3 or earlier copies of these policies, please contact Forum Systems Support.
• Both policies use the same HTTP Listener on port 8080.
• The /authorize virtual directory of the OAuth policy is purposely disabled as it is not in use for this scenario.  

 

Testing the Sentry Policies

Testing of these policies can be done with any REST client application that allows manipulation of the HTTP headers.  We recommend SOAPSonar and have included a sample project file for this use case.

1. Load the attached SOAPSonar project file (OAuth_Client_Credentials_Sample.ssp).

2. Modify the test case named "OAuth_Call_Token" changing the URI to match your local Sentry OAuth policy.

3. Invoke test case "OAuth_Call_Token" and receive an access token.

4. Modify the test case named "OpenWeatherMap API Call" changing the URI to match your local Sentry REST Policy.  Also change the HTTP Authorization header value to use the access token value returned from step 3.

5. Invoke test case "OpenWeatherMap API Call". The API should return a 200 OK with JSON weather data in the response.

6. Optional - You can use the test case "OAuth_Call_Attributes" to test the /attributes directory manually (simulating what the Sentry UIDAC task is doing).

 

The Sentry debug level system log transactions showing the token call, the API call, and the token validation call are also attached.

 

Next Steps

This is a basic sample use case for 2 legged OAuth meant to illustrate the functionality in Forum Sentry. Forum Systems recommends taking further action to tighten and secure these types of Sentry policies. Logical next steps include:

1. Enable SSL with mutual authentication on the OAuth policy HTTP listener.

2. Enable SSL with mutual authentication on the REST policy HTTP listener.

3. Add an IP ACL on the /token directory of the OAuth policy to ensure only specific clients can request an access token.

4. Add an IP ACL on the /attributes directory of the OAuth policy to ensure only the Sentry instance(s) can validate the OAuth tokens.

5. Forum Sentry, as a secure platform, can also be used as the OAuth client application.