Introduction

The JS7 - LDAP Identity Service offers authentication from an LDAP Directory Service and is available from JS7 - REST Web Service API.

• Early JS7 releases make use of the JS7 - Shiro Identity Service, for migration see JS7 - Shiro Identity Service Migration.
• The connection to an LDAP Server can be secured, see JS7 - LDAP over TLS (STARTTLS) and LDAP over SSL (LDAPS).

This article explains the steps for configuration of an LDAP Directory Service:

• Step 1: Basic LDAP Configuration
• Step 2: Authentication
• Step 3: Authorization
  • Define roles
  • Define groupRolesMapping
  • Define the LDAP attributes to search for groups

Relevant Tools

• LDAP Browser:
  • The screenshots used in this article were made with the Softerra LDAP Browser that was configured to use the relevant LDAP Directory Service.
• Command Line Client:
  
  • The examples used in this article are executed with ldapSearch.

Preceding

The following diagram provides an overview of the steps to set up LDAP connections:

Step 1: Basic LDAP Configuration

The LDAP configuration can be managed from the Administration->Manage Identity Services view like this:

Add Identity Service

In a first step click the Add Identity Service button that brings up the following popup window.

• A Name has to be specified that identifies the LDAP Identity Service.
• The Identity Service Type gives a choice
  • LDAP: to map user/role assignments from security group membership in the LDAP Server,
  • LDAP-JOC: to manage user/role assignments for the Identity Service with JOC Cockpit.
• Do not make the Identify Service Required before you are certain that the service configuration works fine.
• Select the single-factor Authentication Scheme.
  
  

Manage Identity Service Settings

In a next step set up the configuration of the service:

• Select the Manage Settings action menu item like this:
  
  

This brings forward a popup window with the following tabs:

• Simple Mode: The most frequently used settings are available.
• Expert Mode:: The full set of settings is available.
  
  

Specify General Settings 

Find detailed explanations about general settings from JS7 - LDAP Identity Service, chapter: Identity Service Settings.

The following table lists the general items used to configure an LDAP connection.

Step 2: LDAP Authentication

Specify Authentication Settings

The following table lists possible values for authentication with an LDAP Server:

The value {0} will be substituted with the account name.

Verify Authentication Settings

ldapsearch -h localhost -p 389 -b "uid=ur,ou=People,dc=sos" -x

# This should return a result such as:

# ur, People, sos
dn: uid=ur,ou=People,dc=sos
mail: *********
uid: ur
givenName: Uwe
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: Risse
cn: Uwe Risse
preferredLanguage: de
# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -x

# This should return a result such as:

# extended LDIF
#
# LDAPv3
# base <uid=gauss,dc=example,dc=com> with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#
 
# gauss, example.com
dn: uid=gauss,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: Carl Friedrich Gauss
sn: Gauss
uid: gauss
mail: gauss@ldap.forumsys.com
 
# search result
search: 2
result: 0 Success
 
# numResponses: 2
# numEntries: 1

ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -W -D "uid=gauss,dc=example,dc=com"

Step 3: Authorization

Authorization includes the assignment of roles to user accounts. Roles, in turn, hold permissions. For details see JS7 - Manage Roles and Permissions.

There are two options for assignment of roles to user accounts depending on the Identity Service Type:

• LDAP: add a Group/Roles mapping. Membership of a user account in security groups of the LDAP Server is mapped to roles in the Identity Service.
• LDAP-JOC: add a user account and assign roles. Accounts are managed with the Identity Service in parallel to the LDAP Server. No user passwords are managed with JOC Cockpit as authentication is performed with the LDAP Directory Service.

Assign Roles with Identity Service

For details see JS7 - Manage Roles and Permissions.

Map Roles from LDAP Security Groups

If roles are assigned with JOC Cockpit by use of the Identity Service Type LDAP-JOC then you can skip this chapter.

The group/roles mapping defines a search for groups and a maps resulting groups to roles.

The search for groups can be executed with one of the following options:

• The LDAP Server makes use a memberOf attribute. In this case users can retrieve the list of groups with the User Search and should proceed with chapter Using memberOf with User Search.
• The LDAP Server does not make use of a memberOf attribute. In this case the group contains the Accounts that are members of the group. Users should proceed with chapter Using Group Search.

Substitution of the account value

In both searches with groupSearchFilter and with userSearchFilter users can specify placeholders:

• In the groupSearchFilter and in the userSearchFilter users can specify the placeholder %s, for example: (uid=%s)
  • The placeholder %s will be substituted with the account from the login. Users can login with domain\account or account@domain.
• Users can specify the placeholder ^s, for example: (uid=^s)
  • The placeholder ^s will be substituted with the original value from the login, for example: account@domain.

Approach 1: Using User Search to look up the memberOf Attribute

This approach looks up the account entry and reads the memberOf attribute. This attribute frequently is available from Microsoft Active Directory^® LDAP Servers.

Define a userSearchFilter and a searchBase to look up the account.

Microsoft Active Directory^® supporting the memberOf attribute

General

An LDAP Browser can be used to identify the suitable values for the searchBase and the userSearchFilter. Users can perform a directory search with the value and should find a single resulting entry. 

The searchBase is the value of the base DN (or ParentDN in the screenshot above).

Hint:

• If the attribute name in a user's environment does not match the default name memberOf then users can specify the name of the attribute with the groupNameAttribute as explained below.

Approach 2: Using Group Search to look up groups that an account is a member of

If the LDAP Server makes use of the memberOf attribute then users can skip this section and proceed with chapter Using memberOf with User Search.

To specify a group search the following settings have to be specified

• LDAP Group Search Base
• LDAP Group Search Filter
• LDAP Group Name Attribute

The groupSearchBase and groupSearchFilter for example can be configured like this:

• groupSearchBase = ou=Groups,dc=sos
• groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)

Looking up the value for the groupSearchBase

Identify the location where groups are stored in the LDAP Server, this should identify the groupSearchBase:

Looking up the value for the groupSearchFilter

When clicking a group entry (in the screenshot, cn=apl the members included should become visible:

The groupSearchFilter is configured with attr=val where attr is the name of the attribute and val is the value. In this example, the attribute is uniqueMember and the value is valuid=%s,ou=People,dc=sos, where the userid is replaced with %s. This results in:

• groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)

# extended LDIF
#
# LDAPv3
# base <ou=Groups,dc=sos> with scope subtree
# filter: uniqueMember=uid=ur,ou=People,dc=sos
# requesting: ALL
#
 
# sos, Groups, sos
dn: cn=sos,ou=Groups,dc=sos
description: Employees of SOS GmbH
objectClass: top
objectClass: groupofuniquenames
cn: sos
uniqueMember: uid=ur,ou=People,dc=sos
uniqueMember: uid=fTester,ou=People,dc=sos

# apl, Groups, sos
dn: cn=apl,ou=Groups,dc=sos
objectClass: top
objectClass: groupofuniquenames
cn: apl
uniqueMember: uid=ur,ou=People,dc=sos
uniqueMember: uid=fTester,ou=People,dc=sos
 
# search result
search: 2
result: 0 Success
 
# numResponses: 3
# numEntries: 2

The groupNameAttribute is the name of the attribute that holds the group name.

• groupNameAttribute = cn

Hint: The value of this attribute has to be used with the groupRolesMap attribute. Typical values of the attribute could be cn=groupname,ou=Groups,dc=sos .

Substitution of the account name

If roles are assigned by JOC Cockpit using the Identity Service Type LDAP-JOC you can skip this chapter.

If the value of the member of the groups contains the Account name from the login then you can skip this chapter

Sometimes the values of the member do not contain the Account Name from the login but, for example, the cn of the Account. In this case users have to search for the account first and then to specify the name of the attribute that should be used instead of the account name from the login .

To achieve this, the searchBase, userSearchFilter and userNameAttribute attributes can be specified:

searchBase = ou=People,dc=sos
userSearchFilter = (uid=%s)

ldapsearch -h localhost -p 389 -b "ou=People,dc=sos" -s sub "uid=fTester" -x

# This should return the following result

# extended LDIF
#
# LDAPv3
# base <ou=People,dc=sos> with scope subtree
# filter: uid=fTester
# requesting: ALL
#

# fTester, People, sos
dn: uid=fTester,ou=People,dc=sos
mail: info@sos-berlin.com
uid: fTester
givenName: Fritz
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: Tester
cn: Fritz Tester

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

Then identify the name of the attribute that contains the value for substitution. For example:

• userNameAttribute = cn

Group Roles Mapping

The mapping is configured with the "Expert Mode" of the LDAP Identity Service Settings.

Note that the value of the group depends on the result of the group search. It is the value of the attribute that has been specified with the groupNameAttribute attribute. This attribute defaults to memberOf. In case that group memberships are looked up by use of the memberOf attribute of an account then the value of the memberOf attribute has to be specified, i.e. the Distinguished Names of group hits.

Example for Group Mapping with Microsoft Active Directory® and memberOf Attribute

A typical mapping when using Microsoft Active Directory® and the memberOf attribute includes to specify each group by its Distinguished Name like this:

• CN=Group1,OU=SpecialGroups,OU=Groups,OU=Company,DC=sos-berlin,DC=com ==>  all
• CN=AnotherGroup,OU=SpecialGroups,OU=Groups,OU=CompanyDC=sos-berlin,DC=com ==>  adminitrator
• CN=Beginners,OU=SecurityGroups,OU=Groups,OU=Company,DC=sos-berlin,DC=com ==> business_user

Example for Group Mapping with cn Attribute

A mapping that is based on Group Search would apply resulting groups from the value of their Common Name like this:

• sos ==> it_operator
• apl ==> administrator,application_manage

The configuration will look like this:

Examples and special configurations

A public LDAP Server for testing the connection

An online public LDAP server which can be accessed using a relatively simple configuration is available from Forum Systems. This server can be used to set up a test environment with LDAP authentication. In this article we will refer to the authentication of two user accounts on this server - gauss and newton - that are each members of a different LDAP group as shown in the following table:

 Logging

References

• JS7 - Logging
  
  • JS7 - Log Files and Locations
  • JS7 - Log Levels and Debug Options

Use Cases

For debugging of LDAP Server connections