Monday, July 20, 2015

Create Users with ASK PASSWORD Feature in WSO2 Identity Server

With WSO2 Identity Server, it is possible to create user accounts by the Administrator without specifying a password at the time of account creation. Once the accounts are created, the account owners (users) can activate their accounts by giving passwords to the accounts by themselves. This feature is called as ‘Ask Password’ feature [1] in WSO2 Identity Server.

In this example I am using Identity Server 5.0.0 version with Service Pack 1 installed. I am demonstrating user creation in following three ways using Ask Password feature.

  1. Create user with Management Console
  2. Create user with SCIM
  3. Create user with RemoteUserStoreManagerService using SOAP UI

First steps is to set the Identity Management properties in the following file as below.



The descriptions for each property above is given below which are referred from [1].

This enables the identity listener.
This enables notifications to be sent via email when recovering an account or verifying user creation.
Using this configuration, you can specify a time limit for the notification to expire.
Enable the internal email sending module. If this is "false", the email sending data would be available to applications via a Web service. Then the application can send the email using its own email sender.
Enabling this ensures that temporary passwords are used when creating user accounts.
This enables verification of account creation. When self registration is done, the user would be verified by sending email (confirmation link) to user's email account.

Next step is to specify configuration for sending emails.
In <IS_HOME>/repository/conf/axis2/axis2.xml file, add the following. Here I have given the configuration for gmail. Username and password values you can change accordingly. If you are using some other email service provider, you can configure the host, port and related configuration appropriately.

<transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
   <parameter name="mail.smtp.from"></parameter>
   <parameter name="mail.smtp.user"></parameter>
   <parameter name="mail.smtp.password">password</parameter>
   <parameter name=""></parameter>
   <parameter name="mail.smtp.port">587</parameter>
   <parameter name="mail.smtp.starttls.enable">true</parameter>
   <parameter name="mail.smtp.auth">true</parameter>

Next step is to define the template of the email sent to users upon account creation.
In <IS_HOME>/repository/conf/email/email-admin-config.xml file, you can add following. Here I am using the InfoRecoverySample client application which helps account verification and password setting. The URL in the email template for account confirmation is based on the InfoRecoverySample app.

<configuration type="askPassword">
 <subject>WSO2 Identity Server - 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 window.
Best Regards,
WSO2 Identity Server Team

You can also define the email template using the Management Console of Identity Server as well by following Configure -> Email Templates link without modifying the email-admin-config.xml file manually.

Note :

When you are modifying the email-admin-config.xml file, to separate query parameters in the account confirmation link, you need to add &amp; instead of just & because if you just add an & it will break the XML. However if you define the email template from the management console UI, you can simply use &  for separating the query parameters in the link.

Next step is hosting the InfoRecoverySample application that helps account confirmation as a client app. The source code of the InfoRecoverySample is available in [2]. If you do not want to build the sample app from source, you can download a built .war file from [3].

Here I deploy the InfoRecoverySample.war file in tomcat. Copy the InfoRecoverySample.war file into <TOMCAT_HOME>/webapps directory.

Configure HTTPS in tomcat by adding following to the <TOMCAT_HOME>/conf/server.xml file. Here for <IS_HOME>, you need to give the path to your Identity Server.

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
              maxThreads="150" scheme="https" secure="true"
              clientAuth="false" sslProtocol="TLS"
              keystoreFile="<IS_HOME>/repository/resources/security/wso2carbon.jks" keystorePass="wso2carbon" />

After that restart tomcat and you can access the InfoRecoverySample app from following URL.

In this feature, the user passwords are modified by the account owners. To keep track of the password modification timestamp, we need to add the following claim.

Go to Configure -> Claim Management and click on the WSO2 claim dialect.

Add a new claim mapping.

Give the claim details as following. Here you can give a mapped attribute that the underlying userstore supports.

Display Name: Identity Password timestamp
Description: Identity Password timestamp
Claim Uri:
Mapped Attribute: facsimileTelephoneNumber

In above claim configuration, I have used  facsimileTelephoneNumber as the mapped attribute for passwordTimestamp claim. That is because the underlying LDAP that comes with Identity Server 5.0.0 does not have an attribute named passwordTimestamp in the LDAP schema. Therefore I am using an attribute which is already defined in the schema. If you are using a JDBC userstore, you can give a proper mapped attribute name because in JDBC userstores, there is no schema definition for user attributes unlike in LDAP.

After adding the claim, the details are shown as following.

Once a user resets the password, the userstore will keep track of the time of the password resetting from the mapped attribute of the claim. Shown below is a user in LDAP where the mapped attribute of the above claim has stored the last modified time of the password.

Now let’s add a user. Here I have logged into Identity Server as Administrator. Go to Configure -> Users and Roles -> Users.

Add a New User.

Select the ‘Ask password from user’ option and give the email address where the confirmation code of the account should be sent to.

Specify roles for the user appropriately.

Now the user is successfully created.

As shown below, the user will receive an email with a link to confirm the account and to set the password for the account. This link is redirecting to a page in the InfoRecoverySample application.

Once you click the link, the following page appears. You need to enter the captcha text for verifying you as a human.

Next step is to enter the password for the account created for the user.
Upon submitting, it will show as password has been changed successfully.

Now I can login to the management console of Identity Server with that user. (When creating the account I assigned the admin role to this user which contains the login permission)

The user can successfully login with the given password.

Instead of using the management console, the administrator can create the user with SCIM as well. Shown below are the SCIM request and the response when creating the user with SCIM. Here I do not give the password for the newly creating user. It is necessary to give the email address of the user in the request because then only the user will get an email to that email address for confirming the account and setting the password.

SCIM Request

curl -k --user admin:admin --data "{"schemas":[],"name":{"familyName":"edirisinghe","givenName":"dushan"},"userName":"edirisinghe", "emails":""}" --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Users

SCIM Response


Once the SCIM response is received, if you check the management console, you can see that the user is successfully created.

The email is also received where now the account can be confirmed and password can be set.

Similarly, the user can be created by calling the RemoteUserStoreManager service as well. You can open the following Admin Service from SOAP UI and call the addUser method for creating the user.

Following is the SOAP request I send. Here also I need to give the email address for the user account.

<soapenv:Envelope xmlns:soapenv="" xmlns:ser="" xmlns:xsd="">


        <!--Zero or more repetitions:-->

        <!--Zero or more repetitions:-->



Upon successful user creation, I do not get any response because this is a One-Way SOAP operation.

However I can check whether the user is successfully created or not by listing the users in the management console.

Upon user creating, The email is reveived for account confirmation and password setting.

For updating the password of an account created with ‘Ask Password’ feature, more information can be found on [4].


Tharindu Edirisinghe
Identity Server Team



  1. Dear Tharindu,

    I am followed your post same to same.

    But, when I create a new user by selecting "Ask a password" option I get this error. But the user is getting created in the default domain.

    "Could not add user PRIMARY/addUser. Error is: Error while doPostAddUser"

    I searched regarding the complete process in many sites but did not get any proper documentation regarding what each parameter in different files does so as to customize for my use.

    Please let me know where did I go wrong and also what all other things I need to configure. Also, sources required for understanding all parameters.

    Thanks in advance.

  2. Hi 'GSH G',

    From the description provided, it is difficult to find the exact issue in your case. Can you please send a mail to 'dev [at] wso2 [dot] org' email regarding this. Please include the log files as well so that I can look into this and guide you.


  3. Hi,
    First thanks for such helpful post..
    I am trying same scenario. I am able to get email into my inbox but when I clicks password reset link, in tomcat logs i found following error

    org.apache.axis2.AxisFault: Connection has been shutdown: PKIX path building failed: unable to find valid certification path to requested target

    I had exported certificate from lock icon from my browser and added to java cacerts and my server.xml and web.xml having entry for wso2carbon.jks

    Could you guide me through this problem?

  4. Hi Sarang,

    In your server.xml file of tomcat, can you try to add the path to wso2carbon.jks file which is in your Identity Server.

    Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
    maxThreads="150" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS"
    keystoreFile="/home/tharindu/Projects/wso2is-5.0.0/repository/resources/security/wso2carbon.jks" keystorePass="wso2carbon"

    An example is above where you can change the file path accordingly. After adding above, restart tomcat and try out the same. If you still get the error I can look more into it.