Page History
Table of Contents |
---|
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 rolesDefine groupRolesMapping
- Define group/roles mapping
- Define the LDAP attribute 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.
...
The following diagram provides an overview of the setup proceedingsteps to set up LDAP connections:
Flowchart |
---|
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"] |
...
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.
...
- Simple Mode: The most frequently used settings are available.
- Expert Mode:: The full set of settings is available.
Specify General Settings
See the JS7 - LDAP Identity Service, chapter: Identity Service Settings for detailed explanations about the general settings.
The following table lists the general items used to configure an LDAP connection.
Name | Value | Description |
---|---|---|
LDAP Server URL |
| The protocol, host and the port of the LDAP Server. |
LDAP Start TLS true|false | Checkbox checked or unchecked | To enable Starttls StartTls set the value to Please note that the server must be prepared to serve with StartTls. To check this, you can use an LDAP browser. Configure your LDAP Server there and click the "Enable Starttls Button" On client side you will need the certificate and you have to add the certificate to your truststore. The path to your truststore is defined in the
Example values:
Note: we habe had difficulties when using Starttls with the JRE 1.8.0_151 and have overcome these by installing the corresponding JDK. |
Host Name Verification | true|false | Enables the host name verification of the certificate. The default value is off. | LDAP Truststore Path | LDAP Truststore Password | LDAP Truststore Type |
See JS7 - LDAP over TLS using STARTTLS and LDAP over SSL using LDAPS | ||
Host Name Verification | on|off | Enables host name verification for the server certificate. The default value is off. |
LDAP Truststore Path | If the LDAP Server is to be configured for TLS/SSL protocols then the indicated truststore has to include an X.509 certificate specified for the Extended Key Usage of Server Authentication. | |
LDAP Truststore Password | If an LDAP truststore is used and the LDAP truststore is protected by a password, then the password has to be specified. | |
LDAP Truststore Type | If an LDAP truststore is used then the type of the indicated truststore has to be specified being either |
Anchor | |||
---|---|---|---|
Anchor | |||
|
...
The following table lists possible values for authentication with an LDAP Server:. The value {0}
will be substituted with the account name.
Name | ValueExample | Description |
---|---|---|
LDAP User DN Template |
| Should This should work from scratch for Microsoft Active Directory®. For login use |
uid={0},ou=People,dc=sos | Use with Microsoft Active Directory® and other LDAP Servers. Look up the For login use 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 example above, the Common Name | |
uid={0},dc=example,dc=com | Use with This example can be used with a Public LDAP Server. For login use |
...
Verification
Expand | ||
---|---|---|
| ||
Verify by use of LDAP BrowserPossible values for the LDAP User DN Template can be derived from an account's properties. The screenshot below |
...
displays such properties from an LDAP Browser: In a first step search with the value from the LDAP User DN Template in the Search DN input field. The query should return only one entry. From the properties of the resulting entry the |
...
value for the LDAP User DN Template can be extracted. Users should replace the Verify by use of ldapSearchUsers can check the value of the LDAP User DN Template setting by |
...
using the ldapSearch utility:
| truecollapse |
Example for use |
---|
...
with a public LDAP Directory Service The following example |
...
makes use of a publicly available LDAP Server |
...
.
| true | collapse
Note: The option |
...
will look like this:
Verify by use of JOC Cockpit |
...
Users can try to login with an LDAP |
...
account/ |
...
password combination. |
...
An account should be used that has been verified by executing the ldapSearch command described above. |
...
Should authentication be successful but roles have not been assigned for the account then users will find the following empty page that indicates missing authorization after successful authentication: |
Anchor | ||||
---|---|---|---|---|
|
...
LDAP
: add a Group/Roles mapping: membership . Membership of a user account in a security group groups of the LDAP Server is mapped to a role 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 by the JOC Cockpit as authentication is performed with by the LDAP Directory Service.
Anchor | ||||
---|---|---|---|---|
|
For details see JS7 - Manage Roles and Permissions.
Anchor | ||||
---|---|---|---|---|
|
...
Anchor | ||||
---|---|---|---|---|
|
...
Assign Roles
...
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 placeholder ^s
will be substituted with the original value from the login e.g. account@domain.
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.
shiro.ini
configuration file. This is done in the a [main]
section with the groupRolesMap
setting.shiro ini
file will look like this:Code Block | ||
---|---|---|
| ||
[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:
- 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.
...
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:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[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.
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:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
[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
.
Getting the value for the groupSearchFilter
Click one group Entry (in the screenshot, cn=apl
) and see how the members are stored there.
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
Code Block | ||
---|---|---|
| ||
# 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
groupSearchBase
and groupSearchFilter
values by using them to perform a directory search. The result should show all groups the account is a member of.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)
Verify by use of ldapSearch
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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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
|
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 | ||||
---|---|---|---|---|
|
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 |
| 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 Users can specify placeholders with the LDAP User Search Filter:
Default: |
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: |
Verification
Expand | ||
---|---|---|
| ||
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. |
Anchor | ||||
---|---|---|---|---|
|
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:
Name | Required | Example | Description |
---|---|---|---|
LDAP Group Search Base | yes |
| 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 Users can specify placeholders with the LDAP Group Search Filter:
|
LDAP Group Name Attribute | no | dn | The name of the attribute that identifies the group which results from an LDAP query using LDAP Group Search Base and LDAP Group Search Filter. The value of this attribute is used for the groups/roles mapping.
Default: |
Verification by LDAP Browser
Expand | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
Users can identify the LDAP Group Search Base in their LDAP Server by navigating to the relevant groups using their LDAP browser: The group entry holds a distinguished name like this:
Users can identify the LDAP Group Search Filter in their LDAP Server by navigating to the relevant groups using their LDAP browser: In this example the attribute is As a result the following LDAP Group Search Filter is used: |
Verification by ldapSearch
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
Verify the LDAP Group Search Filter with the ldapSearch Utility 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.
Verify the LDAP Group Search Base and LDAP Group Search Filter with an LDAP BrowserUsers can verify both attribute values by performing an LDAP query. The result should display all groups the account is a member of. |
Anchor | ||||
---|---|---|---|---|
|
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 theaccount
fromaccount@domain
used for login. This example makes use ofur
. - If the
uid
attribute does not make use of the user'saccount
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 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.
Then identify the name of the attribute that contains the value for substitution. For example:
ldapRealm.userNameAttribute = cn
The configuration will look like this:
Examples and special configurations
...
Add the iniRealm to
securityManager.realms = $ldapRealm, $iniRealm
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[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]
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[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
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[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
...
language | text |
---|---|
title | Configuration when the member attribute contains cn |
linenumbers | true |
collapse | true |
...
Name | Required | Example | Description |
---|---|---|---|
LDAP Search Base | yes |
| 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) |
...
A full shiro.ini example with memberOf in the account record
...
language | text |
---|---|
title | Configuration with memberOf in the user record |
linenumbers | true |
collapse | true |
...
Verification
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
Verify by use of ldapSearchThis LDAP query returns the account with the given account name, for example fTester. Users have to identify the attribute that holds the value that is expected from the
|
...
Verify by use of LDAP BrowserUsers can use their LDAP Browser to test the LDAP query that identifies the user account. The result should return a single account. |
Group Roles Mapping
The mapping is configured with the "Expert Mode" of the LDAP Identity Service Settings.
Examples
Group/roles Mapping with Approach 1: User Search and use of the memberOf Attribute
In the JOC Cockpit Identity Service Settings the following group/roles mapping is specified:
Group | Roles |
---|---|
CN=Group1,OU=SpecialGroups,OU=Groups,OU=Company,DC=sos-berlin,DC=com | all |
CN=AnotherGroup,OU=SpecialGroups,OU=Groups,OU=CompanyDC=sos-berlin,DC=com | adminitrator |
CN=Beginners,OU=SecurityGroups,OU=Groups,OU=Company,DC=sos-berlin,DC=com | business_user |
Explanation:
- As Approach 1: User Search and use of the memberOf Attribute is used then distinguished names of groups have to be specified.
Group/roles Mapping with Approach 2: Group Search for account membership
In the JOC Cockpit Identity Service Settings the following group/roles mapping is specified, for example when using the cn
attribute for group names:
Group | Roles |
---|---|
sos | it_operator |
apl | administrator,application_manager |
Explanation:
- As Approach 2: Group Search for account membership is used the group's Common Name is specified.
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 theall
role which allows access to any operation in JOC Cockpit.newton
: the user account is assigned theapplication_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.
- The popup window to manage LDAP Server settings offers an Upload button to import downloaded settings.
Both accounts gauss and newton make use of the same password:
User Account Password LDAP Group Role gauss password mathematicians all
newton password scientists application_manager
Logging
A public LDAP Server for testing the connection
An online public LDAP server which can be accessed using a relatively simple configuration is available from Forum Systems. This server can be used to set up a test environment with LDAP authentication. In this article we will refer to the authentication of two user accounts on this server - gauss and newton - that are each members of a different LDAP group as shown in the following table:
Account Name | Password | LDAP Group | Shiro Role |
---|---|---|---|
gauss | password | mathematicians | all |
newton | password | scientists | it_operator |
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Logging
...
Use Cases
- 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.