Understanding service extensions

Service extensions allow you to customize specific flows of WSO2 Identity Server by integrating custom code hosted in an external web service. When WSO2 Identity Server 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 WSO2 Identity Server 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 WSO2 Identity Server. 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 WSO2 Identity Server to your specific requirements and integrate it seamlessly with your existing systems and processes without deploying custom code to the product, extending product internal architecture.

All these extension types use a consistent general syntax for requests and responses exchanged between WSO2 Identity Server 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 extensions currently supported by the product.

Flow	Trigger	Example use cases
Login	Authenticate	Call an external service to authenticate the user.
Token management	Pre issue access token	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.
Password update	Pre password update	Integrate with credential intelligence services to verify the security of password, or check against allowed lists.

How service extensions work

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

The following diagram illustrates the sequence of these steps:

Request from WSO2 Identity Server

WSO2 Identity Server 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 WSO2 Identity Server. 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 WSO2 Identity Server. note Currently, not all extensions incorporate a requestId.
actionType	Indicates the execution point within the WSO2 Identity Server 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 WSO2 Identity Server expects

Your service must respond to the request from WSO2 Identity Server 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

WSO2 Identity Server enforces default timeout limits when calling external services:

• Connection timeout: 2 seconds
• Read timeout: 5 seconds

WSO2 Identity Server 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.

Configuring HTTP Client Timeout and Retry Settings

To configure the timeout periods and retry counts for HTTP client connections initiated by WSO2 Identity Server to external services, add the following configurations to the deployment.toml file located in the <IS_HOME>/repository/conf/ directory:

Property	Description
http_client.read_timeout	The maximum time (in milliseconds) the server will wait for a response from the external service.
http_client.request_timeout	The maximum time (in milliseconds) the server will wait to obtain a connection from the connection pool.
http_client.connection_timeout	The maximum time (in milliseconds) the server will wait to establish a connection to the external service.
http_client.connection_pool_size	The size of the HTTP connection pool used for outbound requests.
http_client.retry_count	Number of retry attempts made in case of a failure. Refer to the list of http codes that trigger retries.

Sample configuration is as follows:

[actions]
http_client.read_timeout = 6000
http_client.request_timeout = 3000
http_client.connection_timeout = 3000
http_client.connection_pool_size = 10
http_client.retry_count = 1

Troubleshooting

You can use diagnostic logs to capture detailed information during the troubleshooting process. Logs capture requests sent from WSO2 Identity Server 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 WSO2 Identity Server to the external endpoint.

{
  "logId": "582befe9-6114-4362-8fd4-05496e639fb8",
  "recordedAt": {
    "seconds": 1729488306,
    "nanos": 479103000
  },
  "requestId": "d9b5f323-79cb-4a9e-9d84-f83ab7056122",
  "resultStatus": "SUCCESS",
  "resultMessage": "Call external service endpoint https://myextension.com for Pre Issue Access Token action.",
  "actionId": "process-action-request",
  "componentId": "action-execution",
  "configurations": {
    "action id": "0ab318c4-af38-4190-ae41-75f35ecdf7b6",
    "action type": "Pre Issue Access Token",
    "action endpoint": "https://myextension.com",
    "action endpoint authentication type": "BASIC"
  },
  "logDetailLevel": "APPLICATION"
}

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.

To enable diagnostic logs in system configurations, you may add the following configurations to the deployment.toml file located in the <IS_HOME>/repository/conf directory.

[server]
diagnostic_log_mode = "full"

Note

[server] is already defined in the deployment.toml file. So you just need to add the value.

Additionally, you may use system debug logs to capture similar context information mentioned above. You can enable it component wise by following the steps described here.

For an example, your configuration should look like below.

logger.org-wso2-carbon-identity-action-execution.name=org.wso2.carbon.identity.action.execution
logger.org-wso2-carbon-identity-action-execution.level=DEBUG

loggers = org-wso2-carbon-identity-action-execution

Note

It is highly recommended to disable both diagnostic logs and system debug logs once troubleshooting is completed as it may expose sensitive information included in responses and requests.

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.