Introduction

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

• Early JS7 releases make use of of the JS7 - Shiro Identity Service, for migration see JS7 - Shiro Identity Service Migration.
• The connection to the an LDAP Server can be secured, see JS7 - LDAP over TLS (using STARTTLS ) and LDAP over SSL (using LDAPS).

This article describes explains the steps required for configuration with 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

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

Proceeding

The following diagram provides an overview of the setup proceedingsteps to set up LDAP connections:

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

...

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.
  
  

Image RemovedImage Added

Image Removed

x

LDAP is configured as part of the [main] section of a Shiro configuration file. As already mentioned above this information can be added to the JOC Cockpit either by adding it to a shiro.ini file or - in Version 1.12.1 and newer - by using the editor in the Main Section of the JOC Cockpit Manage Accounts view.

A Basic LDAP configuration in the [main] section will contain the following elements, with the ldapRealm.contextFactory.url being modified to suit the LDAP server being used:

[main]
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm

ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://myHost:389 
ldapRealm.rolePermissionResolver = $rolePermissionResolver

securityManager.realms = $ldapRealm

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

An Add LDAP realm function is available in the Main Section of the JOC Cockpit Manage Accounts view that adds the above Basic LDAP configuration in a single step. Both the button used to activate this function and the configuration items added can be seen in the screenshot below.

Image Removed

List of Basic LDAP Realm Items 

The following table lists the basic items used to configure an LDAP realm.

(See the Authentication and Authorization - Configuration article for more information about the shiro.ini file)

ldapReam

com.sos.auth.shiro.SOSLdapAuthorizingRealm

ldapRealm.contextFactory.url

ldap://host:port

ldapRealm.useStartTls

ldapRealm.hostNameVerification   

rolePermissionResolver  

com.sos.auth.shiro.SOSPermissionResolverAdapter

ldapRealm.rolePermissionResolver 

$rolePermissionResolver

securityManager.realms 

$ldapRealm [, $ldapRealm [, $iniRealm]]

In a simple configuration these items could appear as visible with the code block below (see also the example configuration for the public LDAP server listed in the below section):

...

2. LDAP Authentication

Settings: 

• ldapRealm.userDnTemplate

The userDnTemplate Setting

With authentication you will check for a valid account/password combination. To achieve this you have to specify the userDnTemplate. The parameters for the userDnTemplate can be taken from an account's properties page as displayed in the below screenshot taken from an LDAP browser.

Image Removed

The template setting for the account shown in the screenshot above would be (replacing the uid value with {0}):

• ldapRealm.userDnTemplate = uid={0},ou=People,dc=sos

This userDnTemplate item can be added to the Basic LDAP configuration using the Add Entry button of the Main Section editor as shown in the next screenshot:

Image Removed

Note that the '+' and 'x' symbols in the screenshot can be used to increase the number of entries added at once.

After setting up the Basic LDAP Configuration (described in 1. above) and adding the userDnTemplate the [main] section of the shiro.ini.active file will look like this:

[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://myHost:389 
ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos

rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm

Note that only one template can be specified per realm, separate realms have to be configured for different userDnTemplate settings.

Login with the sAMAccountName or CN

This works with a Microsoft Active Directory^® that supports domain login.

1. Change the userDnTemplate to ldapRealm.userDnTemplate = {0}
2. Add the User Search
3. Use domain\account or account@domain for the login where account is the value of the sAMAccountName attribute.

...

Account Names

The account name for a Microsoft Active Directory^® can have one of the following login patterns:

• sAMAccountName@domain
  • The sAMAccountName attribute is a unique identifier for an Account.
• domain\sAMAccountName
• cn
  • The Common Name attribute value of the Account is used.
  • This format requires the Common Name of an Account to be unique.

Note that LDAP Account names may contain blank spaces. See the Authorization section below for a description of how blank spaces are handled when LDAP authentication is used with Shiro authorization.

Configuration in the shiro.ini file

The [main] section of the shiro.ini file with authentication for the example "ur" account from the screenshot above is shown in the next code block:

Examples for the userDnTemplate: 

...

• Example Configurations with a Microsoft Active Directory^®:

• • ldapRealm.userDnTemplate = {0}
  • ldapRealm.userDnTemplate = cn={0},ou=Users,dc=sos,dc=berlin,dc=com


Verification with ldapSearch

You can check the value of the userDnTemplate by using it with a command for the ldapSearch utility such as:

• 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 a public LDAP Server

The following example uses a publicly available LDAP server at forumsys.com. In our experience this server provides a reliable means of getting an initial LDAP configuration up and working.

The command to check the userDnTemplate in the forumsys ldapSearch utility would be:

• ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -x

The server will return the following:

# 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: ldapSearch Parameters

The option -x is used in all the ldapSearch examples in this article. It is possible that your LDAP Directory Service does not allow this option and you have to specify an Account and a Password. If this is the case then the command would be:

• ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -W -D "uid=gauss,dc=example,dc=com"

Verification with an LDAP Browser

Search with the value from the userDnTemplate in the Search DN input field. The query should return only one entry.

Image Removed

Verification with the 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 Removed

Multi-Realm Authentication

Authentication can be configured for a multi-realm environment made up of one or more LDAP realms, with or without an ini realm. A simple multi-realm configuration is shown in the mixed LDAP and Shiro Authentication example below.

Note that the a user name can be configured for accounts in more than one realm. The behavior in such a situation (for example, should the roles configured for all realms be assigned to the account or only the roles configured for the realm used for the successful login?) is briefly described in the mixed LDAP and Shiro Authentication example below and in detail in the Multi-Realm Authentication and Authorization article.

...

3. Authorization

Authorization is the assignment of Roles to User Accounts. Roles, in turn, have permissions that are listed in the shiro.ini configuration file. An Account has all Permissions specified by the Roles that the Account is assigned.

There are two options for assigning Roles to Accounts:

1. First Option: with an LDAP Group to Shiro Role mapping
2. Second Option: with a Shiro User Account. 

...

Please decide:

1. If Roles are to be assigned in the shiro.ini file using the JOC Cockpit Account Management then the LDAP Groups the Account is a member of have no effect. Proceed with Assigning roles in the shiro.ini File
2. If Roles are to be assigned with the group roles mapping: The LDAP Groups the Account is a member of are assigned to JOC Cockpit roles. Proceed with Assigning Roles from LDAP Groups
3. If a mix of 1. and 2. is to be used: Proceed with Assigning roles in the shiro.ini File and then with Assigning Roles from LDAP Groups.

...

After assigning Roles in the shiro.ini file the [users] section of the file will look like this:

[users]
user1 = ,all
user2 = ,it_operator,administrator

[main]
 ...

Role assignment in the shiro.ini file is configured in the Manage Accounts view of the JOC Cockpit and is described in the Authentication and Authorization - Managing User Accounts article.

Note that a Password should not be entered for a User Account that is to be authenticated by an LDAP Directory Service. 

The following screenshot shows the allocation of one of the default roles:

Image Removed

The Roles assigned to an entry are saved in the [users] section of the shiro.ini configuration file according to the following syntax:

• account = ,list_of_roles

The list_of_roles is a comma separated list such as:

• it_operator,administrator

The JOC Cockpit Account Management can be used to add entries to the [users] section for Role assignment.

• Account names may include blank spaces if they are stored in an LDAP Directory Service. Account names stored in the shiro.ini configuration file may not contain blank spaces.
  
  • When a User Account with blank spaces in its name is configured using the JOC Cockpit's Manage Accounts view then every blank space in the name will be automatically replaced with %20 before the name is written to the shiro.ini file.
  • When a User Account with blank spaces in its name is added directly to the shiro.ini file then every blank space in the name should replaced with %20 before the name is written to the shiro.ini file.
  • Every occurrence of %20 in an User Account name saved in the shiro.ini file will be automatically converted to a blank space before this name is submitted to the LDAP server.
• Passwords may not be specified for Accounts with LDAP authentication when configuring such Accounts using the JOC Cockpit's Manage Accounts view .
• When a domain login is used then the reference has to contain the domain/account pattern e.g. domain\account or account@domain.

...

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.

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:

[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)
 
# Mapping of a LDAP group to roles. You can assign more than one role with separator sign |
ldapRealm.groupRolesMap = \
sos : it_operator, \
apl : administrator|application_manager
 
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm

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)

An LDAP Browser can be used to get the correct values for the searchBase and the userSearchFilter. Perform a directory search with the values. You should find only one entry. 

Image Removed

The searchBase is the value of the base DN (or ParentDN in the screenshot above).

Hint: if the attribute name in your environment is not the default memberOf then you can specify the name of the attribute with the groupNameAttribute key as described in the next section.

...

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

After defining the Group Search the shiro.ini configuration file will look like this:

[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.groupSearchBase = ou=Groups,dc=sos
ldapRealm.groupNameAttribute = cn
ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)

# Mapping of a LDAP group to roles. You can assign more than one role with separator sign |
ldapRealm.groupRolesMap = \
sos : it_operator, \
apl : administrator|application_manager

rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm

When the memberOf attribute is not available for the Account then you can use the Group Search.

Define the groupSearchBase and the groupSearchFilter. For example:

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

...

Getting the value for the groupSearchBase

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

Image Removed

Image Removed

Getting the value for the groupSearchFilter

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

Image Removed

The groupSearchFilter is configured with attr=val where attr is name of the attribute and val is the content. In this example, the attr is uniqueMember and the val uid=%s,ou=People,dc=sos, where the userid is replaced with %s. This results in:

• 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

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

# 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

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.

Anchor
authentication authentication

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"

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.

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.

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

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.

Verification

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 Group Search Base and LDAP Group Search Filter to look up groups:

Verification by LDAP Browser

Verifing the groupSearchBase and groupSearchFilter with an LDAP Browser

Image Removed

Now set the groupNameAttribute to the name of the attribute that contains the group name.

• ldapRealm.groupNameAttribute = cn

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 .

...

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.

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

To achieve this, specify a searchBase, a userSearchFilter and a userNameAttribute.

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

Verification with the ldapSearch command

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

This search should return the Account with the given Account name. Identify the attribute that should be used for substitution in the Group Search base if it is not the Account name from the login.

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

Image Removed

Then identify the name of the attribute that contains the value for substitution. For example:

• ldapRealm.userNameAttribute = cn

The configuration will look like this:

[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.userNameAttribute = cn
ldapRealm.userSearchFilter = (uid=%s)

ldapRealm.groupSearchBase = ou=Groups,dc=sos
ldapRealm.groupNameAttribute = cn
ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)

# Mapping of a LDAP group to roles. You can assign more than one role with separator sign |
ldapRealm.groupRolesMap = \
sos : it_operator, \
apl : administrator|application_manager

rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm

...

Settings

• cacheManager
• securityManager.cacheManager
• securityManager.sessionManager.globalSessionTimeout

After adding Shiro settings for the cache manager and the global session timeout the shiro.ini configuration file will look like this:

[main]
....
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager
securityManager.sessionManager.globalSessionTimeout = 900000

Examples and special configurations

...

Add the iniRealm to 

• securityManager.realms = $ldapRealm, $iniRealm

[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:

• ldapRealm.userDnTemplate = {0}

• Consider use of uppercase/lowercase spelling for domain and account

Add the ldapRealm and iniRealm like this: 

• securityManager.realms = $ldapRealm, $iniRealm

Add domain\account to the [users] section. Assign roles but omit passwords for LDAP authenticated users like this: 

• COMPANY\account = ,role [,role]

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

Define two realms and assign them like this:

• securityManager.realms = $ldapRealm1, $ldapRealm2

A full shiro.ini example with Group Search 

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

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

# 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

Anchor
substitution_of_the_username substitution_of_the_username

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

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

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:

To implement the authentication configuration - or realm - for accessing this public LDAP server, add the following lines to the [main] section of the shiro.ini file:

publicLdapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm

publicLdapRealm.userDnTemplate = uid={0},dc=example,dc=com
publicLdapRealm.searchBase = dc=example,dc=com
publicLdapRealm.contextFactory.url = ldap://ldap.forumsys.com:389

publicLdapRealm.groupNameAttribute = ou
publicLdapRealm.userNameAttribute = uid

publicLdapRealm.rolePermissionResolver = $rolePermissionResolver
publicLdapRealm.userSearchFilter = (uniqueMember=uid=%s,dc=example,dc=com)
publicLdapRealm.groupRolesMap = \
  scientists : it_operator, \
  mathematicians: all

rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm

securityManager.realms = $publicLdapRealm, $iniRealm
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager

Save the modified shiro.ini file. (It is not required to restart the Jetty web server.)

You will now be able to use JOC Cockpit to authenticate the two User Account name:password combinations listed in the table above with the LDAP server.

The Shiro authentication (using, for example, the default root:root User Account) will still be active alongside the LDAP accounts listed above.

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.

Troubleshooting

Enable logging

To enable logging:

• Open the file ./sos-berlin.com/joc/jetty_base/resources/joc/log4j2.xml
• Enable the AuthAppender by uncommenting

<!-- logger for authentication and session management -->
<Logger name="com.sos.auth" level="trace" additivity="false">
<AppenderRef ref="AuthAppender"/>
</Logger>


Log File location

The log file is located  in:

• "${sys:jetty.base}/logs/JOCShiroLog.log