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 using STARTTLS and LDAP over SSL using LDAPS.

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

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

Relevant Tools

• LDAP Browser:
  • The screenshots used in this article indicate the Softerra® LDAP Browser that was used to connect to the relevant LDAP Directory Service.
• Command Line Client:
  
  • The examples used in this article are executed with ldapSearch.

Proceeding

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.

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 

See the JS7 - LDAP Identity Service, chapter: Identity Service Settings for detailed explanations about the general 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.

Verification

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 with JOC Cockpit. Accounts are managed with the Identity Service in parallel to the LDAP Server. No user passwords are managed by the JOC Cockpit as authentication is performed by the LDAP Directory Service.

Assign Roles with Identity Service Type LDAP-JOC

For details see JS7 - Manage Roles and Permissions.

Assign Roles with Identity Service Type LDAP

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

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

• The LDAP Server makes use the memberOf attribute: In this case users can retrieve the list of groups and should proceed with the Approach 1: User Search and use of the memberOf Attribute section of this page.
• The LDAP Server does not make use of the memberOf attribute: In this case the LDAP groups include the accounts that are members of the group. Users should proceed with the Approach 2: Group Search for account membership section of this page.

Approach 1: User Search and use of the memberOf Attribute

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

Users define the LDAP Search Base and LDAP User Search Filter to look up the account.

Verification

Approach 2: Group Search for account membership 

This approach looks up groups in the LDAP Server that the account is a member of.

Users define the LDAP Group Search Base and LDAP Group Search Filter to look up groups:

Verification by LDAP Browser

Verification by ldapSearch

# 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

Nested User Search in Group Search

Consider a situation from the above example:

• LDAP query example includes (uniqueMember=uid=ur,ou=People,dc=sos)
• The value of the uid attribute usually is specified by the %s placeholder and is substituted by the account from account@domain used for login. This example makes use of ur.
• If the uid attribute does not make use of the user's account but some other attribute available for the account then an additional LDAP query is required to the identify the account.

For example, if the uid attribute holds the value of the cn attribute then users have to search for the account first and then specify the name of the attribute that holds the value for the substitution.

The following settings have to be specified:

Verification

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

Group Roles Mapping

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

Examples

Group/roles Mapping with Approach 1: User Search and use of the memberOf Attribute

In the JOC Cockpit Identity Service Settings the following group/roles mapping is specified:

Explanation:

• As Approach 1: User Search and use of the memberOf Attribute is used then distinguished names of groups have to be specified.

Group/roles Mapping with Approach 2: Group Search for account membership

In the JOC Cockpit Identity Service Settings the following group/roles mapping is specified, for example when using the cn attribute for group names:

Explanation:

• As Approach 2: Group Search for account membership is used the group's Common Name is specified.

A public LDAP Server for Testing

An online LDAP Server is available for public access (managed by Forum Systems). This server can be used to test LDAP authentication and authorization.

• The LDAP Server offers two accounts:
  • gauss: the user account is assigned the all role which allows access to any operation in JOC Cockpit.
  • newton: the user account is assigned the application_manager role which includes to manage scheduling object, but for example does not allow to restart a Controller.
  • The roles and permissions are described with the JS7 - Default Roles and Permissions article.
• The accounts are members in different LDAP groups that are mapped to respective roles in JOC Cockpit.

• The LDAP settings are available for download: PublicLDAP.ldap.json

  • The popup window to manage LDAP Server settings offers an Upload button to import downloaded settings.
    
    
    
    

• Both accounts gauss and newton make use of the same password:
  
  

  User Account	Password	LDAP Group	Role
  gauss	password	mathematicians	all
  newton	password	scientists	application_manager

Logging

• JS7 - Logging
  
  • JS7 - Log Files and Locations
  • JS7 - Log Levels and Debug Options
• For analysis of LDAP Server connections, authentication and authorization consider increasing the log level and checking the output of JOC Cockpit's authentication-debug.log file.