Self-registration with email verification: WSO2 APIM 4.1.0

Saranki Magenthirarajah
9 min readJul 13, 2022
[Source: + Edited]

The applications and platforms allow us to create user accounts without assistance from an administrator or other authorized individuals. Have you wondered what would happen if someone else created an account in your name on an application without your approval? This account is an extension of yourself, as it can mimic you online and potentially create a number of security hazards.

There are mechanisms to protect yourself against this self-registration. A standard method is to send a confirmation of registration email to the user. Once the user confirms the account, it will be verified. This provides an extra layer of security, allowing users to know their identity is being used by the relevant application/platform.

Self-registration with an email verification: generic flow

The generic flow for the email verification for self-registered accounts in WSO2 APIM 4.1.0 is shown in Fig 1.

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

As seen in the above figure, once an individual creates an account for themselves, they are sent a confirmation email, which is only valid for a short time. Until the user confirms the email and verifies the account, the profile creator is unable to log in to the developer portal. Until the user verifies the account, the account will be locked.

Let’s get started with WSO2 APIM 4.1.0


In this blog, I will use the latest update wso2am- pack to explain how to enable self-registration with email verification. There are four parts to achieve this use case:

  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, let’s configure the deployment.toml file that resides in the <APIM-HOME>/repository/conf directory to send verification emails to the users and set the email server.

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

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

2. Enable email verification to send the verification mail to the user. Setting the lock_on_creation to “true”, will ensure the user account is locked until it is verified by the intended user.

enable_email_verification = true

3. Configure the email server where the email is sent to the relevant user(s).

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

Provide the sender’s email address, username, and password/app 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

This step is subjective with the email server you have picked. The process given below is for Gmail but may vary according to the email server. This allows your email account to provide access to third-party applications.

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

⭐️ NOTE:

Please note that to help keep your account secure, from May 30, 2022, ​​Google no longer supports the use of third-party apps or devices which ask you to sign in to your Google Account using only your username and password.

Important: This deadline does not apply to Google Workspace or Google Cloud Identity customers. The enforcement date for these customers will be announced on the Workspace blog at a later date.

Therefore, instead of using your email password, you can generate an app password and set that password under [] configuration.

Step 3: Setting up the Carbon Management Console

Here, we will configure the carbon management console in terms of account management policies and account locking mechanisms. This provides 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. This is shown in Fig 4.

Fig 4: Click on Resident

3. Under the User Onboarding section, click the Self Registration option as shown in Fig 5.

Fig 5: Click on the “Self Registration” option

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

i. Select the User self registration checkbox to enable self-registration.

ii. Select the Lock user account on creation checkbox to keep the user's self-registered account locked until the user replies to the account confirmation email.

iii. Select the Manage notifications sending internally checkbox to send confirmation emails. If the client application handles notifications, unselect it.

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). These steps are highlighted in Fig 6.

v. Enable Send sign up confirmation email checkbox to send a notification for self-sign-up confirmation.

Fig 6: Configure the self-registration section

v. Now, configure the set of attributes the user will consent to share.

  • Click on Click here under Manage Self-Sign-Up purposes, as shown in Fig 7.
Fig 7: Click on the “Click here” button
  • As shown in Fig 8, click Add New Purpose.
Fig 8: Add new purpose

Once the Add New Purpose screen appears, enter values for Purpose and Description. This is shown in Fig 9.

Fig 9: Add purpose and description
  • Now, under Select PII Categories, click Add PII Category. Afterward, select the following options as shown in Fig 10.
- — Mandatory
- — Mandatory
- — Not mandatory
Fig 10: Add PII category

vi. Next, click Finish. Afterward, the Consent Purposes screen will appear.

vii. Click Finish, and then the User Self Registration screen will appear.

viii. Click on Update.

Congratulations, the configurations are completed and we can test this flow!

Step 4: Testing the Flow

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

  1. As shown in Fig11, navigate to the developer portal via https://<hostname>:<port>/devportal → Sign-in → Create Account
Fig 11: Create Account

2. Provide a username and click on Proceed to Self Register, as shown in Fig 12.

Fig 12: Initiate self-registration flow

3. You will be directed to the following page as shown in Fig 13, where you must provide mandatory details. Once these are given, read the privacy policy, and tick the privacy policy acknowledgment checkbox → Register.

Fig 13: Create a new account by providing details

4. Now, you will get the following confirmation pop-up message box as shown in Fig 14.

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. This is shown in Fig 15.

Fig 15: Newly self-registered user profile

6. Now log in with the new username and password in the devportal as shown in Fig 16.

Fig 16: Unverified account

If the user doesn’t verify their account via email, they will be denied access to the developer portal. Therefore, it is shown as an unverified account when someone attempts to log in to the developer portal without verifying the account.

7. Log in 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 get the following pop-up message as shown in Fig 18.

Fig 18: Confirmation pop-up message

10. At the same time, you will receive a self-sign-up completed email to the same email address you have used for registration. This email will have the subject as WSO2 - Self Sign Up Completed.

Fig 19: Self-sign-up completed email

⭐️ NOTE:

In case you get the following error message box and the below-mentioned error trace in the carbon console after clicking on the confirmation email you have to follow the below-mentioned steps to resolve this issue. Please note that this is due to the missing selfSignUpSuccess template in <WSO2-APIM-Home>/repository/conf/email/email-admin-config.xml file.

Fig 20: Error message due to missing “selfSignUpSuccess” template
[2022-07-06 20:26:02,796] ERROR - ResendCodeApiServiceImpl Error occurred in the server while performing the task.
org.wso2.carbon.identity.event.handler.notification.exception.NotificationRuntimeException: Cannot find 'selfSignUpSuccess' template in the default 'en_US' locale for 'carbon.super' tenant
at org.wso2.carbon.identity.event.handler.notification.exception.NotificationRuntimeException.error( ~[org.wso2.carbon.identity.event.handler.notification_1.3.29.jar:?]
Caused by: Cannot find 'selfSignUpSuccess' template in the default 'en_US' locale for 'carbon.super' tenant
at ~[]
at org.wso2.carbon.identity.event.handler.notification.util.NotificationUtil.buildNotification( ~[org.wso2.carbon.identity.event.handler.notification_1.3.29.jar:?]
... 64 more

To resolve the above error please copy the following selfSignUpSuccess configuration in the <WSO2-APIM-Home>/repository/conf/email/email-admin-config.xml file. Add this between the <configurations></configurations> tags.

<configuration type="selfSignUpSuccess" display="SelfSignUpSuccess" locale="en_US" emailContentType="text/html">
<subject>WSO2 - Self Sign Up Completed</subject>
<body><![CDATA[<table align="center" cellpadding="0" cellspacing="0" border="0" width="100%"bgcolor="#f0f0f0">
<td style="padding: 30px 30px 20px 30px;">
<table cellpadding="0" cellspacing="0" border="0" width="100%" bgcolor="#ffffff" style="max-width: 650px; margin: auto;">
<td colspan="2" align="center" style="background-color: #333; padding: 40px;">
<a href="" target="_blank"><img src="" border="0" /></a>
<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;">
Self Sign Up Success
<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 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%;">
Please note that your account has been successfully activated. <br>
Account activation time: {{selfsignup-confirm-time}}
<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
<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;">
&copy; 2020
<a href="" target="_blank" style="color: #777; text-decoration: none">WSO2</a>
787 Castro Street, Mountain View, CA 94041.

11. If you have not received a confirmation email, click on the resend link on the login page of the developer portal as seen in Fig 21.

Fig 21: Re-send link for the confirmation email

12. Now let’s try to login into the developer portal again, you should now be successfully logged in as shown in Fig 22.

Fig 22: Successfully logged in as Bill

Congratulations, you now know how to self-register in WSO2 API Manager using email verification!


In this blog, we covered how to enable self-registration to create an account and validate it via a confirmation email, providing additional security against unauthorized individuals who may try to create an account on behalf of you.

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!