Requests and Responses of User Self Registration REST APIs in WSO2 Identity Server
In my previous blog, I’ve explained how user self registration works in a nutshell. In this blog I will explain the API requests and responses. Please note that this feature is available for WSO2 IS 5.7.0 WUM updated version and will be available for WSO2 IS 5.10.0 which will be released in the near future.
Notification Management
Before moving forward I would like to explain about the notification management mechanisms that WSO2 Identity Server Offers. The Identity Server provides the capability for the application developer to manage notifications internally or externally.
- Internal notification management: The server will send the notifications to the user and the verification will be done by the server for given confirmation codes.
- External notification management: The server will not send any notifications. This scenario is used when the developer has an in-house notification management system (separate external notification management mechanism).
Navigate to Main>Identity>Identity Providers>Account Management Policies>User Self Registration to activate the feature.
Also I would like to explain another property related to self registration called Enable Account Lock On Creation. When this property is enabled, the account of the user will be locked on creation. To unlock the account, the user needs to confirm the account by using the confirmation code issued by the server.
Self Registration API Requests and Responses
The feature improvement is provided for the existing User-Self Registration APIs. Therefore you can refer to the API documentation for more details. In this blog, I will only explain about the new feature.
With the added functionality, the responses of the existing APIs have been improved. To support the backward compatibility, we have introduced a new property to enable detailed responses. By default, the improved responses are not returned. To enable the improved responses add the following configurations to the identity.xml file in <HOME>/repository/conf/identity folder inside <SelfRegistration> tags.
<API>
<EnableDetailedResponseBody>true</EnableDetailedResponseBody>
</API>(Please refer to my blog on configuring IS to support multiple notification channels for more details on configuring the server and adding channel related claims)
During this article, I will use the above property enabled, to demonstrate the improved API responses.
A detailed API Request
curl -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{"user": {"username": "kim","realm": "PRIMARY", "password": "Password12!","claims": [{"uri": "http://wso2.org/claims/givenname","value": "kim" },{"uri": "http://wso2.org/claims/emailaddress","value": "kim.anderson@gmail.com"},{"uri": "http://wso2.org/claims/identity/phoneVerified","value": "true"},{"uri": "http://wso2.org/claims/lastname","value": "Anderson"},{"uri": "http://wso2.org/claims/identity/preferredChannel","value": "EMAIL"}, {"uri": "http://wso2.org/claims/mobile","value": "+947721584558"} ] },"properties": []}' "https://localhost:9443/api/identity/user/v1.0/me"In the above request note that there is separate identity claims to get the user preferred notification channel and verified notification channels.
{"uri": "http://wso2.org/claims/identity/preferredChannel","value": "EMAIL"}As I mentioned in my previous blog, above claim is an optional claim. When the server receives the above request, the server will validate the channel and verified claims and then notification will be triggered.
User self registers when notifications are internally managed and the account is locked on creation.
The API will return http code: 201 for successful user registration with the following responses. Following are the two sub scenarios.
- The user self registers with verified claims : In this scenario, if the verified claims match the preferred notification channel, the user will be created and the account will be unlocked since the user is already verified via the preferred channel. (Refer to my previous blog to read about the preferred channel selection criteria)(NOTE: The received verified claim will be set as an attribute to the user)
Sample Request
curl -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{"user": {"username": "kim","realm": "PRIMARY", "password": "Password12!","claims": [{"uri": "http://wso2.org/claims/givenname","value": "kim" },{"uri": "http://wso2.org/claims/emailaddress","value": "kim.anderson@gmail.com"},{"uri": "http://wso2.org/claims/identity/emailVerified","value": "true"},{"uri": "http://wso2.org/claims/lastname","value": "Anderson"},{"uri": "http://wso2.org/claims/mobile","value": "+947721584558"} ] },"properties": []}' "https://localhost:9443/api/identity/user/v1.0/me"Sample Response
{
"code": "USR-02004",
"message": "Successful user self registration with verified channel. Account verification not required.",
"notificationChannel": null,
"confirmationCode": null
}If the verified claims do not match the preferred notification channel, the user will be created and the user will be asked to verify the account via the preferred channel. (Eg: If the preferred channel is EMAIL and SMS channel is verified)
{"uri": "http://wso2.org/claims/identity/phoneVerified","value": "true"},
{"uri": "http://wso2.org/claims/identity/preferredChannel","value": "EMAIL"}(NOTE: The received verified claim will be set as an attribute to the user and the account will be unlocked only upon the confirmation)
Sample Response
{
"code": "USR-02001",
"message": "Successful user self registration. Pending account verification",
"notificationChannel": "EMAIL",
"confirmationCode": null
}2. The user self registers without verified claims : A notification will be sent to the user and the user will be asked to verify via the preferred channel (Refer to my previous blog to read about the preferred channel selection criteria). The following response will be returned by the API. (NOTE: After confirming the user account, the confirmed channel will be considered as a verified channel)
Sample Request
curl -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{"user": {"username": "kim","realm": "PRIMARY", "password": "Password12!","claims": [{"uri": "http://wso2.org/claims/givenname","value": "kim" },{"uri": "http://wso2.org/claims/emailaddress","value": "kim.anderson@gmail.com"},{"uri": "http://wso2.org/claims/lastname","value": "Anderson"},{"uri": "http://wso2.org/claims/mobile","value": "+947721584558"} ] },"properties": []}' "https://localhost:9443/api/identity/user/v1.0/me"Sample Response
{
"code": "USR-02001",
"message": "Successful user self registration. Pending account verification",
"notificationChannel": "SMS",
"confirmationCode": null
}User self registers when notifications are externally managed and account is locked on creation
This scenario is similar to the above scenario, except for the self registration API responses. If the user self registration is successful, http code: 201 will be returned with the following responses. Following are the two sub scenarios.
- The user self registers with verified claims : This scenario is identical to the above scenario. In this scenario, if the verified claims match the preferred notification channel, the user will be created and the account will be unlocked since the user is already verified via the preferred channel.
{
"code": "USR-02004",
"message": "Successful user self registration with verified channel. Account not locked on user creation.",
"notificationChannel": null,
"confirmationCode": null
}However, if the verified claims do not match the preferred notification channel, the response will be different.
{
"code": "USR-02002", "message":
"Successful user self registration. External verification required",
"notificationChannel": "EXTERNAL",
"confirmationCode": "fb03f437-a46f-4da1-8e99-fafab4aad4a4"
}Note that the API has returned a confirmation code. Now the application developer has to verify the user externally and confirm the flow to IS using the returned confirmation code. I will get back to account confirmation later.
2. The user self registers without verified claims : This scenario is similar to the above except for the API response. A notification will be sent to the user and the user will be asked to verify via the preferred channel.
{
"code": "USR-02002", "message":
"Successful user self registration. External verification required",
"notificationChannel": "EXTERNAL",
"confirmationCode": "fb03f437-a46f-4da1-8e99-fafab4aad4a4"
}In this scenario, the API will return a confirmation code to verify the user account externally.
User self registers with account lock on creation is disabled
When the account lock on user creation is disabled, no notifications will be sent to the user and the account of the user will not be locked. The API will return the following response.
{
"code": "USR-02003",
"message": "Successful user self registration. Account not locked on user creation",
"notificationChannel": null,
"confirmationCode": null
}However, when a user self registers with verified claims priority will be given to the verified claims.
- In this scenario, if the verified claims match the preferred notification channel, the user will be created and the account will be unlocked.
- If the verified claims do not match the preferred notification channel, the user will be created and the account will be unlocked since account lock on user creation is disabled.
Error Responses
- Providing an existing username. (HTTP code: 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 code: 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 code: 400) Eg: Specifying preferred channel as EMAIL but not providing value for http://wso2.org/claims/emailaddress claim.
{
"code": "USR-10002",
"message": "Bad Request",
"description": "User specified communication channel does not have any value"
}If any server errors were occurred, a detailed error response will be returned by the server with Http code 500.
Account Confirmation API requests
As I explained in my previous blog, the server uses existing API for account confirmation. In here I will explain the new additions to the API request.
Sample Request
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"verifiedChannel is a newly introduced parameter which is optional in the request. Let me explain the parameter a bit more.
- Type: Type of the verified notification channel. Currently, IS supports only SMS and EMAIL channels. (NOTE: EXTERNAL is not a channel type)
- Claim: Claim of the verified channel (NOTE: All the claims and terms are case sensitive)
If the Request excluded verifiedChannel parameter, the Email Verified claim will be set to TRUE.
If the Request included the verifiedChannel parameter, and the verified channel is supported by the server, verified claim associated with that channel will be set to TRUE. If the verified channel is not supported, an error will be thrown.
Alright folks this is how the API responds to different requests. Even through the new feature uses the existing APIs, the server requires several additional configurations to use the new feature. So make sure to check my blog on configuring user self registration to support multiple notification channels.