This documentation is for WSO2 Identity Server 5.7.0 . View documentation for the latest release.

All docs This doc
||
Skip to end of metadata
Go to start of metadata

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. 

To use this feature, apply the 6084 WUM update to WSO2 IS 5.7.0 using the WSO2 Update Manager (WUM).  To deploy a WUM update into production, you need to have a paid subscription. For more information on updating WSO2 Identity Server using WUM, see Getting Started with WUM  in the WSO2 Administration Guide.


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

  • This feature can be invoked via a PUT/PATCH request to SCIM 2.0 /Users endpoint or /Me endpoint.
  • The verification on update capability will only be supported for the http://wso2.org/claims/emailaddress claim.
  • An email verification will not be triggered if the email address to be updated is the same as the previously verified email address of the user.
  • This feature will only manage the verification flow internally. External verification capability is not offered.
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
 If it is required to have the above email template available server-wide, instead of adding the template via the management console, follow the instructions here

Open the email-admin-config.xml file in the <IS_HOME> /repository/conf/email directory.

  1. Add the configuration template as shown below.

    <configuration type="verifyEmailOnUpdate" display="VerifyEmailOnUpdate" locale="en_US" emailContentType="text/html">
            <subject>WSO2 - Email Confirmation</subject>
            <body><![CDATA[<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>]]></body>
            <footer>---</footer>
        </configuration>
  2. Save the file and restart the server.

The changes done to the email-admin-config.xml file will not appear in the email templates shown in the management console for existing tenants. For any new tenants, the template will be available.

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.

Request
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]
Sample CURL
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":"[email protected]"}]}}]}' --header "Content-Type:application/json" https://localhost:9443/scim2/Users/1e624046-520c-4628-a245-091e04b03f21
Sample Response
{"emails":["[email protected]"],"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":"[email protected]"}]},"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":"[email protected]"}]}

Related Topics

Please refer https://docs.wso2.com/display/IS570/apidocs/SCIM2-endpoints/ for information on using SCIM 2.0 REST APIs.



  • No labels