Friday, October 30, 2015

Enabling User Password Recovery for WSO2 API Manager with WSO2 Identity Server - Part 1

Any of the WSO2 API Manager versions released so far does not have the capability of user password recovery. If the API Manager users completely forget their password, they do not have a way to recover it. However WSO2 Identity Server have this feature implemented as a service called UserInformationRecoveryService. This blog post will explain how to use this password recovery feature of WSO2 IS in WSO2 API Manager. I will demonstrate the service calls through soap UI here.

User Information Recovery API

WSO2 Identity Server has given an API to recover forgotten/lost password in several ways. Those are as follows.

1. Recover with notification : password recovery by using email based notifications. An email is sent to the user's email account through axis2 mail transport.
2. Recover with Secret Questions : By obtaining answers for some challenge questions by invoking UserIdentityManagementAdminService.
3. User Account Recovery : helps to recover username of the account if the user has forgotten it.

All the above recovery processes are secured with captcha verification. In this blog post I will describe how the first option can be enabled in WSO2 API Manager 1.8.0.

Installing WSO2 Identity Server Feature in API Manager

First of all if we want to have the password recovery capability in WSO2 API Manager you have to install the Account Recovery and Credential Management Feature of WSO2 Identity Server in WSO2 API Manager. Please follow the below steps to install the feature.

Steps : 
1. Start the Server and log in to the Management Console of WSO2 API Manager

For more information on downloading WSO2 API Manager, installing it and about installation prerequisites please refer WSO2 API Manager Documentation.

2. Navigate to the Configuration menu and go to Features --> Repository Management and add repository with a relevant name.  e.g. credential-mgt

3. Give the following as the repository URL This is the related P2 repository for the feature.

4. Click on Find the features and select Account Recovery and Credential Management 4.2.2 and click install.

5. Accept Licence Agreement and finish installing the feature.

Configuring WSO2 API Manager for User Information Recovery

After installing the feature follow the documentation on Recover with Notification in WSO2 Identity Server and configure WSO2 API Manager for User Information Recovery. Consider <IS_HOME> mentioned in the documentation as <APIM_HOME> which is the installation directory of product API Manager.

Now WSO2 API Manager has the capability of calling the UserInformationRecoveryService.

Getting the WSDL of UserInformationRecoveryService

Steps : 
1. Stop the Server.
2. Go to <APIM_HOME>/repositiory/conf/carbon.xml and make <HideAdminServiceWSDLs> property false as follows.

2. Start the Server and access the WSDL of UserInformationRecoveryService through following link.

Now what you have to do is calling the relevant service methods in order. Follow the service methods mentioned in documentation and call the service methods.

To use this feature as an existing feature in WSO2 API Manager either you have to implement a jaggery module in API Manager Store or you have to create a separate web app to be redirected from within API Manager Store. however you can check how this is working using Soap UI.

Please go through my next blog post to see how you can call the UserInformationRecoveryService through Soap UI and change the password of a user.


  1. 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?

  2. Hi,

    I am using WSO2 API Manager version 2.
    I tried to install "Account Recovery and Credential Management" but it fails as it conflicts with the Core Identity version 5.2.0 .

    Software being installed: Account Recovery and Credential Management Feature 4.2.2 ( 4.2.2) Software currently installed: Identity Core Feature 5.2.0 ( 5.2.0)

    Can you please let me know how can I install this feature in my WSO2 version 2?

    Thanks & Regards

    1. Since you are using API Manager 2.0.0 and Identity Server 5.2.0, the P2 repository that you should use is

      Can you check that you have used the correct repository URL to install the feature ?

    2. This comment has been removed by the author.

  3. Hi,

    Thank you very much for your reply.

    I tried to install the feature using new repository. But it fails to install it.
    I am going to download the repository locally and then going to try it again.

    I will let you know how it goes. Thanks for your help!

    1. Hi Sandip,
      In API Manager 2.0.0 there exist a known issue when installing this Account Recovery and Credential Management Feature 5.2.0 which I came across when further dig in. However this issue is fixed in API Manager 2.1.0 which is to be released within next two weeks. You can use API Manager 2.1.0 and install the latest feature version without an issue and get this working.

    2. Hi Chamalee,

      Can you please provide me the JIRA number for the issue?

      Thanks & Regards

    3. There is no particular JIRA reported for this issue.
      It is glad to inform that we have released API Manager 2.1.0 version where the aforementioned issue is fixed. You can download the product form and test.


  4. Ok Sandip. Can you do the following steps before you trying with the local P2 repo.
    Steps :

    1.Follow the steps in the blog without put on the tick in front of "show only the latest versions" in step 4 and as a filter add "credential management" and search the repositories.
    Then you can find four repositories there.

    2. Select the "Accout Recovery and Credential Management" Feature with version number 5.2.0.

    3. Install the feature and Proceed with the steps.

    4. If you find any errors when following these steps, that may be due to corrupted jars when installing jars through network.

    5.Therefore if you find any errors go for locally building the P2 repo and install the feature.


    1. Hi,

      I tried these steps and got the error due to corrupted jars. That's the reason why I am going to setup local P2 repository.


  5. Hi Chamalee!

    Thank you very much for your help!

    I downloaded the zip file locally for p2 repository, but the installation failed.

    When we select the feature to install and click install,the next page is showing size of installation as 0.

    It looks like the jar is missing in the p2 repository.

    Thanks & Regards