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 |
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.
|
||||||||||||||||||||||
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. .
|
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 |
operations | Define an array of operations that needs to be performed on the |
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 | 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.