Step 1: Basic LDAP Configuration
Step 2: Authentication
Step 3: Authorization
- Define rolesDefine groupRolesMapping
- Define group/roles mapping
- Define the LDAP attributes to 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:

...

The following table lists possible values for authentication with an LDAP Server. The value {0} will be substituted with the account name.

Name	Example	Description
LDAP User DN Template	`{0}`	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 above example 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

Expand

title	Verify Authentication Settings

Verify by use of LDAP Browser

Possible values for the LDAP User DN Template can be derived from an account's properties. The below screenshot 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 use of the ldapSearch utility:

Code Block

language	text
title	Verify by use of ldapSearch utility
linenumbers	true
collapse	true

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.

Code Block

language	text
title	Verify by use of ldapSearch
linenumbers	true
collapse	true

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:

Code Block

language	bash
title	Verify by use of ldapSearch with public LDAP Server
linenumbers	true

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 no roles be assigned the account then users will find the following empty page that indicates missing authorization after successful authentication:

...

Name Required Example Description

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 Filter

no

(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 Attribute

no

cn

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

Substitution of the account value

...

Verification

Expand

title	Verify User Search

An LDAP Browser can be used to identify matching values for the LDAP Search Base and LDAP User Search Filter

...

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 without the domain part, for example account if account@domain is used.
Users can specify the 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.

Verification

Expand

title	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 . 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 Parent DN in the following screenshot holds the LDAP Search Base.

...

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 User Group Search Filter to look up the account.groups:

Name Required Example Description

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 Filter

yes

(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 Attribute

no

dn

The name of the attribute that identifies the group that 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

Expand

title	Verify Group Search

Anchor
groupsearchbase
groupsearchbase
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 respective groups by use of their LDAP browser:

The group entry holds a distinguished name like this:

Anchor
groupsearchfilter
groupsearchfilter
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 respective groups by use of 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

Expand

title	Verify Authorization SettingsGroup Search

Verify the

LDAP

LDAP Group Search Filter with the ldapSearch

command

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 hats 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.

Code Block

language	text
collapselinenumbers	true

# 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.

Anchor
substitution_of_the_username
substitution_of_the_username
Nested User Search

...

in Group Search

Consider a situation from the above example:

...

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.

To achieve this, the The following settings have to be specified:

Name	Required	Example	Description
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 Filter	yes	`(uid=%s)`	The syntax is the same as explained with Approach 1: User Search and use of the memberOf Attribute
LDAP User Name Attribute	yes	`cn`	Specifies 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

Expand

title	Substitution of the account nameVerify Nested User Search in Group Search

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.

Code Block

language	text	title	Username Substitution
collapselinenumbers	true

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.

...

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:

Group	Roles
`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`

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:

Group	Roles
`sos`	`it_operator`
`apl`	`administrator,application_manager`

Explanation:..

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

Show If

group	sos-members

Examples and special configurations

	userDnTemplate	groupSearchBase	groupNameAttribute	groupSearchFilter	searchBase	userNameAttribute	userSearchFilter
Group Search	`uid={0},ou=People,dc=sos`	`ou=Groups,dc=sos`	`cn`	`(uniqueMember=uid=%s,ou=People,dc=sos)`
Group Search where the member attribute does not contain the account name but the common name	`uid={0},ou=People,dc=sos`	`ou=Groups,dc=sos`	`cn`	`(uniqueMember=uid=%s,ou=People,dc=sos)`	`ou=People,dc=sos`	`cn`	`(uniqueMember=uid=%s,dc=example,dc=com)`
memberOf in the account record	`uid={0},ou=People,dc=sos`				`ou=People,dc=sos`		`(uid=%s)`
public LDAP Server	`uid={0},dc=example,dc=com`		`ou`		`dc=example,dc=com`	`uid`	`(uniqueMember=uid=%s,dc=example,dc=com)`

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:

Account Name	Password	LDAP Group	Role
gauss	password	mathematicians	all
newton	password	scientists	it_operator

Logging

References

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

Use Cases

For

...

analysis of LDAP Server connections, authentication and authorization consider to increase the log level and check the output of JOC Cockpit's authentication-debug.log file.

Space shortcuts

Page tree

Versions Compared

Old Version 18

New Version 19

Key

Relevant Tools

Proceeding

Verification

Verify by use of LDAP Browser

Verify by use of ldapSearch

Verify by use of JOC Cockpit

Substitution of the account value

Verification

Verification

Verification by LDAP Browser

Anchor
groupsearchbase
groupsearchbase
Looking up the value for the LDAP Group Search Base

Anchor
groupsearchfilter
groupsearchfilter
Looking up the value for the LDAP Group Search Filter

Verification by ldapSearch

Verify the

LDAP Group Search Filter with the ldapSearch

Utility

Verify the LDAP Group Search Base and LDAP Group Search Filter with an LDAP Browser

Anchor
substitution_of_the_username
substitution_of_the_username
Nested User Search

in Group Search

Verification

Verify by use of ldapSearch

Verify by use of LDAP Browser

Examples

Group/roles

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

Group/roles Mapping with

Approach 2: Group Search for account membership

Examples and special configurations

A public LDAP Server for testing the connection

References

Use Cases

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 18

New Version 19

Key

Relevant Tools

Proceeding

Verification

Verify by use of LDAP Browser

Verify by use of ldapSearch

Verify by use of JOC Cockpit

Substitution of the account value

Verification

Verification

Verification by LDAP Browser

AnchorgroupsearchbasegroupsearchbaseLooking up the value for the LDAP Group Search Base

AnchorgroupsearchfiltergroupsearchfilterLooking up the value for the LDAP Group Search Filter

Verification by ldapSearch

Verify the

LDAP Group Search Filter with the ldapSearch

Utility

Verify the LDAP Group Search Base and LDAP Group Search Filter with an LDAP Browser

Anchorsubstitution_of_the_usernamesubstitution_of_the_usernameNested User Search

in Group Search

Verification

Verify by use of ldapSearch

Verify by use of LDAP Browser

Examples

Group/roles

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

Group/roles Mapping with

Approach 2: Group Search for account membership

Examples and special configurations

A public LDAP Server for testing the connection

References

Use Cases

Anchor
groupsearchbase
groupsearchbase
Looking up the value for the LDAP Group Search Base

Anchor
groupsearchfilter
groupsearchfilter
Looking up the value for the LDAP Group Search Filter

Anchor
substitution_of_the_username
substitution_of_the_username
Nested User Search