Azure AD B2C: Custom email verification code

This sample solution demonstrates how to use custom email verification. The custom email verification solution allows you to send your own custom email verification during sign-up or password reset user journey. The solution required using Azure AD B2C custom policy and a REST API endpoint that sends the email verification and validates the verification code.

The key concept of custom email verification: During sign-up or password reset and change email custom policies, a user provides the sign-in email address. User clicks on continue, Azure AD B2C calls a REST API endpoint that generates a verification code. The verification code is sent to the user's email and return back to Azure AD B2C. On the next page (sign-up, password reset and change email) user is requested to provide the verification code (sent by email) along with the rest of the information, such as sign-up user profile, password reset the new password. When users click on the continue button, Azure AD B2C makes another call to the REST API, sending both the verification code generated in the previous step and the verification code provided by the end user. The REST API compares the verifications codes and lets the user update, or create the account

User flow

Custom email verification code deals with following scenarios:

Sign-up

1. LocalAccountSignUpWithLogonEmail-FirstStep self-asserted technical profile
   1. Disables the default Azure AD B2C email verification, using the EnforceEmailVerification metadata
   2. Collects the email address
   3. Copies the email address to the CopyEmailAsReadOnly claim type
   4. Calls the REST-API-SendVerificationEmail validation technical profile that generates the verification code, sends the email
   5. Returns the verification code as output claim
2. On the next orchestration step, B2C calls the LocalAccountSignUpWithLogonEmail-SecondPage technical profile. This Self asserted sign-up page. It's based on the LocalAccountSignUpWithLogonEmail, while removing the email claim and changing the validation technical profiles
   1. Presents the email in read only mode
   2. Asks the user to provide the verification code (sent by email), the passwords, and user profile
   3. When user clicks on continue, B2C runs the REST-API-verifyCode validation technical profile that compares the verification code provided by the user and the one generated by the REST API in the previous step.
   4. The second validation technical profile AAD-UserWriteUsingLogonEmail creates the account

Password reset

1. LocalAccountDiscoveryUsingEmailAddress self-asserted technical profile
   1. Disables the default Azure AD B2C email verification, using the EnforceEmailVerification metadata
   2. Collects the email address
   3. Calls the REST-API-SendVerificationEmail validation technical profile that generates the verification code, and sends the email
   4. Returns the verification code as output claim
2. On the next orchestration step B2C calls the LocalAccountWritePasswordUsingObjectId-SecondStep technical profile. This Self asserted password reset page. It's based on the LocalAccountWritePasswordUsingObjectId, while adding the verification code functionality
   1. Asks the user to provide the verification code (sent by email) and the new password
   2. When user clicks on continue, B2C runs the REST-API-verifyCode validation technical profile that compares the verification code provided by the user and the one generated by the REST API in the previous step.
   3. The second validation technical profile AAD-UserWriteUsingLogonEmail creates the account

Change sign-in email address

1. Ask the user to sign-in with the local account email address
2. Read the user profile from Azure AD
3. LocalAccountEmailVerification-FirstStep self-asserted technical profile
   1. Disables the default Azure AD B2C email verification, using the EnforceEmailVerification metadata
   2. Collects the email address
   3. Calls the REST-API-SendVerificationEmail validation technical profile that generates the verification code, and sends the email
   4. Returns the verification code as output claim
4. On the next orchestration step B2C calls the SelfAsserted-EmailVerification self-asserted technical profile
   1. Asks the user to provide the verification code (sent by email)
   2. When user clicks on continue, B2C runs the REST-API-verifyCode validation technical profile that compares the verification code provided by the user and the one generated by the REST API in the previous step.
   3. The second validation technical profile AAD-UserWriteEmailUsingObjectId store the new email address to the account

Run the solution

To run the visual studio solution, you need:

1. Deploy this web app to Azure App Services. For more information, see Create and publish the web app
2. Set the application settings. You can set the app settings directly from appsettings.jsonn file. Or use the better solution, from Azure portal. For more information, see: Configure web apps in Azure App Service

Important notes:

Secure the communication between Azure AD B2C to your Rest API. For more information, see: Secure your RESTful service by using client certificates OR Secure your RESTful services by using HTTP basic authentication

Solution artifacts

This sample policy is based on LocalAccounts starter pack.

• All changes are marked with Demo: comment inside the policy XML files.
• Make the necessary changes in the Action required comments

Visual studio solution

• IdentityController The custom policy calls this REST API
• appsettings.json application settings
• Models folder - this folder contains the necessary object-mapping classes

To test the sample solution, open the AADB2C.Invite.sln Visual Studio solution in Visual Studio. In the AADB2C.Invite project, open the appsettings.json. Replace the app settings with your own values:

• SMTPServer: Your SMTP server
• SMTPPort: Your SMTP server port number
• SMTPUsername: SMTP user name, if necessary
• SMTPPassword: SMTP password, if necessary
• SMTPUseSSL: SMTP use SSL, true of false
• SMTPFromAddress: Send from email address

For example:

  "AppSettings": {
    "SMTPServer": "smtp.sendgrid.net",
    "SMTPPort": 587,
    "SMTPUsername": "[email protected]",
    "SMTPPassword": "1234",
    "SMTPUseSSL": true,
    "SMTPFromAddress": "[email protected]"
    }

Use this solution for sign-in with username

If your policy is username based, make the nassacery changes:

• Sing-Up - Make your store the email address to the strongAuthenticationEmailAddress instead of the signInNames.emailAddress
• Password reset - After the validation, you should look up the account using the username (instead of the email address), and compare the return strongAuthenticationEmailAddress to the one provided and validated by the user.
• Chage email address - When you read and write, use the strongAuthenticationEmailAddress instead of the signInNames.emailAddress

Disclaimer

The sample is developed and managed by the open-source community in GitHub. The application is not part of Azure AD B2C product and it's not supported under any Microsoft standard support program or service. The sample (Azure AD B2C policy and any companion code) is provided AS IS without warranty of any kind.

Note: This sample policy is based on logon with username policy. All changes are marked with Demo: comment inside the policy XML files. Make the nessacery changes in the Demo action required sections.