Try WSO2 Cloud for Free
Sign in

All docs This doc
Skip to end of metadata
Go to start of metadata

WSO2 Identity Cloud provides single sign-on (SSO) capabilities for applications in an organization so that users of the organization can use all the applications seamlessly without having to sign in to each and every application separately. You can connect the on-premises user store of an organization directly to WSO2 Identity Cloud to enable this. 


Before you follow this tutorial, contact to get your organization (tenant) whitelisted to access WSO2 Identity Cloud.

An outbound agent is used to connect an organization's local LDAP to WSO2 Identity Cloud. This allows the organization to give application access (with SSO) for users in the LDAP, without sharing the credentials of the LDAP with WSO2 Identity Cloud.

In this tutorial you will learn how to connect an on-premises user store of your organization to WSO2 Identity Cloud.

Important! Java 1.8 or a later version is required to run the agent. Ensure that the correct Java version is installed in your server.

  1. Sign in to WSO2 Cloud via
  2. Click the navigation icon in the top right corner and then click Identity Cloud.

    This takes you to the WSO2 Identity Cloud home page.

  3. On the Identity Cloud home page, expand the left menu and click User Directories. This displays a page similar to the following:

  4. Click Connect my LDAP to Cloud. This takes a few seconds to complete and begins downloading the agent file. After the backend operations required to connect to the on-premises user store takes place, you will be redirected to the following page: 

    Note: If you are unable to download the agent, click DOWNLOAD AGENT to explicitly download the agent.

  5. Unzip the downloaded agent file. Open the <AGENT_HOME>/conf/userstore-config.xml file and do the required changes to point to your LDAP (or any other LDAP you require access to).

     Click to view a sample userstore-config.xml file
    Sample userstore-config.xml
    <UserStoreManager class="org.wso2.carbon.identity.agent.userstore.manager.ldap.LDAPUserStoreManager">
    		<Property name="ConnectionURL">ldap://localhost:10389</Property>
    		<Property name="ConnectionName">uid=admin,ou=system</Property>
    		<Property name="ConnectionPassword">admin</Property>
    		<Property name="UserSearchBase">ou=system</Property>
    		<Property name="UserNameAttribute">uid</Property>
    		<Property name="UserNameSearchFilter">(&amp;(objectClass=person)(uid=?))</Property>
    		<Property name="UserNameListFilter">(objectClass=person)</Property>
    		<Property name="GroupNameAttribute">cn</Property>
    		<Property name="GroupSearchBase">ou=system</Property>
    		<Property name="GroupNameListFilter">(objectClass=groupOfNames)</Property>	
    		<Property name="GroupNameSearchFilter">(&amp;(objectClass=groupOfNames)(cn=?))</Property>
    		<Property name="MembershipAttribute">member</Property>
    		<Property name="EmptyRolesAllowed">true</Property>
     Click to view descriptions of the key properties you use to configure the on-premise user stores

    The following table provides descriptions of the key properties in the userstore-config.xml file you use to configure on-premise user stores.

    Property name



    Connection URL to the user store server. In the case of default LDAP in Carbon, the port is specified in the carbon.xml file, and a reference to that port is included in this configuration.


    The username used to connect to the database and perform various operations. This user does not have to be an administrator in the user store or have an administrator role in the WSO2 product that you are using, but this user MUST have permissions to read the user list and users' attributes and to perform search operations on the user store. The value you specify is used as the DN (Distinguish Name) attribute of the user. This property is mandatory.

    ConnectionPasswordPassword for the ConnectionName user.

    Filtering criteria for listing all the user entries in the user store. This query or filter is used when doing search operations on users. In this case, the search operation only provides the objects created from the specified class. This query is the same as listing out all the available users in the management console.


    DN of the context or object under which the user entries are stored in the user store. In this case, it is the "users" container. When the user store searches for users, it will start from this location of the directory.

    Different databases have different search bases.

    UserNameSearchFilterFiltering criteria used to search for a particular user entry.

    The attribute used for uniquely identifying a user entry. Users can be authenticated using their email address, UID, etc.

    The name of the attribute is considered as the username.

    EmptyRolesAllowedSpecifies whether the underlying user store allows empty groups to be created. In the case of LDAP in Carbon, the schema is modified such that empty groups are allowed to be created. Usually LDAP servers do not allow you to create empty groups.
    GroupSearchBaseDN of the context under which user entries are stored in the user store.
    GroupNameListFilterFiltering criteria for listing all the group entries in the user store. Groups are created in LDAP using the "groupOfName" class. The group search operation only returns objects created from this class.
    GroupNameSearchFilterFiltering criteria used to search for a particular group entry.
    GroupNameAttributeAttribute used for uniquely identifying a user entry. This attribute is to be treated as the group name.
    MembershipAttributeAttribute used to define members of groups.
  6. To start the agent, run the script (on Linux/Mac OS) or wso2agent.bat (on Windows) from the bin folder. The agent asks for an installation token while starting up. Provide the installation token you see in step 4 of this tutorial and press enter.

    Once the agent successfully connects to Identity Cloud, a confirmation message is displayed on the command line.

    You can further verify this by checking the Identity Cloud UI. It shows your agent is connected successfully to the Identity Cloud.

Your user-store is ready and now you can use the credentials of users in the connected LDAP to log in to the user portal and configure single sign-on for your configured application.You can connect multiple agents (only two at the moment) to cloud to achieve high availability for outbound agent.

  • No labels