Connecting an LDAP Server

In this section:

It is a generic requirement to connect an identity server to an existing external user store. The scenario described in this section addresses how to connect the WSO2 Identity Server to an external LDAP using the ReadOnlyLDAPUserStoreManager. The ReadOnlyUserLDAPStoreManager is capable of reading users, groups, and attributes from the external LDAP, but is not capable of doing operations such as creating users, groups, resetting passwords, setting attributes, and so on.

To add an external user store, click Configure, select User Store Management, and then click Add Secondary User Store.

The following table shows the properties in the User Store Manager page, and describes how each parameter should be set:

Property Name

Description

User Store Manager Class

This property must be set to the following value:

org.wso2.carbon.user.core.ldap.ReadOnlyLDAPUserStoreManager

Domain Name

Name of the domain.

ConnectionName*

This must be the DN (Distinguish Name) of the admin user in LDAP.

ConnectionURL*

Connection URL for the user store.

ConnectionPassword*

Password of the admin user.

UserSearchBase*

DN of the context under which user entries are stored in LDAP.

Disabled*

Whether user store is disabled.

UserNameListFilter*

Filtering criteria for listing all the user entries in LDAP.

UserNameAttribute*

Attribute used for uniquely identifying a user entry. Users can be authenticated using their email address, User ID, and so on.

UserNameSearchFilter*

Filtering criteria for searching a particular user entry.

UserEntryObjectClass*

Object Class used to construct user entries.

GroupEntryObjectClass*

Object Class used to construct group entries.

ReadGroups*

Specifies whether groups should be read from LDAP.

GroupSearchBase*

DN of the context under which user entries are stored in LDAP.

GroupNameAttribute*

Attribute used for uniquely identifying a user entry.

GroupNameListFilter*

Filtering criteria for listing all the group entries in LDAP.

MembershipAttribute*

Attribute used to define members of LDAP groups.

GroupNameSearchFilter*

Filtering criteria for searching a particular group entry.

These properties should be provided by the LDAP Server administrator. Optionally, you can use some third party tools, such as the SOFTERRA LDAP browser, to browse the LDAP server and manually check the provided properties.

Note: Check the WSO2 Identity Server console output to detect possible exceptions when creating new external user stores. It is a best practice to detect invalid credentials, connection timeouts, and so on.

The following image shows a sample User Store page.

After the LDAP User Store has been created, the Users page is displayed. To display users for specific domains, select the domain from the Select Domain drop-down list, as shown in the following image.

Note: To avoid domain confusions, it is recommended to explicitly specify the domain for the user name upon authentication. For example, PROJECTS.LOCAL/WSO2user. For internal users, specify the PRIMARY/ domain, for example, PRIMARY/admin.

It is preferred to explicitly set domains when specifying the username JNDI property:

<Environment override="true" type="java.lang.String" value="PRIMARY/admin" name="is.wso2.username"/>

However, no roles are assigned to users (except the default Internal/everyone). A separate configuration must be performed. Roles can be retrieved either from LDAP or from the internal store, which are described in the following sections.
x
Assigning Internal Roles

If users in the LDAP user store are not assigned to any roles (groups), or assigned to roles that are not handled by policies, then the corresponding roles should be created in the WSO2 Identity Server internal store. Since the LDAP connection is used in read-only mode, no changes can be applied to the LDAP store, and all configurations and role assignments will be stored internally.

To assign internal roles, click Home, select Configure, Users and Roles, and then click Roles, and create a new role by clicking Add New Role Internal.

For more information on how to install the server, proceed with step 5 in the procedure from Connecting an LDAP Server, but create a Role Internal instead.

After users from the LDAP server are listed in the Users list, and internal roles have been created, you can assign users to the corresponding roles. This can be done with pressing the Assign Roles link in the Users page, as shown in the following image.

Note: Only internal roles can be assigned. You cannot assign users to roles retrieved from LDAP.

After retrieval from the LDAP server, users can be used for authentication and authorization using the provided roles. Domain prefixes (for example, PROJECTS.LOCAL\) can be skipped during authentication, especially if the user belongs to only one user store (as described in this documentation).

Prefixes will also be removed by default from roles in the application, so that provided policies will be applicable for them despite their domains.

Note: Data domains are also added through internal roles. For more information, see Handling Groups and Domains.
Top of page
x
Adding Additional Claim Mapping

Application functionalities require one additional configuration step if the WSO2 Identity Server uses the LDAP user store. Click Configure, Claim Management, select urn:scim:schemas:core:1.0, and then click Add New Claim Mapping, as shown in the following image.

The following image shows the New Claim Details section.

The following table shows the parameters and the values you need to set.

Parameter

Value

Description

Login Username

Claim Uri

urn: scim:schemas:core:1.0:loginName

Mapped Attribute (s)

sn

Read-only

true

Note: The Mapped Attribute (s) parameter value should be the same as the value of UserNameAttribute from the LDAP user store configuration.
x
Consuming LDAP External User Roles

You can also specify users, roles, and corresponding assignments in the LDAP server. WSO2 Identity Server must be properly configured to utilize this information properly. The user store configuration must be extended to include the location of roles and other specific properties. To do this, edit the current LDAP user store and provide the values in the Optional section, as shown in the following image.

After the Optional properties have been set, the roles will appear in the Roles list, as shown in the following image.

Corresponding users will be assigned to those roles. Roles are available for permission editing.
Top of page
x
Configuring Role List Retrieving Query

How to:

The LDAP authentication is case insensitive, but the internal mechanisms for mapping roles to users of the WSO2 Identity Server are not. The following configuration is required to adjust this.

Note: The following procedure is applicable only if you are using WSO2 Identity Server Version 5.0 and higher.
x
Procedure: How to Configure Role List Retrieving Query

To configure the role list retrieving query:

  1. Open the following: 
    %WSO2IS_HOME%\repository\conf\user-mgt.xml
  2. Add the following property inside the UserManages/Realm/Configuration tag: 
    <Property name="GetRoleListOfInternalUserSQL">SELECT UM_ROLE_NAME FROM UM_HYBRID_USER_ROLE, UM_HYBRID_ROLE WHERE UPPER(UM_USER_NAME)=UPPER(?) AND UM_HYBRID_USER_ROLE.UM_ROLE_ID=UM_HYBRID_ROLE.UM_ID AND UM_HYBRID_USER_ROLE.UM_TENANT_ID=? AND UM_HYBRID_ROLE.UM_TENANT_ID=? AND UM_HYBRID_USER_ROLE.UM_DOMAIN_ID=(SELECT UM_DOMAIN_ID FROM UM_DOMAIN WHERE UM_TENANT_ID=? AND UM_DOMAIN_NAME=?)</Property>
  3. Restart the WSO2 Identity Server instance.

    The following image shows the required change that was applied.

iWay Software