Understanding service extensions

Service extensions 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.

Types of service extensions

Service extensions in Asgardeo can be broadly categorized into two main types:

1. In-Flow Extensions:

   These extensions operate within the authentication or registration flow itself.

   E.g., Create a custom authenticator as an external web service that integrates with a third-party identity provider or implements unique authentication logic and engage that within the login flow for an application.

2. Pre-Flow Extensions (Actions):

   These extensions execute specific actions before a particular event or flow within Asgardeo. E.g.,

   • Pre-issue access token:
     • Triggered before an access token is issued.
     • Allows you to modify claims, perform additional checks, or log relevant information.
   • Pre-update password:
     • Triggered before a user's password is updated.
     • Enables you to enforce password complexity rules, notify administrators, or perform other custom logic.
   • Pre-update profile:
     • Triggered before a user's profile is updated.
     • Allows you to validate profile data, synchronize with external systems, or trigger notifications.

These extension types provide powerful mechanisms to tailor Asgardeo to your specific requirements and integrate it seamlessly with your existing systems and processes.

All these extension types use a consistent 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 table lists the currently supported extensions and those in the roadmap for future availability.

Flow	Trigger	Availability	Example use cases
Login	Authenticate	Early access (beta)	Call an external service to authenticate the user.
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 May 2025	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 access (beta)	Integrate with credential intelligence services to verify the security of password, or check against allowed lists.
Profile update	Pre profile update	Early access (beta)	Automated verification of user attributes. Verify for sanctioned countries, initiate screening processes.

How service extensions work

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

The following diagram illustrates the sequence of these steps:

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 extension. 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 extensions incorporate a flowId. The presence of a flowId depends on the type of extension and the executed flow.
requestId	A unique correlation identifier that associates the request received by Asgardeo. note Currently, not all extensions incorporate a requestId.
actionType	Indicates the execution point within the Asgardeo runtime where your external service is called. Refer to Types of service extensions 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 extension.
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 respond to the request from Asgardeo with a JSON payload that includes an action status. Depending on the extension type, the payload may also include an operations object to indicate state or flow changes, or a data object to provide data for use within the flow. The specific statuses, operations, and data formats depend on the extension type.

Time out and retry

Asgardeo enforces default timeout limits when calling external services:

• Connection timeout: 2 seconds
• Read timeout: 3 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.

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.

Extension implementation best practices

Security basics

• Avoid including sensitive information or personally identifiable information (PII) in URLs, error/failure messages, or descriptions.
• It is strictly recommended to use HTTPS for external service endpoint in production. The HTTP should be used only for testing purposes.
• The None authentication type is intended for testing purposes only. It is recommended to implement a proper authentication mechanism for external service endpoint.
• Always use HTTPS for redirects and API calls to ensure secure communication.