Introduction

LDAP authentication for the JOC Cockpit is offered from the JS7 - LDAP Identity Service and relies on a connection between the JS7 - REST Web Service API and the LDAP Server.

...

This article describes the steps for configuration with an LDAP Directory Service:

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

Relevant Tools

• An 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.
• A command line utility:
  
  • The examples used in this article are executed with ldapSearch.

Proceeding

The following diagram provides an overview of the setup proceeding:

1 [label="1. Set up basic LDAP configuration\n(URL, etc.)"]
1 -> 2 [weight=5, len=0.5]
2 [label="2. Set up Authentication\n(userDnTemplate)"]
2 -> 3
3 [label="3. Set up Authorization\n/Roles, Assignments/Mappings"]
3 -> 4
4 [shape="diamond", label="Should roles be assigned from LDAP\nby security group memberships?",fillcolor="lightblue"]
4 -> 5 [label="Yes"]
5 [label="Define Group/Roles Mapping"]
4 -> 10 [label="No"]
10 [label="Create accounts and assign roles"]
10 -> E2
E2 [shape="circle", style="filled", label="End", color="pink"]
5 -> 6
6 [shape="diamond", label="Does the user account object include a\nmemberOf attribute?",fillcolor="lightblue"]
6 -> 20 [label="Yes"]
20 [label="Specify User Search\l - searchBase\l - userSearchFilter"]
20 -> E3
E3 [shape="circle", style="filled", label="End", color="pink"]
6 -> 7 [label="No"]
7 [label="Specify Group Search\l - groupSearchBase\l - groupSearchFilter\l - groupNameAttribute"]
7 -> 8
8 [shape="diamond", label="Does the member attribute contain\nthe account name from the login?",fillcolor="lightblue"]
8 -> E4 [label="Yes"]
E4 [shape="circle", style="filled", label="End", color="pink"]
8 -> 9 [label="No"]
9 [label="Specify User Search\l - searchBase\l - userSearchFilter"] 
9 -> E5
E5 [shape="circle", style="filled", label="End", color="pink"]

Anchor
basicldapconfiguration basicldapconfiguration

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 from the Identity Service.
• 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:

...

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

Specify General Settings 

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

Anchor
authentication authentication

Step 2: LDAP Authentication

Specify Authentication Settings

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

...

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:

...

From the properties of the resulting entry the setting for the account is used and the uid value is replaced 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:

...

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 to login with an LDAP Account/Password combination. Use an Account  that you have verified to be correct 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 missing authorization after successful authentication:

Image Added

Anchor
authorization authorization

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.

...

• LDAP: add a Group/Roles mapping: membership of a user account in a security group of the LDAP Server is mapped to a role 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.

Anchor
assigning_roles_in_the_shiro.ini_file assigning_roles_in_the_shiro.ini_file

Assign Roles with Identity Service

For details see JS7 - Manage Roles and Permissions.

Anchor
assigning_roles_from_ldap_groups assigning_roles_from_ldap_groups

Map Roles from LDAP Security Groups

If the Roles are assigned with the JOC Cockpit Account Management, i.e. there is a [users] section available in the shiro.ini configuration fileIdentity Service Management by using the Identity Serviced LDAP-JOC, then you can skip this chapter.

How substitutions will be done

In the groupSearchFilter and the userSearchFilter you can specify e.g. 

(uid=%s)

The %s will be substituted with the account from the login. If you login with domain\account oder account@domain the value for the user is account.

You can specify e.g.

(uid=^s)

The Group/Roles mapping

Settings: 

• ldapRealm.groupRolesMap

If the Roles are assigned with the JOC Cockpit Account Management, i.e. there is a [users] section available in the shiro.ini configuration file, then you can skip this chapter.

[main]
...
ldapRealm.groupRolesMap = \
  group1 : it_operator, \
  group2 : all

The groupRolesMap looks like this.

# Mapping of a LDAP group to roles. You can assign more than one role with separator character |

ldapRealm.groupRolesMap = \
group1 : list_of_roles, \
group2 : list_of_roles

where list_of_roles is a list of Roles that are configured in the [roles] section of the shiro.ini configuration file. Multiple Roles are separated with a bar |.

Note that the value of the group depends on the result of the group search. It is the value of the attribute that you have specified with the groupNameAttribute. Default for the groupNameAttribute is memberOf. This indicates that if you are retrieving group memberships by use of the memberOf attribute of an account then you have to specify the complete value of the memberOf attribute value, i.e. the distinguished names of group hits.

Example for Group Mapping with Microsoft Active Directory by memberOf Attribute

A typical mapping when using Microsoft Active Directory with the memberOf attribute for group memberships includes to specify group hts by their distinguished name like this:

ldapRealm.groupRolesMap = \
"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" : all, \
"CN=Beginners,OU=SecurityGroups,OU=Groups,OU=Company,DC=sos-berlin,DC=com" : business_user

Example for Group Mapping by cn Attribute

A mapping that is based on group search would identify group hits by the value of their common name like this:

ldapRealm.groupRolesMap = \
sos : it_operator, \
apl : administrator|application_manage

Retrieving the Groups an Account is a member of

If the Roles are assigned with the JOC Cockpit Account Management, i.e. there is a [users] section availab le in the shiro.ini configuration file, then you can skip this chapter.

There are two options to find the Group membership(s) for a User Account:

1. The Account has a memberOf attribute. Then you can retrieve the list of groups with the User Search. Then proceed with Using memberOf with User Search.
2. The Account does not have a memberOf attribute. The group contains the Accounts that are members of the group, Then proceed with Using Group Search.

These options cannot be mixed. 

...

If the Account entries do not have the memberOf attribute then you can skip this section and proceed with Using Group Search.

Settings: 

• ldapRealm.searchBase
• ldapRealm.userSearchFilter

After specifying the User Search the shiro.ini.active configuration file will look like this:

...

...

The group roles mapping defines a search for groups and a map that assigns these groups to a role.

The search for groups can be executed with one of these options

• The Account has a memberOf attribute. Then you can retrieve the list of groups with the User Search. Then proceed with Using memberOf with User Search.
• The Account does not have a memberOf attribute. The group contains the Accounts that are members of the group, Then proceed with Using Group Search.

These options cannot be mixed!

With the founded groups a map is defined, that maps the groups to roles.

In both searches the account can be substituted

How substitutions will be done

In the groupSearchFilter and the userSearchFilter you can specify %s e.g. 

(uid=%s)

The %s will be substituted with the account from the login. If you login with domain\account oder account@domain the value for the user is account.

You can specify ^s e.g.

(uid=^s)

The placeholder ^s will be substituted with the original value from the login e.g. account@domain.

Usersearch

This approach looks for the Account entry and reads the memberOf attribute. This attribute is often used when, for example, configuring Microsoft Active Directory^® LDAP servers. 

Define a userSearchFilter and a searchBase that will find the account .

Anchor
using_member_of_with_user_search using_member_of_with_user_search

 

Microsoft Active Directory^® that supports memberOff attribute

General

Groupsearch

Microsoft Active Directory^® that supports memberOff attribute

General

Group Roles Mapping

The mapping is defined in the expert tab of the LDAP Identity Service Manage Settings view.

Note that the value of the group depends on the result of the group search. It is the value of the attribute that you have specified with the groupNameAttribute. Default for the groupNameAttribute is memberOf. This indicates that if you are retrieving group memberships by use of the memberOf attribute of an account then you have to specify the complete value of the memberOf attribute value, i.e. the distinguished names of group hits.

Example for Group Mapping with Microsoft Active Directory by memberOf Attribute

A typical mapping when using Microsoft Active Directory with the memberOf attribute for group memberships includes to specify group hts by their 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 by cn Attribute

A mapping that is based on group search would identify group hits by the value of their common name like this:

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

Anchor
using_member_of_with_user_search using_member_of_with_user_search

a) Using memberOf with User Search

If the Account entries do not have the memberOf attribute then you can skip this section and proceed with Using Group Search.

Settings: 

• ldapRealm.searchBase
• ldapRealm.userSearchFilter

This approach looks for the Account entry and reads the memberOf attribute. This attribute is often used when, for example, configuring Microsoft Active Directory^® LDAP servers. 

Define a userSearchFilter and a searchBase that will find the account (%s will be replaced by the Account name from the login without the domain part).

Example for User Search

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

Example for User Search in Active Directory^®

• ldapRealm.searchBase = dc=example,dc=com
• ldapRealm.userSearchFilter = (sAMAccountName=%s)

...

b) Using Group Search 

If the Account entries have the memberOf attribute then you can skip this section and proceed with Using memberOf with User Search. Settings: 

• ldapRealm.groupSearchBase 
• ldapRealm.groupNameAttribute
• ldapRealm.groupSearchFilter

...

Getting the value for the groupSearchBase

Identify the location where the groups are stored. This is your groupSearchBase.

Getting the value for the groupSearchFilter

Click one group Entry (in the screenshot, cn=apl) and see how the members are stored there.

...

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

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

...

# 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 with an LDAP Browser

...

Hint: The complete content of this attribute must be used in the groupRolesMap attribute. Typical content of the attribute could be ou=Groups,dc=sos,cn=groupname .

Anchor
substitution_of_the_username substitution_of_the_username

Substitution of the account name

If the roles are assigned with the JOC Account Manager (i.e. there is a [users] section in the shiro.ini configuration file) 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 you have to search for the Account first and then specify the name of the attribute that should be used instead of the Account name from the login .

...

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

Verify by use of ldapSearch

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

Verification by use of LDAP Browser

Perform a directory search with your LDAP client to check the User Search configuration. You should find only one Account entry with the given Account name.

...

The configuration will look like this:

Examples and special configurations

Anchor
mixed-realms mixed-realms

Example LDAP Configuration with mixed LDAP and Shiro Authentication

Add the iniRealm to 

[users]
...
 
[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.userDnTemplate = uid={0},ou=People,dc=sos

ldapRealm.groupSearchBase = ou=Groups,dc=sos
ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389
ldapRealm.groupNameAttribute = cn
ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)
ldapRealm.groupRolesMap = \
group1: it_operator, \
group2: administrator|application_manager
 
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver

cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager

securityManager.realms = $ldapRealm, $iniRealm
 
# Session timeout in milliseconds
securityManager.sessionManager.globalSessionTimeout = 900000

Behavior Notes:

• By default roles from the shiro ini are added to the roles of an authenticated LDAP user with the same name. This happens regardless of whether or not a password is set for the account in the shiro ini file. However, a number of options can be configured to modify this behavior. These are described in the Multi-Realm Authentication and Authorization article.

Example LDAP Configuration for Active Directory with mixed LDAP and Shiro Authentication

Login with sAMAccountName specified for domain\account or account@domain:

...

[users]
# Locally authenticated users (specified with a hashed password)
root = $shiro1$SHA-512$500000$W0oNBkZY9LRrRIGyc4z2Ug==$NcoU+ZFM9vsM0MeHJ3P5NJ0NdvJrK38qVnl7v7YG7p9o5ZJfMccugJsA9myJsTNx2BF5rbvA696UhTGdUtSnOg==,all


# LDAP authenticated users (specified without a password)
COMPANY\homer = ,all
COMPANY\alice = ,all
 
[main]
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm


# Realm for Domain company.local
# -------------------------------
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://company.local:389


#    users can login with COMPANY\account and account@COMPANY.local where the account maps to the sAMAccountName
ldapRealm.userDnTemplate = {0}
ldapRealm.rolePermissionResolver = $rolePermissionResolver
# -------------------------------


# Authentication via domains ite.local, domain.local and via shiro.ini [users] section
securityManager.realms = $ldapRealm, $iniRealm


passwordMatcher = org.apache.shiro.authc.credential.PasswordMatcher
iniRealm.credentialsMatcher = $passwordMatcher


cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager


# Session timeout in milliseconds
securityManager.sessionManager.globalSessionTimeout = 1800000

Example LDAP Configuration with several LDAP Servers

LDAP configuration with several LDAP servers is achieved by defining more than one LDAP realm as shown in the next code block.

...

[main]
ldapRealm1 = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm1.userDnTemplate = uid={0},ou=People,dc=sos
ldapRealm1.groupSearchBase = ou=Groups,dc=sos
ldapRealm1.contextFactory.url = ldap://centos6_9_ldap.sos:389
ldapRealm1.groupNameAttribute = cn
ldapRealm1.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)
ldapRealm1.groupRolesMap = \
group1: it_operator, \
group2: administrator|application_manager

ldapRealm2 = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm2.userDnTemplate = uid={0},ou=People,dc=sos
ldapRealm2.groupSearchBase = ou=Groups,dc=sos
ldapRealm2.contextFactory.url = ldap://anotherHost:389
ldapRealm2.groupNameAttribute = cn
ldapRealm2.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)
ldapRealm2.groupRolesMap = \
group1: it_operator, \
group2: administrator|application_manager
 
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm1, $ldapRealm2

cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager

# Session timeout in milliseconds
securityManager.sessionManager.globalSessionTimeout = 900000

A full shiro.ini example with Group Search 

[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.userDnTemplate = uid={0},ou=People,dc=sos
ldapRealm.groupSearchBase = ou=Groups,dc=sos
ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389 
ldapRealm.groupNameAttribute = cn
ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)
ldapRealm.groupRolesMap = \
group1: it_operator, \
group2: administrator|application_manager

rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager

# Session timeout in milliseconds
securityManager.sessionManager.globalSessionTimeout = 900000

A full shiro.ini example with Group Search where the member attribute does not contain the account name but the common name

[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.userDnTemplate = uid={0},ou=People,dc=sos
ldapRealm.groupSearchBase = ou=Groups,dc=sos
ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389 
ldapRealm.groupNameAttribute = cn
ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)
ldapRealm.searchBase = ou=People,dc=sos
ldapRealm.userNameAttribute = cn
ldapRealm.userSearchFilter = (uniqueMember=uid=%s,dc=example,dc=com)
ldapRealm.groupRolesMap = \
group1: it_operator, \
group2: administrator|application_manager

rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager

# Session timeout in milliseconds
securityManager.sessionManager.globalSessionTimeout = 900000

A full shiro.ini example with memberOf in the account record

[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389 
ldapRealm.userDnTemplate = uid={0},ou=People,dc=sos
ldapRealm.searchBase = ou=People,dc=sos
ldapRealm.userSearchFilter = (uid=%s)
ldapRealm.groupRolesMap = \
group1: it_operator, \
group2: administrator|application_manager

rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager

# Session timeout in milliseconds
securityManager.sessionManager.globalSessionTimeout = 900000

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:

...

The LDAP group memberships will be mapped to the default Roles configured in the shiro.ini [roles] section as can be seen in lines 15-17 of the code listing above. This can be checked in the JOC Cockpit by looking at the Permissions section of the relevant User Profiles - the User Account gauss, for example, will have all permissions.

Logging

References

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

Use Cases

For debugging of LDAP Server connections

...