How to enable Email as Username in WSO2 Identity Server
Try self-registration flow with email as username feature enabled in WSO2 Identity Server.
Nowadays most people prefer to use their email as the username when logging into any application because it is easier to remember the email than many non-email usernames, and you won’t perhaps need to try typing several usernames until a unique one is accepted.
WSO2 Identity Server also allows user authentication with the email address. In this blog post, I will be elaborating on how to enable this email-as-username feature and will be trying out the whole flow using self registration with email as username feature enabled.
It is not possible to use the email username feature ‘by default’ in WSO2 IS !! Why?
As WSO2 IS supports multi-tenancy, we can create users either in the default super tenant which is ‘carbon.super’ or in any other tenant domain. Here, the ‘@’ mark is used to distinguish the tenant-aware username from the tenant-domain.
When you try to register a user in the default super tenant in WSO2 IS having default configurations, with an email username tom@zyx.com, Identity Server will consider zyx.com as the tenant domain that the user needs to be registered in. Hence it will first check whether there is a tenant domain called ‘zyx.com’ configured in the server. If so, the user will be registered to that particular tenant, not to the super tenant.
If in case such a tenant is not available, an error message is displayed saying that the tenant domain is invalid.
The reason for this behavior is WSO2 IS does not support the email username feature by default. Therefore, this feature has to be enabled if needed. So let’s get started!
Prerequisites
As I mentioned earlier, I will be demonstrating the user self-registration flow with email username feature enabled. Therefore, first of all you need to configure WSO2 Identity Server to enable self-registration. For detailed instructions on how to do this check here.
Step 1
Open the <IS_HOME>/repository/conf/deployment.toml file. Add the following configuration in order to enable the email username feature.
[tenant_mgt]
enable_email_domain= trueStep 2
Just the above configuration is not enough. You need to add a couple of user-store configurations as well. If you are having the default LDAP user-store, add the below configurations in the same deployment.toml file.
user_name_attribute = “mail”
user_name_search_filter = “(&(objectClass=person)(mail=?))”
username_java_script_regex = ‘^[a-zA-Z0–9.-]+@[a-zA-Z0–9.-]+\.[a-zA-Z]{2,4}$’
username_java_regex = ‘^[a-zA-Z0–9.-]+@[a-zA-Z0–9.-]+\.[a-zA-Z]{2,4}’If you have a different user-store, you may refer here for more information on configurations.
Step 3
Add the following configuration in deployment.toml file to include the email attribute in admin username.
[super_admin]
username = "admin@wso2.com"
password = "admin"Step 4
Enable cors to avoid any cross-origin errors when trying out the self-registration flow.
[cors]
allow_generic_http_requests = true
allow_any_origin = trueStep 5
Now start WSO2 IS from the bin directory of the product.
sh wso2server.shLogin to the management console with admin@wso2.com:admin credentials. Go to Claims → Lists and select http://wso2.org/claims
Click edit on the local claim username from the list of local claims and change the mapped attribute from uid to mail
Now we have configured all that is needed to try out the self-registration flow with email username. So let’s proceed to the interesting part!
Step 6
Go to My Account from https://localhost:9443/myaccount
Click on Create Account
Step 7
Let’s register tom with his email tom@zyx.com
Then proceed to self register and provide the required details.
Once you click on Register, a message box like below will appear, indicating successful setting up.
An email requesting to confirm the user account creation will be sent to the given email address. Click Confirm Account.
Step 8
Next, try logging in to My Account with Tom’s credentials upon successful account confirmation.
You will be redirected to the home page of Tom’s My Account.
We are done!!!!! We have now completed the self-registration flow with email as username feature enabled in WSO2 IS.
Also, you can clearly observe the user has been correctly registered in the super tenant ‘carbon.super’ instead of a tenant ‘zyx.com’ since we have already configured the email username feature!
If you need to register Tom in a tenant ‘abc.com’ , you need to give the username as tom@zyx.xom@abc.com
In summary,
If tom is in super tenant & email username enabled → tom@zyx.com
If tom is in super tenant & email username disabled → tom
If tom is in tenant ‘abc.com’ & email username enabled→ tom@zyx.com@abc.com
If tom is in tenant ‘abc.com’ & email username disabled→ tom@abc.com
Before wrapping up, one more important point to keep in mind!
If you have hosted the Authentication Endpoint and Recovery Endpoint of WSO2 IS in a different server, you need to add an additional configuration in the web.xmlfile located in the path <APP>/WEB-INF
<context-param>
<param-name>EnableEmailUserName</param-name>
<param-value>true</param-value>
</context-param>The reason for this additional configuration is since the app is now hosted on an external sever, the ‘enable email username’ feature configured in deployment.toml file is no longer recognized by the app. Hence the above configuration added in the web.xml file which resides inside the app will help resolve the issue!
For configuration information on hosting authentication/ recovery endpoints on a different server, check here.
Let’s meet in another blog! Until then, Happy reading! Happy learning!