Pre-update password action¶

The pre-update password action in WSO2 Identity Server lets you validate a password during password update flows. You can integrate it with credential intelligence services (like HaveIBeenPwned or SpyCloud) to detect compromised passwords or to compare passwords with allowed or disallowed lists.

The WSO2 Identity Server triggers this action during the following flows involving password updates.

Self-Service Password Reset: An end-user clicks "forgot password" and goes through the password recovery process.
Profile Update: An end-user updates their password through a self-service portal like the MyAccount application.
Admin-Initiated Password Reset: An administrator forces a password reset, and the end-user subsequently resets their password.
Admin-Initiated User Invitation: An administrator invites a new user to register by resetting the password. The user then sets a new password as part of the registration flow.
Direct Admin Update: An administrator directly updates a user's password.

Note

Currently, only the root organization can apply this action, and the WSO2 Identity Server triggers it during any of the flows listed earlier.

How pre-update password action works¶

When you configure a pre-update password action with your external service endpoint, WSO2 Identity Server calls your service and waits for a response whenever a password update action triggers. Upon receiving the response, WSO2 Identity Server either returns a client error, server error, or executes based on the response.

The pre-update password API contract defines the request and response structures that your service must follow.

Request from WSO2 Identity Server¶

The request from WSO2 Identity Server includes following in the JSON request payload:

Property Description

actionType

Defines the triggering action as PRE_UPDATE_PASSWORD for this case.

event

Contains context information relevant to password update flow. Refer event section for details.

event

Property Description

event.tenant

This property identifies the tenant (root organization) handling the password update request.

event.user

This property contains information about the user associated with the password update.

id	The unique numeric identifier of the user associated with the password update.
claims	Includes the user attribute values configured for sharing with the external service during the password update flow. These attributes represent claims using the WSO2 claim dialect: `http://wso2.org/claims`. For example, `[ { "uri": "http://wso2.org/claims/identity/accountLocked", "value": "false" }, { "uri": "http://wso2.org/claims/username", "value": "[email protected]" }, { "uri": "http://wso2.org/claims/verifiedEmailAddresses", "value": [ "[email protected]" ] }, { "uri": "http://wso2.org/claims/emailAddresses", "value": [ "[email protected]", "[email protected]" ] } ]`
groups	Indicates the user groups to which the user belongs. The `event.user` context includes the `groups` attribute only when the pre-update password action configuration contains the `http://wso2.org/claims/groups` attribute for sharing with the external service.
updatingCredential	The user's new password, provided either as a hashed value or in plain text, depending on the pre-update password action configuration. This JSON object includes the password, the format used to share it (hashed or plain text), and the hashing algorithm if used. For example, `{ "type": "PASSWORD", "format": "HASH", "value": "cHRSHCjvmT", "additionalData": { "algorithm": "SHA256" } }` The pre-update password action configuration can enforce encryption of the `updatingCredential` object by providing a public certificate. The WSO2 Identity Server uses this certificate to encrypt the object with asymmetric encryption and shares it as a JWE.

event.userStore

This property indicates the user store that manages the user's data.

event.initiatorType

This property indicates whether an administrator, a user, or an application initiated the password update. Refer initiatorType and action properties in request section for details.

event.action

This property indicates whether a password reset flow, update flow, or an invite flow initiated the password update. Refer initiatorType and action properties in request section for details.

`initiatorType` and `action` properties in request

The initiatorType and the action property in combination denotes the flow that triggers a password update.

The following shows how the initiatorType and action properties differ based on the flow.

Flow	Value of `initiatorType`	Value of `action`	Description
User initiated password update	USER	UPDATE	This occurs when a user updates their password directly through their profile settings in MyAccount app or via SCIM 2.0 Me API .
User initiated password reset	USER	RESET	This occurs when a user has forgotten their password and initiates a reset flow to regain access to their account.
Admin initiated password update	ADMIN	UPDATE	This occurs when an administrator updates a user's password directly via console or SCIM 2.0 Users API.
Admin initiated password reset	ADMIN	RESET	This occurs when an administrator initiates a forced password reset and the user resets the password via that request.
Admin initiated user invite to set password	ADMIN	INVITE	This occurs when an administrator invites a new user to join the system, prompting the user to set their password.
Application initiated password update	APPLICATION	UPDATE	This occurs when an application with appropriate permissions automatically updates a user's password, often as part of an automated user provisioning process or integration with external identity management systems via SCIM 2.0 Users API.

Example request from WSO2 Identity Server

This example illustrates a request sent to an external service configured as a pre-update password action, triggered when a user updates their password.

POST /password-update-action HTTP/1.1
Host: localhost
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json

{
  "actionType": "PRE_UPDATE_PASSWORD",
  "event": {
    "tenant": {
      "id": "1",
      "name": "example.com"
    },
    "user": {
      "id": "8eebb941-51e1-4d13-9d5a-81da190383ae",
      "claims": [
        {
          "uri": "http://wso2.org/claims/username",
          "value": "[email protected]"
        },
        {
          "uri": "http://wso2.org/claims/emailAddresses",
          "value": [
            "[email protected]",
            "[email protected]"
          ]
        }
        ],
        "groups": [
          "employee",
          "manager"
        ],
      "updatingCredential": {
        "type": "PASSWORD",
        "format": "HASH",
        "value": "h3bxCOJHqx4rMjBCwEnCZkB8gfutQb3h6N/Bu2b9Jn4=",
        "additionalData": {
          "algorithm": "SHA256"
        }
      }
    },
    "userStore": {
      "id": "UFJJTUFSWQ==",
      "name": "PRIMARY"
    },
    "initiatorType": "USER",
    "action": "UPDATE"
  }
}

Expected response from external service¶

When WSO2 Identity Server invokes your external service as part of the pre-password update action, it expects a response that adheres to the defined API contract here.

This response plays a crucial role in determining whether to permit the password update. Here’s a breakdown of the expected response:

The response can have three possible states: SUCCESS, FAILEDand ERROR.

SUCCESS: Indicates successful request processing and permits the password update.

FAILED: Represents a selective failure within the password update flow due to password validation logic or business rules enforced by your external service. The application receives a 400 (Client Error) response that includes the failure message from your external service.

ERROR: Indicates a processing failure, typically caused by server-side issues. The application receives a 500 (Server Error) response.

Response for SUCCESS state

When the external service responds with a 200 status code and a SUCCESS state, it indicates that the request completed successfully and permits the password update.

Http Status Code: 200

Property	Description
actionStatus	Indicates the outcome of the request. To permit the password update, set this to `SUCCESS`.

The following shows an example of a success response from a password update request.

Response from external service:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "actionStatus": "SUCCESS",
}

Response for FAILED state

When the external service returns a 200 OK status code with a FAILED state, it means the service has intentionally opted to reject the password update. This decision follows specific validation logic or business rules defined by your application.

The response body must be a JSON object containing the following properties:

Http Status Code: 200

Property	Description
actionStatus	Indicates the outcome of the request. For a failed operation, set this to `FAILED`.
failureReason	Provides the reason for failing to update the password. This value currently doesn't map to the SCIM API response.
failureDescription	Offers a detailed explanation of the failure. This value maps to the `detail` field in the error response of the SCIM API.

The following shows an example of a failed response due to a validation of compromised passwords.

Response from external service:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "actionStatus": "FAILED",
  "failureReason": "Compromised password",
  "failureDescription": "The provided password is compromised. Provide something different."
}

This results in the following error response sent to the application that initiated the password update request over the SCIM API.

Error response to the application:

HTTP/1.1 400 
Content-Type: application/json

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "scimType": "invalidValue",
    "detail": "The provided password is compromised. Provide something different.",
    "status": "400"
}

Following error response returned to the application that initiated the password update request through the forgot password, forced reset, or user invitation flow using the password reset API.

Error response to the application:

HTTP/1.1 400 
Content-Type: application/json

{
    "code": "20067",
    "message": "invalid_format",
    "description": "Invalid password format.",
    "traceId": "c6389827-8fee-4235-928f-96295d192181"
}

Response for ERROR state

When the external service returns an ERROR state, it sends a 400, 401, or 500 HTTP status code indicating validation failure or processing issues.

Http Status Code: 400, 401 or 500

Property	Description
actionStatus	Indicates the request outcome. Set this to `ERROR` for an error operation.
errorMessage	Describes the cause of the error..
errorDescription	A detailed description of the error..

If the external service returns an error response (either defined or undefined) or fails to respond entirely, the WSO2 Identity Server treats it as an error in executing the action. In any of these cases, the application that initiated the password update request will receive a 500 Internal Server Error.

The following shows an example of an error response returned by the service implementing the pre-update password action.

Response from external service:

HTTP/1.1 500
Content-Type: application/json

{
  "actionStatus": "ERROR",
  "errorMessage": "Server error",
  "errorDescription": "Error while processing request."
}

This results in the following error response sent to the application that initiated the password update request over SCIM API.

Error response to the application:

HTTP/1.1 500 
Content-Type: application/json

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "detail": "Error while updating attributes of user: A***n",
    "status": "500"
}

Note

Currently, the errorMessage or errorDescription from the external service’s ERROR response doesn't directly include in the error response sent back to the application.

Conditional invocation of pre-update password action¶

Pre-update password actions trigger conditionally based on configurable rule criteria. The rule configuration currently supports the following field:

Flow: The specific user password updating flows in the product.
Admin initiated password reset
Admin initiated password update
Admin initiated user invite to set password
Application initiated password update
User initiated password reset
User initiated password update

The rule field supports the following operators:

equals
not equals

You can specify exact values for the field, such as an Admin initiated password update. Combine rules using logical AND/OR operators to control precisely when the pre-update password action triggers.

pre-update-password-rule-configuration

This rule configuration translates logically to:

The flow should equals to Admin initiated password reset or Admin initiated password update to trigger the pre-update password action.