Extending User Self Registration and Account Confirmation

This guide provides information regarding the APIs used for this implementation.

• • Mobile claim: http://wso2.org/claims/mobile
  • Email claim: http://wso2.org/claims/emailaddress

• User self-registration can be configured tenant wise (For more information, see user self-registration configurations ).
  
  

• WSO2 Identity Server supports two types of self-registration requests:

  Type	Description
  Self-registration with pre-verified claims	The user is already verified prior to the self-registration using an external mechanism. Therefore, there is no need to verify the user account. This feature is only supported when the prior verified channel is either EMAIL or SMS. If any of the above channels are verified external to WSO2 Identity Server, the Phone Verified and Email Verified claims need to be included in the request with the value set to TRUE.  For example, if the mobile number is already verified, then the Phone verified claim needs to be in the self-registration request with the value set to TRUE. Mobile Verified: http://wso2.org/claims/identity/phoneVerified Email Verified: http://wso2.org/claims/identity/emailVerified
  Self-registration with post user account verifications	The user is not verified prior to the self-registration. The user account needs to be verified after the user self-registration process via internal channels or external channels.

• A claim with a user’s preference can be included in the request. To do this, add a new claim called "Preferred Channel". This claim is optional but it is recommended to send the claim with the request as follows:

  Preferred channel: http://wso2.org/claims/identity/preferredChannel

• Once the server receives a self-registration request, the server will send notifications based on the following scenarios:

• Initiate a self-registration request and verify the user account via WSO2 IS
  The server sends notifications to the user by resolving the communication channel internally. The notification channel resolution is as follows.

• Initiate a self-registration request, verify user account externally and confirm the flow to WSO2 IS.
  The server provides a confirmation code to be used to confirm the user account.

• Self-register after pre-confirmation of the user account, with verified claims.
  The user is already verified. In this case, the user account should not be locked or prompted for verification. Therefore, no notifications are sent.

Notification channel selection criteria

1. The user inputs the notification details with other user claims. 
2. If channel resolving is not enabled, the notification channel is set to use the server default notification channel. 
3. If it is enabled, the next check is if the user has specified a preferred channel:
   1. If the user has only provided an email address or mobile number as the communication channel and has not specified a preferred channel, the notification will be sent via the channel that is given in the request as a claim value.  
      For example, if only the mobile number has been provided, the mobile (SMS) is considered as the preferred channel. 
   2. If the user has specified a preferred channel and the preferred channel matches the given claim value, the notification is sent via the preferred channel. 
      For example, the preferred channel is specified as SMS and has provided claim value is a mobile number.

   3. If the user has specified a preferred channel and the preferred channel does not match the given claim value, a 400 ERROR is returned.  
      For example, the preferred channel is specified as SMS but there is no claim value or the provided value is not a mobile number.

      Notification Channel	Value Claim
      Email	http://wso2.org/claims/emailaddress
      SMS	http://wso2.org/claims/mobile

   4. If the user has provided both email and mobile as communication channels and has specified the preferred channel, the notification will be sent via the preferred channel. 
   5. If the user has provided both email and mobile as communication channels but not specified the preferred channel, the notification will be sent via the server default channel. 

4. Once the communication channel is resolved, an event is triggered. Once the event is triggered, the notification handlers will send notifications to the user.
   The event name will be in the following format.

   Channel	Event Name
   SMS	TRIGGER_SMS_NOTIFICATION
   Email	TRIGGER_NOTIFICATION

API requests and responses

Scenario one: User self registers when notifications are internally managed and the account is locked on creation.

Scenario Two:  User self registers when notifications are externally managed and the account is locked on creation. 

Scenario Three:  The user self registers and the account is not locked on creation.

When the account is unlocked on user creation, no notifications will be sent to the user and the account of the user will not be locked at creation. The following response will be returned by the API (HTTP: 201).

{
"code": "USR-02003",
"message": "Successful user self registration. Account not locked on user creation",
"notificationChannel": null,
"confirmationCode": null
}

Error responses

• Providing an existing username (HTTP: 409)

  {
  "code": "20030",
  "message": "Conflict",
  "description": "User TestUser1 already exists in the system. Please use a different username."
  }

• Preferred channel not supported by the server (HTTP: 400)
  

  {
  "code": "USR-10001",
  "message": "Bad Request",
  "description": "User specified communication channel is not supported by the server"
  }

• Not providing value to the preferred channel claim (HTTP: 400)
  Example: specifying the preferred channel as EMAIL but not providing the claim value for the  http://wso2.org/claims/emailaddress claim
  

  {
  "code": "USR-10002",
  "message": "Bad Request",
  "description": "User specified communication channel does not have any value"
  }

Account confirmation API 

For account confirmations, WSO2 Identity Server now supports multiple verification channels and allows defining the verified channel (i.e., whether the account confirmation was communicated via EMAIL or SMS) in the API request.  A sample request JSON body is as follows.

{
"code": "1a39ec29-9417-4f69-93b6-b7f2bbf75413",
"verifiedChannel":{"type":"SMS", "claim":"http://wso2.org/claims/mobile"},
"properties": []
}

Using the verifiedChannel parameter, the user can be verified with any server supported channel. In the above example, using the confirmation code, the SMS channel for the user can be set as the verified notification channel.

curl -k -v -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H  "Content-Type: application/json" -d '{ "code": "84325529-8aa7-4851-8751-5980a7f2d9f7","verifiedChannel":{"type":"SMS", "claim":"http://wso2.org/claims/mobile"},"properties": []}' "https://localhost:9443/api/identity/user/v1.0/validate-code"

Parameters