Self-registration with email verification: WSO2 APIM 4.1.0
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.
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-4.1.0.15 pack to explain how to enable self-registration with email verification. There are four parts to achieve this use case:
- Configuring the directory level config files
- Configuring the Gmail account to receive emails for account verification
- Setting up the carbon management console
- 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.
- Configure the below event listeners to observe events and trigger the send email event.
[event.default_listener.identity_mgt]
priority= "50"
enable = false
[event.default_listener.governance_identity_mgt]
priority= "95"
enable = true
[event.default_listener.governance_identity_store]
priority= "97"
enable = true2. 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.
[identity_mgt.user_onboarding]
enable_email_verification = true
lock_on_creation=true3. Configure the email server where the email is sent to the relevant user(s).
[output_adapter.email]
from_address= "sampleUser@gmail.com"
username= "sampleUser"
password= "<App password>"
hostname= "smtp.gmail.com"
port= 587
enable_start_tls= true
enable_authentication= trueProvide 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 smtp.gmail.com 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.
- Navigate to https://myaccount.google.com/security.
- Click Signing in to Google on the left menu and make sure that the 2-step Verification is disabled or off.
3. Allow less secured application access to your email account.
⭐️ 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 [output_adapter.email] 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.
3. Under the User Onboarding section, click the Self Registration option as shown in Fig 5.
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.
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.
- As shown in Fig 8, click Add New Purpose.
Once the Add New Purpose screen appears, enter values for Purpose and Description. This is shown in Fig 9.
- Now, under Select PII Categories, click Add PII Category. Afterward, select the following options as shown in Fig 10.
- http://wso2.org/claims/givenname — Mandatory
- http://wso2.org/claims/emailaddress — Mandatory
- http://wso2.org/claims/mobile — Not mandatoryvi. 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.
- As shown in Fig11, navigate to the developer portal via https://<hostname>:<port>/devportal → Sign-in → Create Account
2. Provide a username and click on Proceed to Self Register, as shown in Fig 12.
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.
4. Now, you will get the following confirmation pop-up message box as shown in Fig 14.
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.
6. Now log in with the new username and password in the devportal as shown in Fig 16.
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.
9. After the successful confirmation, you will get the following pop-up message as shown in Fig 18.
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.
⭐️ 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.
[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: org.wso2.carbon.email.mgt.exceptions.I18nEmailMgtInternalException: 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(NotificationRuntimeException.java:38) ~[org.wso2.carbon.identity.event.handler.notification_1.3.29.jar:?]
.
.
.
Caused by: org.wso2.carbon.email.mgt.exceptions.I18nEmailMgtInternalException: Cannot find 'selfSignUpSuccess' template in the default 'en_US' locale for 'carbon.super' tenant
at org.wso2.carbon.email.mgt.EmailTemplateManagerImpl.getEmailTemplate(EmailTemplateManagerImpl.java:255) ~[org.wso2.carbon.email.mgt_1.3.29.jar:?]
at org.wso2.carbon.identity.event.handler.notification.util.NotificationUtil.buildNotification(NotificationUtil.java:314) ~[org.wso2.carbon.identity.event.handler.notification_1.3.29.jar:?]
... 64 moreTo 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">
<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;">
Self Sign Up Success
</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%;">
Please note that your account has been successfully activated. <br>
Account activation time: {{selfsignup-confirm-time}}
</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;">
© 2020
<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>
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.
12. Now let’s try to login into the developer portal again, you should now be successfully logged in as shown in Fig 22.
Congratulations, you now know how to self-register in WSO2 API Manager using email verification!
Summary!
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!
