Supporting Email Account Verification for an Updated Email Address

When the email attribute is updated using the SCIM 2.0 Users endpoint or Me endpoint via a PATCH/ PUT operation, this feature will allow the updated email address to be considered for the email account verification. 

Follow the steps given below to supporting email account verification when the currently verified email address is updated by the user.

Step 01: Configure email settings

Configure <IS_HOME>/repository/conf/output-event-adapters.xml to send emails. For more information, see here.

Step 02: Subscribe UserEmailVerification handler to PRE_SET_USER_CLAIMS and POST_SET_USER_CLAIMS events

Navigate to  <IS_HOME>/repository/conf/identity/identity-event.properties.

1. Add the following configurations under module.name.7=userEmailVerification.

   userEmailVerification.subscription.3=PRE_SET_USER_CLAIMS
   userEmailVerification.subscription.4=POST_SET_USER_CLAIMS

2. Save the file and restart the server.

Step 03: Add a new claim to persist the email address to be updated until the account is verified

In the management console, navigate to Main > Identity > Claim > Add > Add Local Claim and add the following identity claim.

1. Claim URI: http://wso2.org/claims/identity/emailaddress.pendingValue
2. Display Name: Verification Pending Email
3. Description: Claim to store newly updated email address until the new email address is verified.
4. Mapped Attribute: Provide an attribute name from the underlying user store that is mapped to the Claim URI value. For example: stateOrProvinceName. Make sure the attribute name is an unused one.
5. Enable Supported by Default to display the newly introduced attribute on the user profile.
6. Mark the claim as Read only.

Step 04: Define an attribute for the new claim using “Enterprise User Extension” for SCIM2

1. Add the configuration given below in scim2-schema-extension.config in the <IS_HOME>/repository/conf directory.

   {
   "attributeURI":"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:pendingEmails.value",
   "attributeName":"value",
   "dataType":"string",
   "multiValued":"false",
   "description":"Store email to be updated as a temporary claim till email verification happens.",
   "required":"false",
   "caseExact":"false",
   "mutability":"readOnly",
   "returned":"default",
   "uniqueness":"none",
   "subAttributes":"null",
   "canonicalValues":[],
   "referenceTypes":[]
   },
   {
   "attributeURI":"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:pendingEmails",
   "attributeName":"pendingEmails",
   "dataType":"complex",
   "multiValued":"true",
   "description":"The User's email addresses. A complex type that represents verification pending email addresses of the user.",
   "required":"false",
   "caseExact":"false",
   "mutability":"readOnly",
   "returned":"default",
   "uniqueness":"none",
   "subAttributes":"value",
   "canonicalValues":[],
   "referenceTypes":[]
   },

   
   

   Then add emails to the sub-attribute list of wso2Extension (attribute configuration with attributeURI, urn:ietf:params:scim:schemas:extension:enterprise:2.0:User).

   "subAttributes" : "verifyEmail askPassword employeeNumber costCenter organization division department manager pendingEmails".

   {
   "attributeURI":"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
   "attributeName":"EnterpriseUser",
   "dataType":"complex",
   "multiValued":"false",
   "description":"Enterprise User",
   "required":"false",
   "caseExact":"false",
   "mutability":"readWrite",
   "returned":"default",
   "uniqueness":"none",
   "subAttributes":"verifyEmail askPassword employeeNumber costCenter organization division department manager pendingEmails",
   "canonicalValues":[],
   "referenceTypes":["external"]
   }

2. Save the file and restart the server.

3. In the management console, navigate to Main > Identity > Claim > Add > Add External Claim.  Add the external claim configurations as shown below:

   1. Dialect URI: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
   2. Claim URI: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:pendingEmails.value
   3. Mapped Local Claim: http://wso2.org/claims/identity/emailaddress.pendingValue

Step 05: Add a new email template

1. Add email template type.
   1. In the management console, navigate to Main > Manage > Email Templates > Add > Add Email Template Type.
   2. Add VerifyEmailOnUpdate as the Template Type Display Name.
2. Add email template.
   1. In the management console, navigate to Main > Manage > Email Templates > Add > Add Email Template.
   2. Add the email template configurations as shown below:
      1. Select Email Template Type: VerifyEmailOnUpdate
      2. Subject: WSO2 - Email Confirmation

      3. Email Body:

         <table align="center" cellpadding="0" cellspacing="0" border="0" width="100%"bgcolor="#f0f0f0">
                     <tr>
                     <td style="padding: 30px 30px 20px 30px;">
                         <table cellpadding="0" cellspacing="0" border="0" width="100%" bgcolor="#ffffff" style="max-width: 650px; margin: auto;">
                         <tr>
                             <td colspan="2" align="center" style="background-color: #333; padding: 40px;">
                                 <a href="http://wso2.com/" target="_blank"><img src="http://cdn.wso2.com/wso2/newsletter/images/nl-2017/wso2-logo-transparent.png" border="0" /></a>
                             </td>
                         </tr>
                         <tr>
                             <td colspan="2" align="center" style="padding: 50px 50px 0px 50px;">
                                 <h1 style="padding-right: 0em; margin: 0; line-height: 40px; font-weight:300; font-family: 'Nunito Sans', Arial, Verdana, Helvetica, sans-serif; color: #666; text-align: left; padding-bottom: 1em;">
                                     Email Confirmation
                                 </h1>
                             </td>
                         </tr>
                         <tr>
                             <td style="text-align: left; padding: 0px 50px 20px 50px;" valign="top">
                                 <p style="font-size: 18px; margin: 0; line-height: 24px; font-family: 'Nunito Sans', Arial, Verdana, Helvetica, sans-serif; color: #666; text-align: left; padding-bottom: 3%;">
                                     Hi {{user.claim.givenname}},
                                 </p>
                                 <p style="font-size: 18px; margin: 0; line-height: 24px; font-family: 'Nunito Sans', Arial, Verdana, Helvetica, sans-serif; color: #666; text-align: left; padding-bottom: 3%;">
                                     Your email address has been updated for the account with the following user name. <br>
                                     User Name: <b>{{user-name}}</b><br>
                                     Please click the button below to verify your updated email address.
                                 </p>
                             </td>
                         </tr>
                         <tr>
                             <td style="padding: 0px 50px 0px 50px; text-align: left;">
                                 <table align="left" cellpadding="0" cellspacing="0" border="0" style="border-radius: 4px; background-color: #ff5000;">
                                     <tr>
                                         <td style="border-radius: 6px;  padding: 14px 0px;">
                                             <a href="{{carbon.product-url}}/accountrecoveryendpoint/confirmregistration.do?confirmation={{confirmation-code}}&userstoredomain={{userstore-domain}}&username={{url:user-name}}&tenantdomain={{tenant-domain}}"
                                                target="_blank" style="width: 230px; font-family: 'Nunito Sans', Arial, Verdana, Helvetica, sans-serif;  font-size: 18px; line-height: 21px; font-weight: 600; color: #fff; text-decoration: none; background-color: #ff5000; text-align: center; display: inline-block;cursor: pointer;">Confirm</a>
                                         </td>
                                     </tr>
                                 </table>
                             </td>
                         </tr>
                         <tr>
                             <td style="text-align: left; padding: 40px 50px 0px 50px;" valign="top">
                                 <p style="font-size: 18px; margin: 0; line-height: 24px; font-family: 'Nunito Sans', Arial, Verdana, Helvetica, sans-serif; color: #505050; text-align: left;">
                                     If clicking the button doesn't seem to work, you can copy and paste the following link into your browser. <br/>
                                     <a style="word-break: break-all; color: #ff5000; font-size: 14px" target="_blank"
                                        href="{{carbon.product-url}}/accountrecoveryendpoint/confirmregistration.do?confirmation={{confirmation-code}}&userstoredomain={{userstore-domain}}&username={{url:user-name}}&tenantdomain={{tenant-domain}}">
                                         {{carbon.product-url}}/accountrecoveryendpoint/confirmregistration.do?confirmation={{confirmation-code}}&userstoredomain={{userstore-domain}}&username={{url:user-name}}&tenantdomain={{tenant-domain}}</a>
                                 </p>
                             </td>
                         </tr>
                         <tr>
                             <td style="text-align: left; padding: 30px 50px 50px 50px;" valign="top">
                                 <p style="font-size: 18px; margin: 0; line-height: 24px; font-family: 'Nunito Sans', Arial, Verdana, Helvetica, sans-serif; color: #505050; text-align: left;">
                                     Thanks,<br/>WSO2 Identity Server Team
                                 </p>
                             </td>
                         </tr>
                         <tr>
                             <td colspan="2" align="center" style="padding: 20px 40px 40px 40px;" bgcolor="#f0f0f0">
                                 <p style="font-size: 12px; margin: 0; line-height: 24px; font-family: 'Nunito Sans', Arial, Verdana, Helvetica, sans-serif; color: #777;">
                                     © 2018
                                     <a href="http://wso2.com/" target="_blank" style="color: #777; text-decoration: none">WSO2</a>
                                     <br>
                                     787 Castro Street, Mountain View, CA 94041.
                                 </p>
                             </td>
                         </tr>
                         </table>
                     </td>
                     </tr>
                 </table>
         
         

      4. Email Footer:

         ---

         

         
         

         For detailed instructions, see here. 

Step 06: Enabling the feature in the management console

1. In the management console navigate to Main > Identity Providers > Resident > Account Management Policies > User Claim Update.
2. 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 changes.

    To enable this feature server-wide, add the configuration given below within the <server> tag in <IS_HOME>/repository/conf/Identity/identity.xml

   <UserClaimUpdate>
           <Claim uri = "http://wso2.org/claims/emailaddress">
               <VerificationOnUpdate>
                   <Enable>true</Enable>
                   <VerificationCode>
                       <ExpiryTime>1440</ExpiryTime>
                   </VerificationCode>
               </VerificationOnUpdate>
           </Claim>
    </UserClaimUpdate>

Try it Out

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

curl -v -k --user [username]:[password] -X PATCH -d '{"schemas":[],"Operations":[{"op":[operation],"value":{[attributeName]:[attribute value]}}]}' --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":{"emails":[{"primary":true,"value":"kim.jackson.new@gmail.com"}]}}]}' --header "Content-Type:application/json" https://localhost:9443/scim2/Users/1e624046-520c-4628-a245-091e04b03f21

{"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"],"EnterpriseUser":{"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"}

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. The new email address to be updated is represented in the SCIM response as an attribute of Enterprise User Extension. Given below is the extracted representation of it.

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