How to add extra properties to an access token

Overview


Authlete provides a feature that enables an authorization server to associate arbitrary properties with either an access token or authorization code. The authorization server can easily share the properties with resource servers so that they can consume such information for its authorization enforcement as well as making a response.

For example, you would like to develop a money transfer API that can process specific transaction like "send $50 to ABC shop." You could implement such function by creating a "send-50dollar-to-abcshop" scope, but it hardly works as you would have to prepare a lot of scopes that are multiplied with recipients and amounts.

With the properties feature of Authlete, The authorization server can associate the money transfer information (or its handle, if database manages the actual information) with an access token to be issued to a client. The resource server, which hosts the money transfer API, receives an API request with the access token from the client, asks Authlete's introspection API to provide the properties along with details of the token, and then determines if the money transfer request is allowed to proceed.

Another example is say when a resource server receives an API request with an access token, it would like to know details of the token, not only user identifier but also groups and roles of the user. A simple solution is, that the resource server makes an introspection request to Authlete, gets the user identifier ("subject") and makes a query to another database to find such groups/roles information.

Again, Authlete's properties feature makes the implementation simpler. The authorization server can associate the groups/roles with the access token to be provided to the client, and the resource server can find the values from the access token included in an API request from the client. The resource server doesn't need to communicate with the database.


How it works


Property  ("properties") is a data type of Authlete for associating arbitrary parameters with either an access token or an authorization code. Property is a JSON object that contains entries of "key" and "value", which have a value of string. The "key" represents a key of the property, and the "value" does a value. The following example is a JSON object of a property.

{
  "key":"example_parameter",
  "value":"example_value",
  "hidden":false
}


When an authorization server associates the property to an access token, a token response from the server to a client looks like the following:


{
  "access_token":"pNj1h24a4geA_YHilxrshkRkxJDsyXBZWKp3hZ5ND7A",
  "token_type":"Bearer",
  "expires_in":86400,
  "scope":null,
  "example_parameter":"example_value"
}

Authlete's  /auth/introspection API would make the following response to an resource server. It contains the property.

{
  "clientId" : <Client ID>,
  "properties" : [
    {
      "key":"example_parameter",
      "value":"example_value",
      "hidden" : true
   }
  ],

  "sufficient" : true,
  "action" : "OK",
  "clientIdAliasUsed" : false,
  "resultCode" : "A056001",
  "expiresAt" : 1565847795000,
  "subject" : "<Subject>",
  "type" : "introspectionResponse",
  "refreshable" : true,
  "usable" : true,
  "existent" : true,
  "resultMessage" : "[A056001] The access token is valid.",
  "responseContent" : "Bearer error=\"invalid_request\""
}

How to use


The association of properties is done at the following situations:

  1. Just before an authorization server makes a response that contains either an access token or authorization code from its authorization endpoint
  2. Just before an authorization server makes a response that contains an access token from its token endpoint

For example in the former case 1, the authoriztion server is to set the property to a request to /auth/authorization/issue API as follows:

{ "ticket": "<ticket>", "subject": "<subject>", "properties":[{"key":" example_parameter","value":"example_value","hidden":true}] }

Or you can implement such operation with authlete-java-jaxrs library. Specifically there is a getProperties method in AuthorizationDecisionHandlerSpiAdapter class, that handles association of properties (returns null by default).

See more details on Definitive Guide, API Reference, implementation examples on GitHub.


Limitations


  1. The following values are not applicable for "key" of properties, as RFC 6749 and OpenID Connect Core 1.0 have reserved the names for parameters which may be included in a response from an authorization server. Authlete discards them if they are specified. 
    • access_token
    • token_type
    • expires_in
    • refresh_token
    • scope
    • error
    • error_description
    • error_uri
    • id_token
  2. String is the only allowed type of "value." Neither boolean nor array can be specified.
  3. Size of properties is limited. Properties are saved into the database on the server side after going through the steps described below. 
    1. Converted to a two-dimensional array (e.g. [["example_parameter","example_value",null]]). The value of hidden is converted to either null or an empty string. They mean false and true, respectively.
    2. Converted to JSON (e.g. "[[\"example_parameter\":\"example_value\",null]]")
    3. Encrypted by AES/CBC/PKCS5Padding
    4. Encoded by base64url
    5. If the length of the resultant base64url string generated by the above steps exceeds 65535, an error occurs.
How did we do with this article?