Pre-update profile action¶

The pre-update profile action in Asgardeo allows you to the validate user attributes during profile update processes. This action enables you to implement use cases such as automated verification of updated data (e.g., cross-referencing with passport or driving license information), persisting changes, or triggering notifications to updated contact details.

This action is triggered during the following profile update flows:

Self-Service Profile Update: When an end-user modifies their profile through a self-service portal like the My Account application.
Administrator-Initiated Profile Update: When an administrator updates a user's profile through a user management portal, such as the Console application.

Note

Currently, this action can only be applied at the root organization level and is invoked for any of the flows mentioned above.

How pre-update profile action works¶

When a pre-update profile action is configured with your external service endpoint, Asgardeo will call your service and wait for a response whenever a profile update action is triggered. Upon receiving the response, Asgardeo will either return a client error, server error or execute based on the response received.

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

Request from Asgardeo¶

The request from Asgardeo includes following in the JSON request payload:

Property Description

actionType

Specifies the action being triggered, which in this case is PRE_UPDATE_PROFILE.

event

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

event¶

Property Description

event.request

This property contains the details of the profile update request. Currently, it includes the list of attributes that the user is updating.

event.tenant

This property represents the tenant (root organization) under which the profile update request is being processed.

event.user

This property contains information about the user whose profile is being updated.

id

The unique numeric identifier of the user whose profile is being updated.

claims

Includes the user attributes that are configured to be shared with the external service during profile update flow. These attributes are represented as claims and represented with the WSO2 claim dialect: http://wso2.org/claims.

e.g.,

[
  {
    "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]"
    ],
    "updatingValue": [
      "[email protected]",
      "[email protected]"
    ]
  }
]

If any updating claims in the profile update request are configured to be shared with the service, the value updating will be included under the claim's updatingValue property.

groups

Indicates the user groups to which the user belongs. The groups attribute is only included in the event.user context if the http://wso2.org/claims/groups attribute is configured to be shared with the service implementing action, in the pre-update profile action configuration.

event.userStore

This property indicates the user store in which the user's data is being managed.

event.initiatorType

This property indicates whether the profile update was initiated by an administrator, a user, or an application.

event.action

This property shows if the profile update started through an update flow. Right now, it only has the value UPDATE which means the profile update is done using a standard profile update flow.

Example request from Asgardeo:¶

This example illustrates a request sent to an external service configured as a pre-update profile action, triggered when an administrator updates the user’s profile.

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


{
  "actionType": "PRE_UPDATE_PROFILE",
  "event": {
    "request": {
      "claims": [
       {
          "uri": "http://wso2.org/claims/emailAddresses",
          "value": [
            "[email protected]",
            "[email protected]",
          ]
        },
        {
          "uri": "http://wso2.org/claims/mobileNumbers",
          "value": [
            "1234566234",
            "1234566235",
            "1234566236"
          ]
        },
        {
          "uri": "http://wso2.org/claims/emailaddress",
          "value": "[email protected]"
        }
      ]
    },
    "tenant": {
      "id": "12402",
      "name": "bar.com"
    },
    "user": {
      "id": "ab49e1b8-2d1b-424d-b136-debdca67bfcc",
      "claims": [
        {
          "uri": "http://wso2.org/claims/emailAddresses",
          "value": [
            "[email protected]"
          ],
          "updatingValue": [
            "[email protected]",
            "[email protected]",

          ]
        },
        {
          "uri": "http://wso2.org/claims/mobileNumbers",
          "value": [
            "1234566234",
            "1234566235",
          ],
          "updatingValue": [
            "1234566234",
            "1234566235",
            "1234566236"
          ]
        },
        {
          "uri": "http://wso2.org/claims/identity/accountState",
          "value": "UNLOCKED"
        },
        {
          "uri": "http://wso2.org/claims/emailaddress",
          "value": "[email protected]",
          "updatingValue": "[email protected]"
        },
      ],
      "groups": [
        "gold-tier"
      ]
    },
    "userStore": {
      "id": "REVGQVVMVA==",
      "name": "DEFAULT"
    },
    "initiatorType": "ADMIN",
    "action": "UPDATE"
  }
}

Expected Response from External Service:¶

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

This response plays a crucial role in determining whether profile update is allowed or not. Here’s a breakdown of the expected response:

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

SUCCESS: Indicates that the request was processed successfully, and profile update is allowed.

FAILED: Represents a selective failure within the profile update flow due to attribute validation logic or business rules enforced by your external service. A 400 (Client Error) response is returned to the application, incorporating the failure message provided by your external service. It is your responsibility to provide a SCIM API compliant failure message when extending the flow if you expect SCIM compliance.

ERROR: Indicates a processing failure, typically caused by server-side issues. A 500 (Server Error) response is returned to the application.

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 profile update is allowed.

Http Status Code: 200

Property	Description
actionStatus	Indicates the outcome of the request. For an allowed profile update, this should be set to `SUCCESS`.

Below is an example of a success response at a profile 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 profile update. This decision is based on specific validation logic or business rules defined by your application's requirements.

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, this should be set to `FAILED`.
failureReason	Provides the reason for failing to update the profile. This value is mapped to the `scimType` field in error response of the SCIM API.
failureDescription	Offers a detailed explanation of the failure. This value is mapped to the `detail` field in error response of the SCIM API.

Below is an example of a failed response due to a validation of invalid attributes.

Response from external service:

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

{
  "actionStatus": "FAILED",
  "failureReason": "invalid_input",
  "failureDescription": "Provided user attributes are invalid."
}

This will result in the following error response being sent to the application that initiated the profile update request over 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": "invalid_input",
    "detail": "Provided user attributes are invalid.",
    "status": "400"
}

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 either a validation failure or 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`.
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, it will be treated as an error in executing the action. In any of these cases, the application that initiated the profile update request will receive a 500 Internal Server Error.

Below is an example of an error response returned by the service implementing the pre-update profile action.

Response from external service:

HTTP/1.1 500
Content-Type: application/json

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

This will result in the following error response being sent to the application that initiated the profile 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 is not directly included in the error response sent back to the application.