This documentation is for WSO2 Identity Server 5.3.0 . View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

This section is about the user creation flow which allows users to decide their own passwords. This process is initiated by the administrator when selecting Ask password from user during the user creation process. This is different from the default flow, in which the administrator decides the passwords for users. Using the Ask Password option is the standard method for user management as the administrator does not have to remember and specify passwords when creating an account for a user. When selecting this option, the administrator must enter an Email Address. The Identity Server sends an email to this address that provides the users with a redirection URL. This directs the users to a screen where they can provide the password for the account that was newly created for them by the administrator. 


Note the following before you begin:

  • This feature has been fixed with the WUM Update that is effective from 2017-06-13. To add this WUM update to your product, see Updating WSO2 Products.
    You cannot configure this feature successfully without the WUM update.
  • By default, you cannot use special characters such as !#$%&'*+-=?^_ when you update a users email address. The use of special characters is supported with the WUM update that is effective from 2018-01-20. For more information, see the Try it out section. To add this WUM update to your product, see Updating WSO2 Products.
  • From 5.3.0 onwards there is a new implementation for identity management features. The steps given below in this document follows the new implementation, which is the recommended approach for creating users using the ask password option.


    You can deploy a WUM update into production only if you have a paid subscription. If you do not have a paid subscription, you can either use this functionality when it is added to an upcoming WSO2 Identity Server release, or you can enable the identity management feature using the old implementation. For information on how to use the old implementation, see Creating Users using the Ask Password Option in the WSO2 Identity Server 5.2.0 documentation. The old implementation has been retained within the distribution for backward compatibility, and can be used if required.

Follow the instructions given below to configure this feature. 

Before you begin

Ensure that the "IdentityMgtEventListener" with the orderId=50 is set to false and that the Identity Listeners with orderId=95 and orderId=97 are set to true in the <IS_HOME>/repository/conf/identity/identity.xml file.

By default, the properties are configured as shown below. Therefore, if you have not changed the default configurations, you can skip this step. 

<EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.mgt.IdentityMgtEventListener" orderId="50" enable="false"/>
<EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.governance.listener.IdentityMgtEventListener" orderId="95" enable="true" />
<EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.governance.listener.IdentityStoreEventListener" orderId="97" enable="true">

Follow the steps given below to configure WSO2 IS to enable the ask password feature:

  1. Add the configuration given below to the <IS_HOME>/repository/conf/identity/identity.xml file under <Server> element to set the redirection URL valid time period in minutes
    The redirection link that is provided to the user to set the password is invalid after the time specified here has elapsed. 

    <Server xmlns="">

    You can also configure the expiry time through the Management Console.

     Click to see how to configure this through the management console
    1. Start the Identity Server and login to the Management Console.

    2. Click Resident under Identity Providers on the Main tab and expand the Account Management Policies tab. 

    3. Expand the User Onboarding tab and configure the Ask password code expiry time field. Click Update to save changes. 

  2. Optionally, if you are adding users via the management console, the EnableAskPasswordAdminUI property value needs to be added to the <IS_HOME>/repository/conf/identity/ identity.xml file.

  3. Configure the email settings in the <IS_HOME>/repository/conf/output-event-adapters.xml file. 

    mail.smtp.fromProvide the email address of the SMTP account.
    Example: [email protected]
    mail.smtp.userProvide the username of the SMTP account.
    Example: abcd
    mail.smtp.passwordProvide the password of the SMTP account.
    <adapterConfig type="email">
        <!-- Comment mail.smtp.user and mail.smtp.password properties to support connecting SMTP servers which use trust
            based authentication rather username/password authentication -->
        <property key="mail.smtp.from">{EMAIL_ID}</property>
        <property key="mail.smtp.user">{USERNAME}</property>
        <property key="mail.smtp.password">{PASSWORD}</property>
        <property key=""></property>
        <property key="mail.smtp.port">587</property>
        <property key="mail.smtp.starttls.enable">true</property>
        <property key="mail.smtp.auth">true</property>
        <!-- Thread Pool Related Properties -->
        <property key="minThread">8</property>
        <property key="maxThread">100</property>
        <property key="keepAliveTimeInMillis">20000</property>
        <property key="jobQueueSize">10000</property>

    If you are using a Google mail account, note that Google has restricted third-party apps and less secure apps from sending emails by default. Therefore, you need to configure your account to disable this restriction, as WSO2 IS acts as a third-party application when sending emails to confirm user registrations or notification for password reset WSO2 IS.

     Click here for more information.

    Follow the steps given below to enable your Google mail account to provide access to third-party applications.

    1. Navigate to
    2. Click Signing in to Google on the left menu and make sure that the 2-step Verification is disabled or off.
    3. Click Connected apps and sites on the left menu and enable Allow less secure apps.

    Tip: The email template used to send this email notification is the AskPassword template.

    You can edit and customize the email template. For more information on how to do this, see Customizing Automated Emails.

  4. Start the Identity Server and log in to the Management Console.

  5. In the Main tab, click, under Identity Providers, click Resident and expand the Account Management Policies tab. 
  6. Expand the User Onboarding tab and select Enable User Email Verification. Click Update to save changes. 

    The EmailVerification property can be enabled for each tenant at tenant creation by adding the following configuration to the <IS_HOME>/repository/conf/identity/identity.xml file as seen below. Please note this should be added before the first start up. If you added this later, you need to manually enable the email verification in the resident IDP configurations of the already created tenants and the super tenant.


Try it out

You can use one of the following methods to creating a user using the ask password option. 

If you want to enter any of the !#$%&'*+-=?^_ special characters in the email address, make sure that WSO2 IS 5.3.0 is WUM updated until 2018-01-20 or beyond. 

 Click here for more information on the steps you need to follow after WUM updating IS 5.3.0.
  1. Go to management console click the Main tab > Claims > List.

  2. Click

  3. Expand the Email claim and click Edit.

  4. Add the characters you need out of the !#$%&'*+-=?^_ special characters to the Regular Expression.

    Adding the # character to the regex email pattern.^([a-zA-Z0-9_\.\-#])+\@(([a-zA-Z0-9#\-])+\.)+([a-zA-Z0-9#]{2,4})+$
    Adding the $ character to the regex email pattern.
    Make sure to use the appropriate escape characters, such as \\, when using the $ character.

Now, follow the steps given below to add a new user.

Management console

Do the following steps to test the account creation using the password option.

  1. Start the WSO2 Identity Server.

  2. On the Main tab in the  Management Console , click  Add under Users and Roles.

  3. Click Add new User.

    If you are using the $ character in the email address, make sure to use appropriate escape characters, such as /.
    Example: abc\[email protected]

  4. Fill in the form:

    1. Select the user store where you want to create this user account from the drop down as the Domain.
      This includes the list of user stores you configured. See Configuring User Stores for more information.
    2. Enter a unique User Name that is used by the user to log in.

    3. Allow users to enter their own password by selecting the Ask password from user option.

    4. Enter a valid Email Address and click Finish.

  5. The Identity Server sends an email to the email address provided. The email contains a redirect URL that directs the users to a screen where they must provide their own password.

SCIM 2.0

Before you begin!

Follow the steps given in the Configuring SCIM 2.0 Provisioning Connector Documentation to configure IS 5.3.0 with SCIM 2.0.

  1. Set the user-schema-extension-enabled property in the <IS_HOME>/repository/conf/identity/charon-config.xml file to true.

    <Property name="user-schema-extension-enabled">true</Property>
  2. Now you are be able to use the ask password features using SCIM 2.0. A sample curl commands is given below: 

    curl -v -k --user admin:admin --data '{"schemas":[],"name":{"familyName":"Smith","givenName":"Paul"},"userName":"Paul","password":"password","emails":[{"primary":true,"value":"[email protected]","type":"home"},{"value":"[email protected]","type":"work"}],"EnterpriseUser":{askPassword:"true"}}' --header "Content-Type:application/json" https://localhost:9443/scim2/Users
Related Links
  • For information on how to edit an existing email template, see Email Templates.
  • By default, the claim values of the identity claims used in this feature are stored in the JDBC datasource configured in the identity.xml file. See Configuring Claims for more information on how to store the claim values in the user store.
  • No labels