Understanding actions¶

Actions allow you to customize specific flows of Asgardeo by integrating custom code hosted in an external web service. When Asgardeo initiates a flow, it calls an endpoint provided by the web service and executes the custom code synchronously, as part of the flow. This flexibility enables you to extend and modify a flow's behavior to meet your unique requirements.

Explore action types¶

The capabilities of an action are determined by its execution point within the Asgardeo runtime.

Asgardeo defines several types of actions, each tailored to customize a specific flow within the product. While all action types use the same general syntax for requests and responses exchanged between Asgardeo and the external web service, they differ in the specifics of the JSON objects involved. When implementing your external service, you must develop your code according to the REST API contract associated with the type of action you are using. The following flows support customization with custom code.

Note

Currently, the product supports only the pre issue access token trigger. The other action types listed below are planned for inclusion by early December 2024.

Flow	Trigger	Availability	Example use cases
Login	Authenticate	Early November 2024	Call an external service to authenticate the user. Make access decisions based on a risk factor reading obtained from a third party risk engine, or data/grants read from an external service (elevate access, suspend, etc). Prompt for additional inputs required by business systems to verify access.
Token management	Pre issue access token	Early access (beta)	Prevent tokens from being issued based on policy or change permissions, scopes. Add custom claims to access tokens. Change the access token and refresh token validity based on a rule.
Registration	Pre registration	Early December 2024	Deny registration by location. Set additional data in the user profile. Initiate an external service to trigger a verification such as an approval, biometrics, allowed lists, etc. Verify for sanctioned countries, initiate screening processes.
Password update	Pre password update	Early November 2024	Challenge with an additional verification factor before allowing to update password. Integrate with credential intelligence services to verify the security of password, or check against allowed lists.
Profile update	Pre profile update	Early December 2024	Challenge with an additional verification factor before allowing to update sensitive attributes. Redirect to a third party service for verification. Verify for sanctioned countries, initiate screening processes.

How actions work¶

Each type of action is executed at a specific extension point within a particular runtime flow of Asgardeo. When an action is triggered, Asgardeo calls your external service and waits for a response. Upon receiving the response, Asgardeo performs any specified operations and continues with the flow.

The following diagram illustrates the sequence of these steps:

how-actions-work

Request from Asgardeo¶

Asgardeo sends an HTTPS POST request to your external web service with a JSON payload that includes data relevant to the flow that triggered the action. The request consists of the following components:

Property	Description
flowId	A unique correlation identifier for the flow (e.g., a login process involving input collection, authentication, and two-factor authentication) initiated and executed by Asgardeo. note Currently, not all actions incorporate a flowId. The presence of a flowId depends on the type of action and the executed flow.
requestId	A unique correlation identifier that associates the request received by Asgardeo.
actionType	Indicates the execution point within the Asgardeo runtime where your external service is called. Refer to Explore Action Types for a list of supported trigger points.
event	Contains context information necessary for your external service to perform state or flow-changing operations. The structure of the event data depends on the type of action.
allowedOperations	Specifies which elements within the event data can be modified. For a given JSON resource in the `event`, you may add fields, replace values, or remove fields. Additionally, your external service may have the option to redirect based on the flow.

Responses Asgardeo expects¶

Your service must handle the action by responding to the request from Asgardeo. The JSON payload of your response may include different action statuses and can contain an operations object to indicate state or flow changes. The specifics of these statuses and operations depend on the action type.

Time out and retry¶

When Asgardeo calls an external service, it enforces a default read timeout of five seconds and a connection timeout of two seconds. Asgardeo will attempt at most one retry for the following HTTP status codes received from your service:

Status code	Description
500	Internal Server Error. If the error response includes an acceptable payload, it is treated as an error state that must be addressed by responding back to the client or as a flow breaker. Otherwise, requests will be retried.
502	Bad Gateway.
503	Service Unavailable.
504	Gateway Timeout.

Requests will not be retried if the external service responds with HTTP status codes 200 (OK), 400 (Bad Request), 401 (Unauthorized), or any other codes not listed above as retry scenarios.

Troubleshooting¶

You can use diagnostic logs to capture detailed information during the troubleshooting process. Logs capture requests sent from Asgardeo to your external action service, track the responses received, and include status and context data for response handling.

Shown below is an example of a diagnostic log generated during the pre-issue access token action flow, while sending a request from Asgardeo to the external endpoint.

Asgardeo logs

The following table gives an explanation to each property included in the diagnostic log event.

Property	Description
logId	Unique ID for each log event.
recordedAt	Timestamp of log event occurrence.
requestId	Unique ID to correlate the log event to a specific request.
resultStatus	Status of the log event. Either `Success` or `Failed`.
resultMessage	Description of the log event.
actionId	ID to identify a specific log event.
componentId	ID to identify the component where the log event was carried out.
configurations	System specific context data relevant to the log event.
input	Parameters given by the user which are applicable during the log event.

You may view the diagnostics logs under the logs tab in Asgardeo. Refer here to learn more about diagnostic logs in Asgardeo.