How to enable Email Username with WSO2 API Manager?

WSO2 products including WSO2 API Manager, allows you to authenticate users through their Email address.

Now let’s see how this can be achieved through WSO2 API Manager.

You can download the latest version of WSO2 API Manager from here and get going straight away.

I will be using API Manager version 2.0.0 in this guide. The steps will be the same across all versions. So you can try it out.

Step 1

• Download the product from the link above.
• Open <PRODUCT_HOME>/repository/conf/carbon.xml and uncomment the following configuration.

<EnableEmailUserName>true</EnableEmailUserName>

Step 2

• Open <PRODUCT_HOME>/repository/conf/claim-config.xml and configure the AttributeID property of ClaimURI http://wso2.org/claims/username to mail.

claim-config.xml

Step 3

• Open <PRODUCT_HOME>/repository/conf/identity/identity-mgt.properties and set the following property to true as shown.

UserInfoRecovery.UseHashedUserNames=true

Step 4

• Open <PRODUCT_HOME>/repository/conf/user-mgt.xml and add the following property under the relevant User Store Manager tag.

<Property name=”UsernameWithEmailJavaScriptRegEx”>^[\S]{3,30}$</Property>

• Check the image below.

user-mgt.xml

• This property determines the username validation that will be enforced when the EnableEmailUserName option is enabled.

NOTE : The user-mgt.xml file above is configured when you use the Primary User Store. But if you are using a Secondary User Store, the above property should be added to the relevant user store configuration file found in <PRODUCT_HOME>/repository/deployment/server/userstores. You can check my article on Configuring a Secondary User Store with WSO2 API Manager.

Step 5

In addition to the above configuration in the user store, you should configure the following set of parameters as well, in the same user store configuration. This depends on the type of the user store you are connected to. But in the default scenario where you use the Primary user store, only the following 2 properties should be changed.

<Property name=”UsernameJavaScriptRegEx”>^[a-zA-Z0–9._-]+@[a-zA-Z0–9.-]+\.[a-zA-Z]{2,4}$</Property>

<Property name=”UsernameJavaRegEx”>^[a-zA-Z0–9._-]+@[a-zA-Z0–9.-]+\.[a-zA-Z]{2,4}$</Property>

• Check step 5 of this if you use a different user store type(LDAP/Active Directory etc.).

Step 6

• Change the Admin username to the email attribute of the admin user in <PRODUCT_HOME>/repository/conf/user-mgt.xml as follows.

<AdminUser>
   <UserName>admin@gmail.com</UserName>
   <Password>admin</Password>
</AdminUser> 

Step 7

• Open <PRODUCT_HOME>/repository/conf/jndi.properties and change the admin username to admin!gmail.com!carbon.super as shown in the following image. ‘!’ character is used because ‘@’ is a reserved character in the WSO2 messaging component.

jndi.properties

Step 8

Now start WSO2 API Manager server from the bin directory of the product.

./wso2server.sh

Now you can login(with admin@gmail.com:admin credentials) to any application (Publisher, Store, Admin Portal, Management Console) of API Manager using the email address of the user.

Cheers!