Page History
Table of Contents |
---|
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:
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"] |
Anchor | ||||
---|---|---|---|---|
|
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.
Name | Value | Description |
---|---|---|
LDAP Server URL |
| The host and the port of the LDAP Server. |
LDAP Start TLS | true|false | To enable 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 |
Anchor | ||||
---|---|---|---|---|
|
Specify Authentication Settings
The following table lists possible values for authentication with an LDAP Server:
...
Name | Value | Description |
---|---|---|
LDAP User DN Template |
| 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 | |
cn={0},ou=Users,dc=sos,dc=berlin,dc=com | Use with Microsoft Active Directory® and other LDAP Servers. The Common Name For login use | |
uid={0},dc=example,dc=com | Use with Public LDAP Server. For login use |
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:
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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:
Anchor | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
|
For details see JS7 - Manage Roles and Permissions.
Anchor | ||||
---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
...
- 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!
...
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.
...
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 | ||||
---|---|---|---|---|
|
Microsoft Active Directory® that supports memberOff attribute
...
Name | Value | Description |
---|---|---|
LDAP Search Base |
| The search base for the ldap search |
LDAP User Search Filter | Example: (uid=%s) |
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:
...
Anchor | ||||
---|---|---|---|---|
|
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
...
Anchor | ||||
---|---|---|---|---|
|
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
...
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....
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 | ||||
---|---|---|---|---|
|
If the roles are assigned with the JOC Account Manager using the Identity Service LDAP-JOC 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
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 |
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
userDnTemplate | groupSearchBase | groupNameAttribute | groupSearchFilter | searchBase | userNameAttribute | userSearchFilter | |
---|---|---|---|---|---|---|---|
Group Search | uid={0},ou=People,dc=sos | ou=Groups,dc=sos | cn | (uniqueMember=uid=%s,ou=People,dc=sos) | |||
Group Search where the member attribute does not contain the account name but the common name | uid={0},ou=People,dc=sos | ou=Groups,dc=sos | cn | (uniqueMember=uid=%s,ou=People,dc=sos) | ou=People,dc=sos | cn | (uniqueMember=uid=%s,dc=example,dc=com) |
memberOf in the account record | uid={0},ou=People,dc=sos | ou=People,dc=sos | (uid=%s) | ||||
public LDAP Server | uid={0},dc=example,dc=com | ou | dc=example,dc=com | uid | (uniqueMember=uid=%s,dc=example,dc=com) |
A public LDAP Server for testing the connection
An online public LDAP server which can be accessed using a relatively simple configuration is available from Forum Systems. This server can be used to set up a test environment with LDAP authentication. In this article we will refer to the authentication of two user accounts on this server - gauss and newton - that are each members of a different LDAP group as shown in the following table:
Account Name | Password | LDAP Group | Shiro Role |
---|---|---|---|
gauss | password | mathematicians | all |
newton | password | scientists | it_operator |
Logging
References
Use Cases
For debugging of LDAP Server connections
...