Tuesday, September 9, 2014

Email and normal user name configuration with WSO2 IS

In this blog post I'm going to discuss how to configure WSO2 Identity Server to support email based user names for one user store and also normal String type user names to another user store.

This is supported in WSO2 IS 4.6 and 5.0 versions.

First you need to configure the Identity Server to support email based user names. You can refer this [1] blog post for the this configuration steps. You can configure the primary user store to have email user name as described in the blog.

Then you can add a secondary user store from Configure -> User Store Management configuration. Click on add secondary user store and give the necessary details for the user store which support both email and normal user name types. We will call this user store domain as "TEST".
When you configure this and strait away if you try to add an user with only String type user name which has alphanumeric chars it will complain that user name is not confirming to policy as shown below.

So in order to have both type of user names for TEST domain we need to add the following configuration for the user store. 
<Property name="UsernameWithEmailJavaScriptRegEx">^[\S]{3,30}$</Property>
This property defines the user name pattern to be used when email user name is enabled as discussed in the [1] blog.

However you cannot add this property from the User Store Manager configuration UI. Hence you need to edit the file manually. Usually the secondary user store properties for super tenant is placed in <IS_HOME>/repository/deployment/server/userstores/ directory with the domain name as here it will be TEST.xml

After adding the property you need to restart the server. Then try to add an user to TEST domain with normal String type user name (testuser1) from Configure -> Users and Roles -> Users and by clicking Add New User. Then try with email user name (testuser2@email.com).

With the configuration you will be able to add both type of users to this user store.

This is supported in super tenant mode only. So in multi-tenant deployment its recommend to have only one type of user name configuration.

[1] - http://sureshatt.blogspot.de/2013/07/attribute-email-based-user.html

Sunday, December 15, 2013

WSO2 Identity Server – User creation with ask password from user

This post is about the configurations and usage of the WSO2 Identity Server user account creation process by admin which allows the user to enter the password. This feature is included in the WSO2 Identity Server 4.5.0 and on-wards.


When the administrator needs to create user account from the Identity Server management console it gives options to either enter the password by administrator directly or allow user to specify the password. If administrator needs to give the password to user it might become burden to admin since he/she needs to give it to the particular user. During this period admin may loose it before giving it to user. To avoid such situations admin can use the ask password from user option when creating users with Identity Server. 

The user creation page can be accessed by browsing Configure → Users and Roles → Users and clicking on Add new user as shown in the Figure 1.

Figure 1 : Add new user

Figure 2 below shows the management console ui with the ask password from user option selected.

Figure 2 : ask password from user

You need to provide the user's user name and email address. The Identity Server send an email to this address by providing the user with a redirect url in which the user will be directed to provide the password for his/her newly created account by admin.

The supporting web service is hosted in the following WSDL by the Identity Server.


Following operations have been used from the above api.

You can find the sample implementation of this in the web application here.

Now we will see the configurations needed for this functionality.

Configuration for Identity Server

Edit the identity-mgt.properties file with the following located in your Identity Server installation under <is_server>/repository/conf/security/ directory.


Since notification sending is internally managed we need to uncomment the email transportSender in axis2.xml file located under <is_server>/repository/conf/axis2. Search for <transportSender name="mailto" and provide your email details as required.

Make sure the following email template is defined in the email-admin-config.xml under <is_sever>/repository/conf/email directory.

<configuration type="askPassword">
<subject>WSO2 Carbon - Password
Change for New Account</subject>
Hi {first-name}
Please change your password for the
newly created account : {user-name}.
Please click the link below to create
the password.
If clicking the link doesn't seem to
work, you can copy and paste the
link into your browser's address
Best Regards,
WSO2 Carbon Team

Here the <targetEpr> holds the redirect URL which handles the password flow in the sample web application. Also the contents with curly brases {} will be replaced by correct values when generating the email.

Then you need to restart the Identity Server to take effect of the configuration changes.

You need to define the following claim and map it with a valid attribute of your underlying user store. Go to Configure → Claim Management → and select "http://wso2.org/claims"  → click on Add New Claim Mapping. Here I'm going to map it with facsimileTelephoneNumber with my ldap user store attribute. Following are the values that I have given. Figure 3 shows the UI for this operation.

Display Name: Identity Password timestamp
Description: Identity Password timestamp
Claim Uri: http://wso2.org/claims/identity/passwordTimestamp
Mapped Attribute: facsimileTelephoneNumber

Figure 3: adding a claim

Configuration for sample web application

Once you have downloaded the sample from here you can directly deploy the InfoRecoverySample.war under target directory or you can build it from source.

If you have building from source you need to give the following context configurations in web.xml.
Give your hosted Identity Server urls as below.

Give the trust store path to the Server

Give your admin username and password of the Identity Server.


Also you need to enable the SSL configuration of your web application container. You can give the same key store file as below for tomcat under <tomcat>/conf/server.xml. After this change restart tomcat.
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="150" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS"
               keystoreFile="/home/chamath/apps/wso2is-4.5.0-7.18.2-SNAPSHOT/repository/resources/security/wso2carbon.jks" keystorePass="wso2carbon" />

If you are directly deploying the InfoRecoverySample.war file first you need to deploy and stop and do the above configurations and start again.

Now you are ready to test the functionality.

As shown in the figure 1 go the add new user and select ask password from user option. You need to give the user name and the user's email. Then assign the user to a role which has login permission. And then finish the flow which you will receive a successful user creation message.
User will be receive a email message with password change for new account with confirmation link. As instructed in the email click on the link. You will be directed to a page to enter user name and captcha as shown in Figure 4.

Figure 4. user name and captcha page

Enter the details and submit which then you will be directed a page to enter the new password.
Now you can test the new password in effect by login into the Identity Server management console by giving the user name and new password.


Sample source code

Monday, December 2, 2013

Password Recovery with WSO2 Identity Server

This blog shows the password recovery feature usage in the Wso2 Identity Server 4.5.0. The Identity Server provides email based password recovery as well as secret question based password recovery for the registered users. Currently password recovery only supports for super tenant users. However in the future versions it will support for tenant users as well.

With the Identity Server as a middle ware you can configure it to recover user password securely after registering users with the Identity Server User store. The Identity Server exposes secure APIs which your application can invoke to recover user's password. You can view the available APIs by accessing the following WSDL.


First I will explain how to recover the password using email notifications.

Recover password with email notification

The API methods available through the above WSDL shown below for email notification based password recovery.
1. getCaptcha()
2. verifyUser()
3. sendRecoveryNotification()
4. getCaptcha()
5. verifyConfirmationCode()
6. updatePassword()

The flow of password recovery by email notification is as follows using the above WSDL.
First you need to get the captcha using getCaptcha(). The captcha details returned should be passed along with the visible captcha answer and user name to verifyUser() which is for user verification. Upon successful verification it will return a code. Then you need to call the sendRecoveryNotification() to send the notification along with the code to the user. Then the generated email with the password reset link will be emailed to the user. Upon user clicking the reset link the user should be directed to a another captcha page for verification by calling getCaptcha(). Then it needs to verify the confirmation code along with the captcha answer by calling verifyConfirmationCode(). This will generate another code which needs be passed to the updatePassword() to update the password.
In order to recover the password using email notification following configuration needs to be done.
You need to configure the email sender and here we use the axis transport Sender. Following configureation needs to be done in the axis2.xml file located in the Identity Server installation under <is_home>/repository/conf/axis2 directory. Uncomment the following and give your email details.


Then you need to configure the identity management module properties in identity-mgt.properties file under /repository/conf/security directory. You can give the following configuration for this.

Notification.Expire.Time=3 # expire the recovery after 3 minutes. 

You also can configure the email format and confirmation code urls in the email-admin-config.xml under <is_home>/repository/conf/email directory. For password recovery sending email you need to have a email template type as “passwordReset”. Following shows a sample configuration.

 WSO2 Carbon - Password Reset
 Hi {first-name}

 We received a request to change the password on the {user-name} account
 associated with this e-mail address. If you made this request, please
 click the link below to securely change your password:

 If clicking the link doesn't seem to work, you can copy and paste the
 link into your browser's address window.

 If you did not request to have your {user-name} password reset, simply
 disregard this email and no changes to your account will be made.
Best Regards, WSO2 Carbon Team http://www.wso2.com
In the email template shown above the <targetEpr> tag defines the call back url which handles the users confirmation request. The contents of the tag is used to create the password-reset-link by appending a confirmation code.
You can find the sample from here. You can follow the “I forgot my password” link to see the demo.

Recover password with secret questions

The Identity Server provides another way of recovering the password using secret questions. User is able to select two security questions on the two sets of questions and provide answers using the Account Recovery option under My Identity in the management console as shown below.

Figure 1. Account Recovery menu in management console.

You need to do the same configuration as recover with email notification except the email related configurations.
Also make sure that you have mapped correct attributes for the challenge question attributes under Claim management for http://wso2.org/claims/challengeQuestion1 and http://wso2.org/claims/challengeQuestion2 claim URIs.

There are 6 methods defined through the API as follows.

1. getCaptcha()
2. verifyUser()
3. getUserChallengeQuestionIds()
4. getUserChallengeQuestion()
5. verifyUserChallengeAnswer()
6. updatePassword()

Following is how the password recover flow should be used for two challenge questions.

Get the captcha using getCaptcha() and provide the captcha details with user name to verfiyUser(). You will be getting a code with the call. After the verification you can get the challenge question ids using the getUserChallengeQuestionIds() which returns the defined claim URIs along with a code. You need to have this to retrieve the question for the user with the getUserChallengeQuestion(). In your web application you can define two steps to answer the challenge questions to maximize security. The verifyUserChallengeAnswer() is used to verify a particular answer for a question. If both answers are correct you can call the updatePassword() to change the user password.

You can find a sample web app is implemented this feature from here.