Self-registration with email verification: WSO2 APIM 3.X.X

Saranki Magenthirarajah
7 min readAug 9, 2020

Many of the applications or e-platforms we use today allow us to create user accounts by ourselves without the interference of an administrator or any other authorized personality. What if someone else creates an account on behalf of you in any of the applications without your concern? That will lead an unauthorized personality to mimic yourself on that platform which will create security hazards for you.

There are various mechanisms to protect this self-registration process. One such method is to send a registration confirmation email to the user and when the user confirms the account, it becomes a verified account. This provides an extra layer of security and allows the intended users to know that their identity is being used by the relevant application or platform.

Self-registration with an email verification: generic flow

The generic flow of the email verification for self-registered accounts in WSO2 APIM is as follows.

Fig 1: Self-registration with email verification in WSO2 APIM

In Fig 1, the successful path of self-registration with email verification has been shown. Once the self-registers and creates an account for themselves they will be sent a confirmation email. This confirmation email has an expiry time. Unless the user confirms the email and verifies the account the user won’t be able to login to the dev portal and until the user verifies the account, the account will be in a locked state.

Let’s get started with WSO2 APIM


In this blog, I’ll be using the latest wum updated wso2am-3.1.0 pack to demonstrate how we can enable self-registration with email verification. There are 4 main phases in order to achieve this use-case and those are as follows.

  1. Configuring the directory level config files
  2. Configuring the Gmail account to receive emails for account verification
  3. Setting up the carbon management console
  4. Testing the flow

Step 1: Configuring the directory level config files

In this step, we’ll configure the deployment.toml file that resides in the <APIM-HOME>/repository/conf directory in order to send the verification emails to the users and set the email server.

In the deployment.toml file, add the following configurations.

  1. Configure the below even listeners in order to observe the events and trigger the send email event.
priority= "50"
enable = false
priority= "95"
enable = true
priority= "97"
enable = true

2. Enable email verification in order to send the verification mail to the user. By setting the lock_on_creation to true will ensure that the user account will be in a locked state until the account is verified by the intended user.

enable_email_verification = true

3. Configure the email server from which the email will be sent to all the relevant users.

from_address= ""
username= "sampleUser"
password= "password"
hostname= ""
port= 587
enable_start_tls= true
enable_authentication= true

Provide the sender’s email address, username, and password in the above configuration. Since I’m using a Gmail account for the sender’s email ID I have used as the hostname.

4. Restart the APIM server.

Step 2: Configuring the Gmail account to receive emails for account verification

This step is subjective with the email server you have picked. Since I have picked Gmail I’ll walk you through this step. This step is to allow your email account to provide access to third-party applications.

  1. Navigate to
  2. Click Signing in to Google on the left menu and make sure that the 2-step Verification is disabled or off.
Fig 2: Turn off 2-step verification in your Gmail account

3. Allow less secured application access to your email account.

Fig 3: Allow less secured application access

Step 3: Setting up the carbon management console

In this section, we will configure the carbon management console in terms of account management policies and account locking mechanisms to provide an extra layer of security in the self-registration flow.

1.Sign-in to the APIM carbon management console via https://<hostname>:<port>/carbon as an admin user.

2. In the Main menu of the carbon management console, click Identity → Identity Providers → Resident.

Fig 4: Click on Resident

3. Under the Account Management Policies section, click the User Self Registration option.

Fig 5: Click on User self-registration option

4. Make the following changes in the User Self Registration section.

i. Select the Enable Self User Registration checkbox to enable self-registration.

ii. Select the Enable Account Lock On Creation Enabled checkbox to keep the user self-registered account be locked until the user responds to the account confirmation email.

iii. To enables sending confirmation emails to the user, select the Enable Notification Internally Management checkbox. If the client application handles notifications, unselect.

iv. You may enter the account confirmation email validity period (in minutes) in the User self registration verification link expiry time text box. By default, it is set as 1440 minutes(24 hours).

Fig 6: Configure the user self-registration section

v. Configure the set of attributes the user will consent to share.

  • Click on Click here under Manage Self-Sign-Up purposes.
Fig 7: Click on “Click here” button
  • Click Add New Purpose.
Fig 8: Add new purpose
  • The Add New Purpose screen appears.
  • Enter values for Purpose and Description.
Fig 9: Add purpose and description
  • Under Select PII Categories, click Add PII Category.
  • Select the following options.
- — Mandatory
- — Mandatory
- — Not mandatory
Fig 10: Add PII category

vi. Click Finish. Note that the Consent Purposes screen appears.

vii. Click Finish. Note that the User Self Registration screen appears.

viii. Click Update.

Now the configurations are completed and we are good for testing this flow!

Step 4: Testing the flow

Now let’s self register a user and test the flow.

  1. Navigate to devportal via https://<hostname>:<port>/devportal → Sign-in → Create Account
Fig 11: Create account

2. Provide a username and click on Proceed to Self Register.

Fig 12: Initiate self-registration flow

3. You will be directed to the following page where the mandatory details need to be provided. Once the details are provided read the privacy policy and tick the privacy policy acknowledgment checkbox → Register

Fir 13: Create a new account by providing details

4. You will get the following confirmation pop-up message box.

Fig 14: Account created confirmation box

5. To confirm the newly created account visit the carbon management console and check the user list in Identity → Users and Roles → List → Users → User profile of the newly created user → default.

Fig 15: Newly self-registered user profile

6. Now try to login with the new user’s username and password in the devportal.

Fig 16: Unverified account

Since the configurations are made not to allow the user without verifying the account via the email when trying to login to the devportal it is prompted as an unverified account.

7. Login to your email and open the email with the subject “WSO2 — Account Confirmation”.

8. You will receive a similar email as below and click on the Confirm Account button or the link provided in the email.

Fig 17: Confirmation email

9. After the successful confirmation, you will be displayed with the following pop-up message.

Fig 18: Confirmation pop-up message

10. Suppose if you have not received a confirmation email, then click on the Re-send link in the login page of devportal.

Fig 19: Re-send link for the confirmation email

11. Now let’s try to login to the devportal again.

Fig 20: Successfully logged in as Bill

You will be able to enter into the devportal now. Yes, we were able to successfully do self-registration in APIM with email verification!


In this blog, we were able to do self-registration to create an account and validate it via a confirmation email that provides an extra layer of security for any unintended parties to create an account on behalf of you and to protect your account.

Hope this was a good read and will be a useful reference for those who wanted to try out the self-registration flow with email verification.

Happy Learning!

Stay safe!