Skip to content

Pre-issue access token action

The pre-issue access token action in Asgardeo allows you to execute custom logic before issuing an access token. This action is triggered during the OAuth2 token issuance process, enabling you to modify the access token or implement additional checks before the token is issued.

You can use this functionality to:

  • Add, modify, or remove scopes.
  • Add, modify, or remove audience values.
  • Modify or remove user attributes incorporated into the access token.
  • Add custom claims (only string, number, boolean, and string type arrays are allowed).
  • Update the validity period of the access token.

Once an access token is modified, the changes are persisted as transactional data (for the period access token is active, until it is purged from the underlying data store). In subsequent flows, the modified access token is made available to applications, resource servers, and any actions engaged in later flows. For example, if an access token is modified during the authorization code flow, the same modified access token is used in the refresh token flow.

Note

Currently, this action can only be applied at the root organization level and is available exclusively for JWT tokens. It supports the following grant types: authorization code, client credentials, password, and refresh token.

How pre-issue access token action works

When a pre-issue access token action is configured with your external service endpoint, Asgardeo will call your service and wait for a response whenever a token request is received. Upon receiving the response, Asgardeo will apply any modifications to the access token as specified in the response and then continue with the flow.

The pre-issue access token API contract defines the request and response structures that your service must implement.

Request from Asgardeo

Property Description
requestId

A unique correlation identifier that associates with the token request received by Asgardeo.

actionType

Specifies the action being triggered, which in this case is PRE_ISSUE_ACCESS_TOKEN.

event

Contains context information relevant to access token issue flow. Refer event section for details.

allowedOperations

Specifies the objects within the event data that can be modified. Refer allowedOperations section for details.

event

Property Description
event.request

This property encapsulates the details of the access token request, including parameters and headers. It provides the following specific properties.

clientId The unique identifier of the client (application) that is requesting the access token.
grantType The type of OAuth2 grant used for the token request, such as authorization code, client credentials, password, or refresh token. This defines the flow that is being used to obtain the access token.
scopes The scopes requested by the client, which define the permissions associated with the access token. Scopes determine what resources the access token will grant access to.
additionalHeaders Any additional HTTP headers included in the access token request. These may contain custom information or metadata that the client has sent. All headers in request are not incorporated specially sensitive headers like ‘Authorization’, ‘Cookie’, etc.
additionalParams Any additional parameters included in the access token request. These may be custom parameters defined by the client or necessary for specific flows. All request parameters are not incorporated, specially sensitive parameters like client secret, username and password, etc.
event.tenant

This property represents the root organization(tenant) under which the token request is being processed.

event.user

This property contains information about the authenticated user associated with the token request.

event.userStore

This property indicates the user store in which the user's data is being managed.

event.organization

This property refers to the organization to which the user belongs. Organizations represent partners/enterprise customers in Business-to-Business (B2B) use cases.

event.accessToken

This property represents the access token that is about to be issued. It contains claims and scopes, of the access token which can then be modified by your external service based on the logic implemented in the pre-issue access token action. .

claims

This property is an array that contains both standard access token claims and any OpenID Connect (OIDC) claims configured to be included in the access token.

Standard claims:

sub The subject identifier for the token, typically representing the user. In M2M apps that use client credentials this represents the application.
iss The issuer of the token, which is the tenant of WSO2 Identity Server that act as the authorization server.
aud The audience for the token.
client_id The identifier of the client (application) that requested the token.
aut

The authorized user type associated with the token.

Can have the following values:

APPLICATION: Indicates that the token is authorized for an application. APPLICATION_USER: Indicates that the token is authorized for a user.

expires_in The duration (in seconds) for which the token is valid.
binding_type Indicates the type of binding associated with the token, if applicable.
binding_ref A reference identifier for the binding, if applicable.
subject_type Specifies the type of subject (e.g., public or pairwise) as per OIDC specifications.

OIDC claims are any additional claims configured in the application to be included in the access token. These claims are based on the OIDC standard and may include user profile information such as email, given-name, or custom claims specific to the application.

scopes Lists the permissions or access levels granted by the access token.

allowedOperations

The allowedOperations property in the context of the pre-issue access token action defines the set of operations that your external service is permitted to perform on the access token's claims and scopes. This property is specifically related to the event.accessToken property and outlines which attributes can have additional properties added, values replaced, or be removed. The allowedOperations are defined using JSON Patch modification semantics.

In the context of the pre-issue access token action, certain claims related to authorization decisions, such as audience (aud), access token validity (expires_in), and scopes (scopes), are allowed to be modified. These claims are typically associated with the resource server and influence how access is granted.

However, other standard access token claims, such as the issuer (iss) and token bindings (binding_type), represent the authorization server and are critical for authorization decisions. As such, these properties are not available for modification through the action. Instead, application and organization-level configurations should be used to change these properties and their associated behaviors.

Additionally, any OIDC claims incorporated into the access token are also allowed to be modified.

Here is the example of an allowedOperations object in a request formatted as a JSON payload:

{
  "allowedOperations": [
    {
      "op": "add",
      "paths": [
        "/accessToken/claims/",
        "/accessToken/scopes/",
        "/accessToken/claims/aud/"
      ]
    },
    {
      "op": "remove",
      "paths": ["/accessToken/scopes/", "/accessToken/claims/aud/"]
    },
    {
      "op": "replace",
      "paths": [
        "/accessToken/scopes/",
        "/accessToken/claims/aud/",
        "/accessToken/claims/expires_in"
      ]
    }
  ]
}

Example request from Asgardeo:

This example illustrates a request sent to an external service configured as a pre-issue access token action, for an application authorizing a user via the authorization code grant flow.

POST /token HTTP/1.1
Host: localhost
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json

{
    "actionType": "PRE_ISSUE_ACCESS_TOKEN",
    "event": {
        "request": {
            "additionalHeaders": {
                "host": [
                    "localhost:9443"
                ],
                "user-agent": [
                    "curl/7.79.1"
                ],
                "accept": [
                    "*/*"
                ]
            },
            "clientId": "1u31N7of6gCNR9FqkG1neSlsF_Qa",
            "grantType": "authorization_code"
        },
        "tenant": {
            "id": "-1234",
            "name": "carbon.super"
        },
        "user": {
            "id": "e204849c-4ec2-41f1-8ff7-ec1ebff02821"
        },
        "userStore": {
            "id": "UFJJTUFSWQ==",
            "name": "PRIMARY"
        },
        "accessToken": {
            "tokenType": "JWT",
            "scopes": [
                "email",
                "groups",
                "openid",
                "profile",
                "roles"
            ],
            "claims": [
                {
                    "name": "iss",
                    "value": "https://localhost:9443/oauth2/token"
                },
                {
                    "name": "client_id",
                    "value": "1u31N7of6gCNR9FqkG1neSlsF_Qa"
                },
                {
                    "name": "aut",
                    "value": "APPLICATION_USER"
                },
                {
                    "name": "expires_in",
                    "value": 3600
                },
                {
                    "name": "aud",
                    "value": [
                        "1u31N7of6gCNR9FqkG1neSlsF_Qa"
                    ]
                },
                {
                    "name": "subject_type",
                    "value": "public"
                },
                {
                    "name": "sub",
                    "value": "e204849c-4ec2-41f1-8ff7-ec1ebff02821"
                }
            ]
        }
    },
    "allowedOperations": [
        {
            "op": "add",
            "paths": [
                "/accessToken/claims/",
                "/accessToken/scopes/",
                "/accessToken/claims/aud/"
            ]
        },
        {
            "op": "remove",
            "paths": [
                "/accessToken/scopes/",
                "/accessToken/claims/aud/"
            ]
        },
        {
            "op": "replace",
            "paths": [
                "/accessToken/scopes/",
                "/accessToken/claims/aud/",
                "/accessToken/claims/expires_in"
            ]
        }
    ]
}

Expected Response from External Service:

When Asgardeo invokes your external service as part of the pre-issue access token action, it expects a response that adheres to the defined API contract here.

This response plays a crucial role in determining how the access token is ultimately issued or modified. Here’s a breakdown of the expected response:

The response can have two possible states: SUCCESS and ERROR.

SUCCESS: Indicates that the request was processed successfully and includes any state changes or modifications that should be applied.

ERROR: Indicates a failure in processing, accompanied by an error message that should be communicated to the application. This error message should adhere to OAuth 2.0 error response definitions to ensure compliance. However, it is your responsibility to ensure this compliance when extending the flow.

Note

Currently, ERROR responses are not communicated back to the client, but this functionality is planned for inclusion by end October 2024.

Response for SUCCESS state:

When the external service responds with a 200 status code and a SUCCESS state, it indicates that the request was processed correctly and that any requested modifications to the access token or associated data have been completed. The response should include details about these modifications, typically in the form of an operations object that outlines the changes made to the token's claims, scopes, or other relevant attributes.

Http Status Code: 200

Property Description
actionStatus

Indicates the outcome of the request. For a successful operation, this should be set to SUCCESS.

operations

Define an array of operations that needs to be performed on the event.accessToken in the request. These operations must adhere to the [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) modification format..

Tip

Refer the sample responses for successful access token updates to learn how to construct success responses for different scenarios.

Response for ERROR state:

When the external service responds with an ERROR state, it can return an HTTP status code of 400, 401, or 500, indicating that the expected validations are not met or there is an issue processing the request.

Http Status Code: 400, 401 or 500

Property Description
actionStatus

Indicates the outcome of the request. For an error operation, this should be set to ERROR.

error

The error code, as specified in OAuth 2.0 error response definitions..

errorDescription

A detailed description of the error..

Note

Currently, ERROR responses are not communicated back to the client, but this functionality is planned for inclusion by end October 2024.

If the defined error response is not received, or if the external service fails to respond, this is identified as an error in executing the action. In such cases, the flow will proceed as if the action was not applied, ensuring that the process continues without disruption.