Enable Email Account Verification for an Updated Email Address¶

This feature enables email account verification when the user updates the user profile with a new email address, so that the new email address can be taken into consideration for all further activities performed by the user.

When users update their email addresses in the user profile, an email verification is triggered to the new email address. Until the new email address is verified successfully, the user's existing email address is not overridden.

Step 01 - Configure the email adapter to send emails¶

1. Navigate to the <IS_HOME>/repository/conf/deployment.toml file and uncomment the [output_adapter.email] configuration block.

   [output_adapter.email]
   from_address= "wso2iam@outlook.com"
   username= "wso2iam@outlook.com"
   password= "xxxx"
   hostname= "smtp.office365.com"
   port= 587

   Info

   • If you use a Gmail account as the email OTP sender, you must create an App Password. After you get an App Password from Google, update the password.
   • If your password contains special characters (example: <, >, &), you will run into errors when running the server. To avoid errors, update the password parameter as follows:

     password= "<![CDATA[xxxx]]>"

2. Update the sample values with your email adapter configurations.

   Info

   Refer configure email sending module for the complete list of email adapter configurations.

3. Save the configurations and restart the server.

Step 02 - Enable the feature in the management console¶

1. In the management console, navigate to Main > Identity Providers > Resident > Other Settings > User Claim Update.

2. Mark Enable user email verification on update. Additionally, you can define the expiry time for the verification link to match your requirement.

   

3. Click Update to save the changes.

Try it out¶

You can use either the My Account application or SCIM 2.0 API to try out the feature.

My Account¶

The My Account application which provided the capability for users to manage their user account-related preferences, can also be used to try out this feature.

1. Access the My Account URL: https://<HOST_NAME>:<PORT>/myaccount/.

2. Enter the username and password and click Sign In.

3. Click the Personal info tab on the side panel to view Profile information of the user.

4. Click on the pencil icon aligning with the Email field.

5. Update the new email address in the profile and click Save.

The user will receive an email notification to verify the account and the following notification will be displayed until the account confirmation happens.

SCIM 2.0¶

This feature can also be invoked via a PUT/PATCH request to SCIM 2.0 /Users endpoint or /Me endpoint.

Given below is a sample request and the relevant response for updating the email address via a PATCH operation to SCIM 2.0 Users endpoint.

curl -v -k --user [username]:[password] -X PATCH -d '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations":[{"op":[operation], "value":{ "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {"verifyEmail": [true/false]}, "emails":[{"primary":true, "value":[new email]}]}}]}' --header "Content-Type:application/json" https://localhost:9443/scim2/Users/[user ID]

curl -v -k --user admin:admin -X PATCH -d '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations":[{"op":"replace","value":{ "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {"verifyEmail": "true"}, "emails":[{"primary":true,"value":"kim.jackson.new@gmail.com"}]}}]}' --header "Content-Type:application/json" https://localhost:9443/scim2/Users/1e624046-520c-4628-a245-091e04b03f21

Sample Response

{
    "emails":[
        "kimjack@gmail.com"
    ],
    "meta":{
        "created":"2020-01-07T09:32:18",
        "location":"https://localhost:9443/scim2/Users/1e624046-520c-4628-a245-091e04b03f21",
        "lastModified":"2020-01-07T14:18:49",
        "resourceType":"User"
    },
    "schemas":[
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User":{
        "pendingEmails":[
            {
                "value":"kim.jackson.new@gmail.com"
             }
        ]
    },
    "roles":[
        {
            "type":"default",
            "value":"Internal/everyone"
        }
    ],
    "name":{
        "givenName":"kim",
        "familyName":"jackson"
    },
    "id":"1e624046-520c-4628-a245-091e04b03f21",
    "userName":"kim"
}

The new email address is represented in the SCIM response as an attribute of Enterprise User Extension. Given below is the extracted representation of it.

{"pendingEmails":[{"value":"kim.jackson.new@gmail.com"}]}

Upon receiving the response as given above, the user will receive an email notification to verify the account. By successfully confirming the account, the user’s emailaddress claim (http://wso2.org/claims/emailaddress), will be updated with the newly-verified email address.

Resend email verification¶

Run the following curl command to resend email verification upon updating the email address.

Request

curl -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{"user":{"username": <USERNAME>,"realm": <REALM>"},"properties": [{"key":"RecoveryScenario","value":"EMAIL_VERIFICATION_ON_UPDATE"}]}' "https://localhost:9443/api/identity/user/v1.0/resend-code" -k -v

Sample

curl -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{"user":{"username": "admin","realm": "PRIMARY"},"properties": [{"key":"RecoveryScenario","value":"EMAIL_VERIFICATION_ON_UPDATE"}]}' "https://localhost:9443/api/identity/user/v1.0/resend-code" -k -v

HTTP/1.1 201 Created