Rate this page

Verify Account Flow

Schema URN
urn:pingidentity:scim:api:messages:2.0:AccountFlow:VerifyAccountRequest

The Verify Account flow is a special flow that is used to mark a user account as verified, usually by confirming that the user controls a contact mechanism associated with the account, such as an email address or phone number.

This flow is triggered by the Data Governance Broker’s Account Verification policy. By default, this policy simply looks for a boolean attribute called accountVerified. If it is false, then this flow is triggered.

Field Type Provided? Description
schemas array always The SCIM schema of the Verify Account flow. Always has the value urn:pingidentity:scim:api:messages:2.0:AccountFlow:VerifyAccountRequest.
meta complex always By default, will contain a resourceType sub-attribute with the value Verify Account. Will always contain a location sub-attribute with the current flow URI.
followUp complex always An object indicating the authorization endpoint URI to be retrieved when this flow is complete. Will always contain a type sub-attribute and a $ref sub-attribute; the latter is the URI to be retrieved.
sessionIdentityResource complex If an end user is already logged in, the sub-attributes of this object are attribute values of the user that may be displayed by the auth UI. Examples might include the end user’s username, full name, or icon. The attributes included here are determined by the Session Resource Attribute property of the Broker’s Authentication Service configuration.
success boolean Will be present with a value of true if the flow’s enforcement criteria have been satisfied.
accountVerifiedResourceAttributes object This is an object provided by the auth UI, consisting of attribute names and values to be set on the user resource to indicate that the account is verified. This must be provided to satisfy the Verify Account flow.

In addition to the fields above, objects representing any identity authenticators associated with the Verify Account flow in the Broker configuration will be listed in a Verify Account flow message.

Here is an example Verify Account message, which uses the Email Delivered Code authenticator.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:VerifyAccountRequest"
  ],
  "meta": {
    "resourceType": "Verify Account",
    "location": "https://example.com/authentication/account/Verify%20Account/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": false,
    "status": "ready"
  }
}

Example: Verify an account

In this example, an account will be marked as verified after the Email Delivered Code authenticator is satisfied.

The auth UI begins by sending a verification code.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:VerifyAccountRequest"
  ],
  "meta": {
    "resourceType": "Verify Account",
    "location": "https://example.com/authentication/account/Verify%20Account/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": false,
    "status": "ready",
    "codeRequested": true
  }
}

The Auth API responds by acknowledging that a verification code was sent.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:VerifyAccountRequest"
  ],
  "meta": {
    "resourceType": "Verify Account",
    "location": "https://example.com/authentication/account/Verify%20Account/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "success": false,
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": true,
    "status": "failure"
  }
}

After the end user receives the code and provides it to the auth UI, the auth UI submits the code to the Auth API.

Since this is the last step, the auth UI should also provide the accountVerifiedResourceAttributes field. This object contains one or more attributes and values to set on the user’s account, marking the account as verified.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:VerifyAccountRequest"
  ],
  "meta": {
    "resourceType": "Verify Account",
    "location": "https://example.com/authentication/account/Verify%20Account/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "success": false,
  "accountVerifiedResourceAttributes": {
    "accountVerified": true
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": true,
    "status": "failure",
    "verifyCode": "978522"
  }
}

The Verify Account flow is now satisfied, and the Auth API marks its success flag as true.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:VerifyAccountRequest"
  ],
  "meta": {
    "resourceType": "Verify Account",
    "location": "https://example.com/authentication/account/Verify%20Account/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "success": true,
  "accountVerifiedResourceAttributes": {
    "accountVerified": true
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": true,
    "status": "success"
  }
}