Adding Extra Properties to Access Token

Preface

On receiving API requests (with access tokens) from clients, resource servers determine if the requests are allowed, and how to process them, by referring information associated with the tokens. Typical kinds of information include the following: status of the token (active / expired), who (resource owner) granted what access (scope) to whom (client). In some cases, the resource servers need to obtain other related information from an authorization server. Authlete 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. You can prevent unnecessary information disclosure as the sharing of properties can be achieved by not using clients as an intermediary.

Use cases

1. Controlling a money transfer API

Let’s assume 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.

2. Role based access control

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

This section describes examples on how to set and get properties.

Extra Properties

“Property” data type

Authlete defines Property data type that represents an arbitrary set of attributes associated with either an access token or an authorization code. The Property data type is a JSON object that contains the following entries.

Name	Type	Description
key	string	A key of the property
value	string	A value of the property
hidden	boolean	A flag that indicates if the property is hidden from clients

true: hidden from clients
false: not hidden from clients i.e. they can see the content |

For example, a property whose key and value are example_key and example_value respectively and that is not hidden from clients would be represented as a JSON object as follows.

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

Associating properties

Associating properties with an access token and/or an authorization code will be done by an authorization server at the following steps.

Providing an authorization code and/or an access token through its authorization endpoint

An authorization server sets properties to a request to Authlete’s /auth/authorization/issue API. Authlete associates the properties with the new authorization code / the access token and provide content of a token response including the code / the token. The following is an example using curl. (folded for readability)

Request

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/authorization/issue \
     -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
     -H 'Content-Type: application/json' \
     -d '{"subject":"<subject>",
          "ticket":"<ticket>",
          "properties":[
              {"key":"example_key", "value":"example_value", "hidden":true}
          ]
     }'

Response

{
    "resultCode": "A040001",
    "resultMessage": "[A040001] The authorization request was processed successfully.",
    "accessTokenDuration": 0,
    "accessTokenExpiresAt": 0,
    "action": "LOCATION",
    "authorizationCode": "...",
    "responseContent": "https://client.example.org/cb/example.com?code=..."
}

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

Providing an access token through a token endpoint

An authorization server sets properties to a request to Authlete’s /auth/token API. Authlete associates the properties with the new access token and provide content of a token response including the token. The following is an example using curl. (folded for readability)

Request

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token \
   -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
   -H 'Content-Type: application/json' \
   -d '{
        "clientId": "<clientId>",
        "clientSecret": "<clientSecret>",
        "parameters": "redirect_uri=https://client.example.org/cb/example.com&grant_type=authorization_code&code=...",
        "properties": [
            {"key": "example_key", "value": "example_value", "hidden": false}
        ]
    }'

Response

{
  "resultCode": "A050001",
  "resultMessage":
    "[A050001] The token request (grant_type=authorization_code) was processed
     successfully.",
  "accessToken": "...",
  "action": "OK",
...
  "properties": [
    {
      "hidden": false,
      "key": "example_key",
      "value": "example_value"
    }
  ],
  "refreshToken": "...",
  "responseContent":
    "{\"access_token\":\"...\",
      \"refresh_token\":\"...\",
      \"scope\":\"payment\",
      \"token_type\":\"Bearer\",
      \"expires_in\":300,
      \"example_key\":\"example_value\"     }",
  "subject": "<subject>"
}

In this case, the property is exposed to the client as** “hidden”:false** is set. Client can see the property as a part of a token response and/or a part of payload of JWT-formatted access token (if used). This value must be set to true if the property is only for resource servers i.e. clients must not see it.

Obtaining properties

By sending an access token (extracted from an API request from a client) to Authlete’s /auth/introspection API, an resource server receives a response that would contain properties. The following is an example using curl. (folded for readability)

Request

curl -s -X POST \
https://us.authlete.com/api/${SERVICE_API_KEY}/auth/introspection \
-H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{"token":"<accessToken>"}'

Response

{
    "clientId": <clientId>,
    "properties": [
        {
            "key": "example_key",
            "value": "example_value",
            "hidden": false
        }
    ],
    "action": "OK",
    "resultCode": "A056001",
    "expiresAt": 1565847795000,
    "subject": "<subject>",
    "refreshable": true,
    "usable": true,
    "existent": true,
    "resultMessage": "[A056001] The access token is valid.",
    "responseContent": "Bearer error=\"invalid_request\""
    ...
}

Examples by flow

Where properties are set depends on the grant flow, because different flows issue the token from different Authlete APIs. The walkthroughs below show the API call that takes the properties parameter in each flow, and what the client and the resource server see as a result. The examples use example_parameter=example_value as the property, ${SERVICE_API_KEY} as the service ID, and a service access token as the bearer credential.

Authorization code flow

Pass the authorization request from the client to the /auth/authorization API. The response carries action: INTERACTION and a ticket, which the next call consumes.

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/authorization \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "client_id=1048476397&response_type=code&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&scope=timeline.read" }'

Issue the authorization code with the /auth/authorization/issue API, passing the properties to associate with it. They end up on the access token that the authorization code is later exchanged for.

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/authorization/issue \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "ticket": "XhPCGRCuKw4QYShCB59yQ-5jq258hZaZ-2QNhdmsUZg",
        "subject": "user123",
        "properties": [
            {"key": "example_parameter", "value": "example_value"}
        ]
      }'

{
  "resultCode": "A040001",
  "resultMessage": "[A040001] The authorization request was processed successfully.",
  "action": "LOCATION",
  "authorizationCode": "HSwoz1hLb-qaEo5oUFhGHZdpdTevHNIrhJotOpOg0_o",
  "responseContent": "https://client.example.org/cb?code=HSwoz1hLb-qaEo5oUFhGHZdpdTevHNIrhJotOpOg0_o&iss=https%3A%2F%2Fauthlete.com"
}

action: LOCATION means the authorization server should answer the client with 302 Found and use responseContent as the Location header.

Exchange the authorization code at the /auth/token API. Properties can be added here as well; they are merged with the ones given at step 2, and a key given in both places takes the value passed to /auth/token.

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "grant_type=authorization_code&code=HSwoz1hLb-qaEo5oUFhGHZdpdTevHNIrhJotOpOg0_o&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb",
        "clientId": "1048476397",
        "clientSecret": "${CLIENT_SECRET}",
        "properties": [
            {"key": "additional_parameter", "value": "additional_value"}
        ]
      }'

{
  "resultCode": "A050001",
  "resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
  "action": "OK",
  "properties": [
    {
      "key": "additional_parameter",
      "value": "additional_value",
      "hidden": false
    },
    {
      "key": "example_parameter",
      "value": "example_value",
      "hidden": false
    }
  ],
  "accessToken": "LN-42WCA9hGmTbiKVfnyG8zFssh1S99YdLZ-uZ7Dg04",
  "refreshToken": "pbUei8l4-2cFL31zfBsaX9MO83SvNYmLfIJQxxYXAwU",
  "responseContent": "{\"access_token\":\"LN-42WCA9hGmTbiKVfnyG8zFssh1S99YdLZ-uZ7Dg04\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":\"timeline.read\",\"refresh_token\":\"pbUei8l4-2cFL31zfBsaX9MO83SvNYmLfIJQxxYXAwU\",\"additional_parameter\":\"additional_value\",\"example_parameter\":\"example_value\"}"
}

action: OK means the authorization server should answer the client with 200 OK and use responseContent as the response body. Both properties reach the client, because neither was marked hidden.

Implicit flow

The access token is issued from the authorization endpoint, so /auth/authorization/issue is the only place that takes properties.

Pass the authorization request, this time with response_type=token, to the /auth/authorization API and take the ticket from the response.

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/authorization \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "client_id=1048476397&response_type=token&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&scope=timeline.read" }'

Issue the access token with /auth/authorization/issue, passing the properties.

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/authorization/issue \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "ticket": "j3OkWV4r8TEKeCTLPY8c_BfrYAbKYEy2FXZUaiYKAYU",
        "subject": "user123",
        "properties": [
            {"key": "example_parameter", "value": "example_value"}
        ]
      }'

{
  "resultCode": "A040001",
  "resultMessage": "[A040001] The authorization request was processed successfully.",
  "action": "LOCATION",
  "responseContent": "https://client.example.org/cb#access_token=VHnmJTwVdiS69oY_RLT9kYhdMUWqNdUEVHITdy_81ak&token_type=Bearer&expires_in=86400&scope=timeline.read&example_parameter=example_value&iss=https%3A%2F%2Fauthlete.com",
  "accessToken": "VHnmJTwVdiS69oY_RLT9kYhdMUWqNdUEVHITdy_81ak"
}

The property travels to the client as a fragment parameter of the redirect URI, next to access_token.

Client credentials flow

There is no authorization endpoint step, so the properties go to /auth/token together with the token request.

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "grant_type=client_credentials&scope=timeline.read",
        "clientId": "1048476397",
        "clientSecret": "${CLIENT_SECRET}",
        "properties": [
            {"key": "example_parameter", "value": "example_value"}
        ]
      }'

{
  "resultCode": "A052001",
  "resultMessage": "[A052001] The token request (grant_type=client_credentials) was processed successfully.",
  "action": "OK",
  "properties": [
    {
      "key": "example_parameter",
      "value": "example_value",
      "hidden": false
    }
  ],
  "responseContent": "{\"access_token\":\"jC9TsQVcb0tE30pZ2jGu9S_fUB_r7AFACqcJOkl4HFA\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":\"timeline.read\",\"example_parameter\":\"example_value\"}"
}

The client must be confidential to use this flow, and no refresh token is issued (RFC 6749, 4.4.3).

Resource owner password credentials flow

The token is issued in two steps, and only the second one takes properties.

Pass the token request to /auth/token. The response carries action: PASSWORD together with the username and password the client sent, which the authorization server authenticates the user with.

Properties passed to /auth/token are discarded when grant_type is password. Pass them to /auth/token/issue instead.

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "grant_type=password&username=john&password=secret",
        "clientId": "1048476397",
        "clientSecret": "${CLIENT_SECRET}"
      }'

{
  "resultCode": "A051001",
  "resultMessage": "[A051001] Authlete has successfully issued a ticket to the service (API Key = 4239612149) for the token request from the client (ID = 1048476397). [grant_type=password]",
  "action": "PASSWORD",
  "username": "john",
  "password": "secret",
  "ticket": "gS1B19zO0c8DzN5jpac2PIWa9M1h2bFX9u6MzRi0X58"
}

Once the user is authenticated, issue the access token with the /auth/token/issue API, passing the identified user as subject and the properties to associate.

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token/issue \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "ticket": "gS1B19zO0c8DzN5jpac2PIWa9M1h2bFX9u6MzRi0X58",
        "subject": "user123",
        "properties": [
            {"key": "example_parameter", "value": "example_value"}
        ]
      }'

{
  "resultCode": "A054001",
  "resultMessage": "[A054001] The token request (grant_type=password) was processed successfully.",
  "action": "OK",
  "properties": [
    {
      "key": "example_parameter",
      "value": "example_value",
      "hidden": false
    }
  ],
  "responseContent": "{\"access_token\":\"jRdB_IwMkIyjvFkZTE5PBm1rbzz96x8Y0oF2MGagsVo\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":null,\"refresh_token\":\"a3NqLMT87HKgLblRkg51ga-xCY3OI_voPvC5uzLxQDg\",\"example_parameter\":\"example_value\"}"
}

Refresh token flow

Properties passed to /auth/token with grant_type=refresh_token are merged into the properties already carried by the access token that the refresh token belongs to — new keys are added, and a key that already exists takes the value passed here. The refresh token below is the one issued by the authorization code flow above, whose access token already has example_parameter and additional_parameter.

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "grant_type=refresh_token&refresh_token=pbUei8l4-2cFL31zfBsaX9MO83SvNYmLfIJQxxYXAwU",
        "clientId": "1048476397",
        "clientSecret": "${CLIENT_SECRET}",
        "properties": [
            {"key": "extra_parameter", "value": "extra_value"}
        ]
      }'

The newly issued access token therefore carries three properties, which the resource server reads back from the introspection API.

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/introspection \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "token": "SJKrkYzT16OInwg0gKjC6bhPo9rUNRGRDMD1c8YUHNE" }'

{
  "resultCode": "A056001",
  "resultMessage": "[A056001] The access token is valid.",
  "action": "OK",
  "clientId": 1048476397,
  "subject": "user123",
  "properties": [
    {
      "key": "additional_parameter",
      "value": "additional_value",
      "hidden": false
    },
    {
      "key": "example_parameter",
      "value": "example_value",
      "hidden": false
    },
    {
      "key": "extra_parameter",
      "value": "extra_value",
      "hidden": false
    }
  ],
  "refreshable": true,
  "usable": true,
  "existent": true,
  "expiresAt": 1789564519772,
  "responseContent": "Bearer error=\"invalid_request\""
}

Notes

Reserved values for “key”

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

Type of “value”

String is the only allowed type of “value.” Neither boolean nor array can be specified.

Size of properties

Size of properties is limited. Properties are saved into the database on the server side after going through the steps described below.

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.
Converted to JSON (e.g. ”[[“example_parameter”:“example_value”,null]]”)
Encrypted by AES/CBC/PKCS5Padding
Encoded by base64url
If the length of the resultant base64url string generated by the above steps exceeds 65535, an error occurs.

Endpoints

Tokens and Claims

Key Management

Metadata

Error Handling & Debugging

Security

Client Management

Service Settings

Adding Extra Properties to Access Token

Preface

Use cases

1. Controlling a money transfer API

2. Role based access control

How it works

“Property” data type

Associating properties

Providing an authorization code and/or an access token through its authorization endpoint

Providing an access token through a token endpoint

Obtaining properties

Examples by flow

Authorization code flow

Implicit flow

Client credentials flow

Resource owner password credentials flow

Refresh token flow

Notes

Reserved values for “key”

Type of “value”

Size of properties

​Preface

​Use cases

​1. Controlling a money transfer API

​2. Role based access control

​How it works

​“Property” data type

​Associating properties

​Providing an authorization code and/or an access token through its authorization endpoint

​Providing an access token through a token endpoint

​Obtaining properties

​Examples by flow

​Authorization code flow

​Implicit flow

​Client credentials flow

​Resource owner password credentials flow

​Refresh token flow

​Notes

​Reserved values for “key”

​Type of “value”

​Size of properties

Preface

Use cases

1. Controlling a money transfer API

2. Role based access control

How it works

“Property” data type

Associating properties

Providing an authorization code and/or an access token through its authorization endpoint

Providing an access token through a token endpoint

Obtaining properties

Examples by flow

Authorization code flow

Implicit flow

Client credentials flow

Resource owner password credentials flow

Refresh token flow

Notes

Reserved values for “key”

Type of “value”

Size of properties