Skip to end of metadata
Go to start of metadata

Introduction

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

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

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.

NameValueDescription

LDAP Server URL

ldap://host:port

The protocol, host and the port of the LDAP Server. 

LDAP Start TLS

Checkbox checked or unchecked

To enable StartTls set the value to true (Default is unchecked)

See JS7 - LDAP over TLS using STARTTLS and LDAP over SSL using LDAPS

Host Name Verification

on|offEnables host name verification for the server certificate. The default value is off.

LDAP Truststore Path


If the LDAP Server is to be configured for TLS/SSL protocols then the indicated truststore has to include an X.509 certificate specified for the Extended Key Usage of Server Authentication.

LDAP Truststore Password


If an LDAP truststore is used and the LDAP truststore is protected by a password, then the password has to be specified.

LDAP Truststore Type


If an LDAP truststore is used then the type of the indicated truststore has to be specified being either PKCS12 or JKS (deprecated).

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.

NameExampleDescription

LDAP User DN Template

{0}

This should work from scratch for Microsoft Active Directory®

For login use domain\account or account@domain where account is the value of the sAMAccountName attribute.


uid={0},ou=People,dc=sos

Use with Microsoft Active Directory® and other LDAP Servers.

The LDAP search expression makes use of the uid attribute. This is applicable if the account specified for login matches the value of the uid attribute. Users can use other attributes, for example the sAMAccountName if their LDAP Server makes use of this attribute.

The specification of an organizational unit and domain context limits access to hierarchy levels.


cn={0},ou=Users,dc=sos,dc=berlin,dc=com

Use with Microsoft Active Directory® and other LDAP Servers.

Similar to the example above, the Common Name cn attribute is used. This requires the Common Name to be unique.


uid={0},dc=example,dc=com

This example can be used with a Public LDAP Server.

Verification

Verify by use of LDAP Browser

Possible values for the LDAP User DN Template can be derived from an account's properties. The screenshot below displays such properties from an LDAP Browser:

In a first step search with the value from the LDAP User DN Template in the Search DN input field. The query should return only one entry.


From the properties of the resulting entry the value for the LDAP User DN Template can be extracted. Users should replace the uid attribute value with: {0}.

Verify by use of ldapSearch

Users can check the value of the LDAP User DN Template setting by using the ldapSearch utility:

Verify by use of ldapSearch utility
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


Example for use with a public LDAP Directory Service

The following example makes use of a publicly available LDAP Server.

Verify by use of ldapSearch
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


Note: 

The option -x is used in the ldapSearch examples in this article. It is possible that an LDAP Directory Service does not allow this option and instead an account and a password have to be specified. In this case the command will look like this:

Verify by use of ldapSearch with public LDAP Server
ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -W -D "uid=gauss,dc=example,dc=com"

Verify by use of JOC Cockpit

Users can try to login with an LDAP account/password combination. An account should be used that has been verified by executing the ldapSearch command described above. Should authentication be successful but roles have not been assigned for the account then users will find the following empty page that indicates missing authorization after successful authentication:

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:

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.

NameRequiredExampleDescription

LDAP Search Base

yes

ou=People,dc=sos

The specification of an organizational unit and domain context is used to limit access to hierarchy levels.

LDAP User Search Filterno(uid=%s)

The search filter is applied to identify an account within the hierarchy of the LDAP Search Base.

The example makes use of the uid attribute, other attributes can be used. However, the LDAP query has to identify a unique account. If no value is specified then the default value applies.

Users can specify placeholders with the LDAP User Search Filter:

  • Placeholder %s, for example: (uid=%s)
    • The placeholder %s will be substituted with the account from the login without the domain part, for example account if account@domain is used.
  • Placeholder ^s, for example: (uid=^s)
    • The placeholder ^s will be substituted with the account from the login including the domain part, for example account@domain.

Default: (sAMAccountName=%s)

LDAP Group Name Attributenocn

If the LDAP Server makes use of an attribute that is different to memberOf but that provides the same functionality then users should specify this attribute with their LDAP query.

Default: memberOf

Verification

An LDAP Browser can be used to identify matching values for the LDAP Search Base and LDAP User Search Filter. Users can perform an LDAP query with the attributes that match their LDAP Server. The query has to identify a unique account

The column Parent DN in the following screenshot holds the LDAP Search Base.

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:

NameRequiredExampleDescription

LDAP Group Search Base

yes

ou=Groups,dc=sos

The specification of an organizational unit and domain context is used to limit access to hierarchy levels.

LDAP Group Search Filteryes(uniqueMember=uid=%s,ou=People,dc=sos)

The LDAP Group Search Filter is applied to identify groups within the hierarchy of the LDAP Group Search Base that the authenticated account is a member of.

The LDAP Group Search Filter make use of an attribute that is specific for the LDAP Server product.

The example makes use of the uniqueMember attribute that specifies the uid attribute to identify the authenticated user account. Other attributes can be used. However, the LDAP query has to identify a unique account.

Users can specify placeholders with the LDAP Group Search Filter:

  • Placeholder %s, for example: (uid=%s)
    • The placeholder %s will be substituted with the account from the login without the domain part, for example account if account@domain is used.
  • Placeholder ^s, for example: (uid=^s)
    • The placeholder ^s will be substituted with the account from the login including the domain part, for example account@domain.
LDAP Group Name Attributenodn

The name of the attribute that identifies the group which results from an LDAP query using LDAP Group Search Base and LDAP Group Search Filter.

The value of this attribute is used for the groups/roles mapping.

  • If the dn attribute is used then the group/roles mapping specifies the group including its hierarchy levels.
  • If the cn attribute is used then the group/roles mapping specifies the group name without its hierarchy levels.

Default: cn


Verification by LDAP Browser

Looking up the value for the LDAP Group Search Base

Users can identify the LDAP Group Search Base in their LDAP Server by navigating to the relevant groups using their LDAP browser:


The group entry holds a distinguished name like this:

Looking up the value for the LDAP Group Search Filter

Users can identify the LDAP Group Search Filter in their LDAP Server by navigating to the relevant groups using their LDAP browser:

In this example the attribute is uniqueMember and the value is uid=%s,ou=People,dc=sos.

As a result the following LDAP Group Search Filter is used: (uniqueMember=uid=%s,ou=People,dc=sos)

Verification by ldapSearch

Verify the LDAP Group Search Filter with the ldapSearch Utility

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

This search returns the groups that the account is a member of. Users should identify the value of the LDAP Group Name Attribute attribute in the output of the example.

  • If the LDAP Group Name Attribute dn is used then from the first result the value cn=sos,ou=Groups,dc=sos has to be applied for group/roles mapping.
  • If the LDAP Group Name Attribute cn is used then from the first result the value sos has to be applied for group/roles mapping.

# 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
Verify the LDAP Group Search Base and LDAP Group Search Filter with an LDAP Browser

Users can verify both attribute values by performing an LDAP query. The result should display all groups the account is a member of.


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:

NameRequiredExampleDescription

LDAP Search Base

yes

ou=People,dc=sos

The specification of an organizational unit and domain context is used to limit access to hierarchy levels.

LDAP Search User Filteryes(uid=%s)

The syntax is the same as explained with Approach 1: User Search and use of the memberOf Attribute

LDAP User Name AttributeyescnSpecifies the attribute that holds the value to replace the %s placeholder in LDAP Group Search Filter, for example: (uniqueMember=uid=%s,ou=People,dc=sos) 

Verification

Verify by use of ldapSearch

This LDAP query returns the account with the given account name, for example fTester. Users have to identify the attribute that holds the value that is expected from the uid attribute in the LDAP Group Search Filter. This values has to be used for substitution in the LDAP Group Search Filter.

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


Verify by use of LDAP Browser

Users can use their LDAP Browser to test the LDAP query that identifies the user account. The result should return a single account.

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:


GroupRoles
CN=Group1,OU=SpecialGroups,OU=Groups,OU=Company,DC=sos-berlin,DC=comall
CN=AnotherGroup,OU=SpecialGroups,OU=Groups,OU=CompanyDC=sos-berlin,DC=comadminitrator
CN=Beginners,OU=SecurityGroups,OU=Groups,OU=Company,DC=sos-berlin,DC=combusiness_user


Explanation:

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:


GroupRoles
sosit_operator
apladministrator,application_manager


Explanation:

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 AccountPasswordLDAP GroupRole
    gausspasswordmathematicians

    all

    newtonpasswordscientistsapplication_manager

Logging