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

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.

...

Name	Value	Description
LDAP Server URL	`ldap://host:port`	The protcol, host and the port of the LDAP Server.
LDAP Start TLS	`true\|false`	To enable Starttls set the value to `true` (Default is `false`) See JS7 - LDAP over TLS (STARTTLS) and LDAP over SSL (LDAPS)
Host Name Verification	`true\|false`	Enables host name verification for the server certificate. The default value is `off.`
LDAP Truststore Path		Should the LDAP Server 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).

...

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

Name	ValueExample	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. Look up the `sAMAccountName` starting from the indicated hierarchy. This limits access to hierarchy levels. For login use `domain\account` or `account@domain` where `account` is The LDAP search expression makes use of the `uid` attribute. This is applicable if the account specified for login matches the value of the `sAMAccountName` attribute. `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.
	`cncn={0},ou=Users,dc=sos,dc=berlin,dc=com`	Use with Microsoft Active Directory® and other LDAP Servers. The Similar to the above example the Common Name `cn` attribute value of the account is used. This format requires the Common Name to be unique. For login use `domain\account` or `account@domain` where `account` is the value of the `sAMAccountName` attribute.
	`uid={0},dc=example,dc=com`	Use with This example can be used with a Public LDAP Server.For login use

Verify Authentication Settings

...

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 setting for the account is used and the uid value is replaced 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 of with a public LDAP Directory Service

The following example uses makes use of a publicly available LDAP Server. To our experience this server provides a good example to make an initial LDAP configuration work.

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

Try Users can try to login with an LDAP Accountaccount/Password password combination. Use an Account that you have verified to be correct An account should be used that has been verified by executing the ldapSearch command described above. If there are no Role(s) configured for the Account but the authentication works then you will see the following screen that complains about 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:

Anchor
authorization
authorization
Step 3: Authorization

...

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 with JOC Cockpit as authentication is performed with the LDAP Directory Service.

Anchor
assigning_roles_in_the_shiro.ini_file
assigning_roles_in_the_shiro.ini_file
Assign Roles with Identity Service Type LDAP-JOC

For details see JS7 - Manage Roles and Permissions.

Anchor
assigning_roles_from_ldap_groups
assigning_roles_from_ldap_groups

...

Anchor
grouprolesmapping
grouprolesmapping

...

Assign Roles with Identity Service Type LDAP

The group-JOC then you can skip this chapter.The group/roles mapping defines a search for LDAP groups and a 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 a the memberOf attribute. : In this case users can retrieve the list of groups with the User Search and should proceed with chapter Using memberOf with Approach 1: User Search and use of the memberOf Attribute.
The LDAP Server does not make use of a the memberOf attribute. : In this case the group contains the Accounts LDAP groups include the accounts that are members of the group. Users should proceed with chapter Using Approach 2: Group Search for account membership.

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.

...

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

...

LDAP Search Base

...

Example: ou=People,dc=sos

...

General

...

LDAP Search Base

...

Example: ou=People,dc=sos

...

Image Removed

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)

...

Image Removed

...

Image Removed

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:

...

Anchor
using_member_of_with_user_search
using_member_of_with_user_search
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.

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

For both LDAP User Search Filter and with LDAP User Search Filter 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 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 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.

Image Added

Anchor
groupsearch
groupsearch
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 Search Base and LDAP User Search Filter to look up the account.

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

Verify using an LDAP Browser

Expand

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:

Image Added

The group entry holds a distinguished name like this:

Image Added

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)

Image Added

Verify using ldapSearch

Expand

title	Verify Authorization Settings

Verify the LDAP Group Search Filter with the ldapSearch command

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

collapse	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=

Expand

title	Verify Authorization Settings

Verifing the groupSearchFilter with the ldapSearch command

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

This search should return the group entries the Account is a member of. Identify the attribute containing the group name that is to be used in the user roles mapping. This can be seen in the next listing

Code Block

collapse	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

Verifing the groupSearchBase and groupSearchFilter

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

Users can verify the groupSearchBase and groupSearchFilter attribute both attribute values by performing a directory searchan LDAP query. The result should display all groups the account is a member of.

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 .

...

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:

...

Anchor
substitution_of_the_username
substitution_of_the_username
User Search nested 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.

To achieve this, 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 name

Verify by use of ldapSearch

This search should return the Account LDAP query returns the account with the given Account account name. Identify the attribute that should , 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 base if it is not the Account name from the loginFilter.

Code Block

language	text
title	Username Substitution
collapse	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 -h localhost -p 389 -b "ou=People,dc=sos>sos" with-s scope subtree
# filter: sub "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

Verification by use of LDAP Browser

Users can perform a directory search with their LDAP Browser to check the User Search configuration. The result should present one account entry only.

Image Removed

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:

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

Image Added

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:

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.

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:

...

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

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

Examples and special configurations

...

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 17

New Version 18

Key

Add Identity Service

Verify Authentication Settings

Verify by use of LDAP Browser

Verify by use of ldapSearch

Verify by use of JOC Cockpit

AnchorauthorizationauthorizationStep 3: Authorization

Anchorassigning_roles_in_the_shiro.ini_fileassigning_roles_in_the_shiro.ini_fileAssign Roles with Identity Service Type LDAP-JOC

Anchorassigning_roles_from_ldap_groupsassigning_roles_from_ldap_groups

Anchorgrouprolesmappinggrouprolesmapping

Assign Roles with Identity Service Type LDAP

Substitution of the account value

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

Anchorusing_member_of_with_user_searchusing_member_of_with_user_searchApproach 1: User Search and use of the memberOf Attribute

Substitution of the account value

Verification

AnchorgroupsearchgroupsearchApproach 2: Group Search for account membership

Verify using an LDAP Browser

AnchorgroupsearchbasegroupsearchbaseLooking up the value for the LDAP Group Search Base

AnchorgroupsearchfiltergroupsearchfilterLooking up the value for the LDAP Group Search Filter

Verify using ldapSearch

Verify the LDAP Group Search Filter with the ldapSearch command

Verifing the groupSearchFilter with the ldapSearch command

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

Anchorsubstitution_of_the_usernamesubstitution_of_the_usernameUser Search nested in Group Search

Verification

Verify by use of ldapSearch

Verification by use of LDAP Browser

Group Roles Mapping

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

Verify by use of LDAP Browser

Group Roles Mapping

Examples

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

Example for Group Mapping with cn Attribute

In the JOC Cockpit Identity Service Settings the following group/roles mapping is specified:GroupRolessosit_operatorapl...administrator,application_...managerExplanation:..As Approach 2: Group Search for account membership is used the group's Common Name is specified....

Examples and special configurations

Anchor
authorization
authorization
Step 3: Authorization

Anchor
assigning_roles_in_the_shiro.ini_file
assigning_roles_in_the_shiro.ini_file
Assign Roles with Identity Service Type LDAP-JOC

Anchor
assigning_roles_from_ldap_groups
assigning_roles_from_ldap_groups

Anchor
grouprolesmapping
grouprolesmapping

Anchor
using_member_of_with_user_search
using_member_of_with_user_search
Approach 1: User Search and use of the memberOf Attribute

Anchor
groupsearch
groupsearch
Approach 2: Group Search for account membership

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
User Search nested in Group Search

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

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