OTK token lifetimes customized for OAuth clients

Document ID : KB000044452
Last Modified Date : 14/02/2018
Show Technical Document Details

Introduction/Summary: 

OTK by default issues tokens with a global lifetime which becomes a limitation in many cases. Many people would like to customize it so that each client has their own token lifetime. This KB is about customizing token lifetimes per client.

Background:  

Since OTK-3.3.01 (January 2016) client_id's can be configured with a JSON structured custom field. The content of that field is available in policy for certain tasks during OAuth request processing. Here are the required steps from "Register a new client" to "issue token with custom token lifetime":

Instructions: 

The process is divided into 2 parts:

1.  Register a test client in OAuth Manager

2.  Modify one policy

It starts with OAuth Manager (https://your-gateway:port/oauth/manager):

1.  Select "Clients -> Register A New Client"

2.  Use the name "AAA Test Client", the Organization "AAA Test" and click "Register"

3.  Select "Clients" and look for "AAA Test Client"

4.  Select "List Keys -> Edit". At the bottom of the screen you will find a custom field containing "{}" (an empty JSON structure)

5.  Paste this content into the custom field:  {"lifetimes": {"oauth2_access_token_lifetime_sec": 86400, "oauth2_refresh_token_lifetime_sec": 432000}}

6.  Click "Save"

This client_id now has a custom field which we will use to generate access_token with a lifetime of 86400s (1 day) and refresh_token with a lifetime of 432000s (5 days).

The next step is to modify the policy that generates token: OTK Generate OAuth Token. This will be done in the Policy Manager:

1.  Login to Policy Manager using admin credentials

2.  In the lower left window search for "OTK Generate OAuth Token" and open the policy in the editor window; turn on "Show Comments" and "Show Assertion Numbers"

3.  On line 5 you will find "OTK Token Lifetime Configuration". That assertion generates global lifetimes which we will overwrite

4.  All together, including container assertions (At least one ..., All assertions ...) we have to add 9 lines of policy

 

To give you an idea, the result of this customization will look like shown below:

 1.png

 

Ok, let's get started:

1.  line 6: add the assertion "At least one ..."

2.  line 7: add the assertion "All assertions ..." as the first child of the "At least one ..." assertion

3.  line 8: add the assertion "Continue Processing" as the second child

You should have this picture now (without the comments in the screenshot unless you also added those):

 2.png

 

All the next assertions will be added into the block on line 7. I will explain each line with all necessary details:

1.  line 8: add the assertion "Set Context Variable". Configure it as follows:

 a.  Variable Name: custom_json

 b.  Data Type: Message

 c.   Content-Type: application/json; charset=UTF-8

 d.  Expression: ${custom}. The variable ${custom} contains what was specified in the custom field in OAuth Manager

2.  line 9: add the assertion "Compare Expression" to check if the content includes the value "lifetimes" which indicates that custom lifetimes were configured

 a.  Variable: ${custom_json.mainpart}

 b.  Add ... Simple Comparison ...

 c.   Select "contain" in the second drop-down list, select "does" in the first drop-down list

 d.  Right Expression: lifetimes

 e.  Uncheck "Case Sensitive", click "OK"

 f.    Click "OK" to close the assertions dialog

3.  line 10, 11: add the assertion "Evaluate JSON Path Expression". Both are similar, one is extracting the "access_token" lifetime, the other the "refresh_token" lifetime:

a.  for the access_token lifetime:

   i.   Expression: $..lifetimes.oauth2_access_token_lifetime_sec

   ii.    Other Message Variable: custom_json

   iii.    variable Prefix: at_lifetime

 

b.  For the refresh_token lifetime:

   i.   Expression: $..lifetimes.oauth2_refresh_token_lifetime_sec

   ii.    Other Message Variable: custom_json

   iii.    Variable Prefix: rt_lifetime

 

4.  line 12, 13: add the assertion "Set Context Variable" to overwrite the global lifetime variables oauth2_access_token_lifetime_sec and oauth2_refresh_token_lifetime_sec

a.  for the access_token lifetime:

   i.   Variable Name: oauth2_access_token_lifetime_sec

   ii.   Data Type: String

   iii.    Expression: ${at_lifetime.result}

 

b.  for the refresh_token lifetime:

   i.   Variable Name: oauth2_refresh_token_lifetime_sec

   ii.   Data Type: String

   iii.   Expression: ${rt_lifetime.result}

 

Click "Save and Activate", create a revision history comment "Customized Token Lifetime".

Additional Information:

This will only work with OTK-3.3.01 and above as these versions contain the new JSON field.