Page History
...
- Early JS7 releases make use of the JS7 - Shiro Identity Service, for migration see JS7 - Shiro Identity Service Migration.
- The connection to an LDAP Server can be secured, see JS7 - LDAP over TLS (using STARTTLS ) and LDAP over SSL (using LDAPS).
This article explains the steps required for configuration 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 attributes to to search for groups
Relevant Tools
- LDAP Browser:
- The screenshots used in this article indicate the Softerra® LDAP Browser that was used to connect to the relevant LDAP Directory Service.
- Command Line Client:
- The examples used in this article are executed with ldapSearch.
...
Proceeding
The following diagram provides an overview of the steps to set up LDAP connections:
...
- Simple Mode: The most frequently used settings are available.
- Expert Mode:: The full set of settings is available.
Specify General Settings
Find detailed explanations about general settings from 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 protcolprotocol, 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 See JS7 - LDAP over TLS (using STARTTLS ) and LDAP over SSL (using LDAPS) |
Host Name Verification | trueon|falseoff | Enables host name verification for the server certificate. The default value is off. |
LDAP Truststore Path | Should 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 |
...
The following table lists possible values for authentication with an LDAP Server. The value {0}
will be substituted with the account name.
Name | Example | 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. The LDAP search expression makes use of the The specification of an organizational unit and domain context limits access to hierarchy levels. | |
cn={0},ou=Users,dc=sos,dc=berlin,dc=com | Use with Microsoft Active Directory® and other LDAP Servers. Similar to the example above example , the Common Name | |
uid={0},dc=example,dc=com | This example can be used with a Public LDAP Server. |
...
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 screenshot displays such properties from an LDAP Browser: In a first step search with the value from the LDAP User DN Template in the Search DN input field. The query should return only one entry. From the properties of the resulting entry the 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 use of using the ldapSearch utility:
Example for use with a public LDAP Directory Service The following example makes use of a publicly available LDAP Server.
Note: The option
Verify by use of JOC CockpitUsers 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 no roles be have not been assigned for the account then users will find the following empty page that indicates missing authorization after successful authentication: |
...
LDAP
: add a Group/Roles mapping. Membership of a user account in security groups of the LDAP Server is mapped to roles in the Identity Service.LDAP-JOC
: add a user account and assign roles with JOC Cockpit. Accounts are managed with the Identity Service in parallel to the LDAP Server. No user passwords are managed with by the JOC Cockpit as authentication is performed with by the LDAP Directory Service.
...
- The LDAP Server makes use the memberOf attribute: In this case users can retrieve the list of groups and should proceed with chapter 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 chapter the Approach 2: Group Search for account membership section of this page.
Anchor | ||||
---|---|---|---|---|
|
...
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: |
Substitution of the account value
...
Verification
Expand | ||
---|---|---|
| ||
An LDAP Browser can be used to identify matching values for the LDAP Search Base and LDAP User Search Filter |
...
- In the
groupSearchFilter
and in theuserSearchFilter
users can specify the placeholder%s
, for example:(uid=%s)
- The placeholder
%s
will be substituted with the account from the login without the domain part, for exampleaccount
ifaccount@domain
is used.
- The placeholder
- Users can specify the placeholder
^s
, for example:(uid=^s)
- The placeholder
^s
will be substituted with the account from the login including the domain part, for exampleaccount@domain
.
- The placeholder
Verification
...
title | Verification |
---|
An LDAP Browser can be used to identify matching values for the LDAP Search Base and LDAP User Search Filter. Users can perform an LDAP query with the attributes that match their LDAP Server. The query has to identify a unique account
...
...
This approach looks up groups in the LDAP Server that the account is a member of.
Users define the LDAP Search Base and LDAP User Search Filter to look up the account.
...
LDAP Group Search Base
...
ou=Groups,dc=sos
...
The specification of an organizational unit and domain context is used to limit access to hierarchy levels.
...
The LDAP Group Search Filter is applied to identify groups within the hierarchy of the LDAP Group Search Base that the authenticated account is a member of.
The LDAP Group Search Filter make use of an attribute that is specific for the LDAP Server product.
The example makes use of the uniqueMember
attribute that specifies the uid
attribute to identify the authenticated user account. Other attributes can be used. However, the LDAP query has to identify a unique account.
Users can specify placeholders with the LDAP Group Search Filter:
- Placeholder
%s
, for example:(uid=%s)
- The placeholder
%s
will be substituted with the account from the login without the domain part, for exampleaccount
ifaccount@domain
is used.
- The placeholder
- Placeholder
^s
, for example:(uid=^s)
- The placeholder
^s
will be substituted with the account from the login including the domain part, for exampleaccount@domain
.
- The placeholder
...
The name of the attribute that identifies the group that results from an LDAP query using LDAP Group Search Base and LDAP Group Search Filter.
The value of this attribute is used for the groups/roles mapping.
- If the
dn
attribute is used then the group/roles mapping specifies the group including its hierarchy levels. - If the
cn
attribute is used then the group/roles mapping specifies the group name without its hierarchy levels.
Default: cn
. 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 using an LDAP Browser
...
...
...
Users can identify the LDAP Group Search Filter in their LDAP Server by navigating to the respective groups by use of their LDAP browser:
In this example, the attribute is uniqueMember
and the value is uid=%s,ou=People,dc=sos
.
...
Verify using ldapSearch
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
Verify the LDAP Group Search Filter with the ldapSearch command ldapsearch -h localhost -p 389 -b "ou=Groups,dc=sos" -s sub "
This search returns the groups that the account is a member of. Users should identify the value of the LDAP Group Name Attribute attribute in the output of the example. If the LDAP Group Name Attributedn is used then from the first result the value
cn is used then from the first result the value sos has to be applied for group/roles mapping.
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 | ||||
---|---|---|---|---|
|
...
in Group Search
Consider a situation from the above example:
...
For example, if the uid
attribute holds the value of the cn
attribute then users have to search for the account
first and then specify the name of the attribute that holds the value for the substitution.
To achieve this, the The following settings have to be specified:
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) |
Verification
Expand | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
Verify 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:
...
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
Explanation:
- As Approach 1: User Search and use of the memberOf Attribute is used then distinguished names of groups have to be specified.
...
Attribute
In the JOC Cockpit Identity Service Settings the following group/roles mapping is specified:
...
Explanation:..
- As Approach 2: Group Search for account membership is used the group's Common Name is specified.
Examples and special configurations
...
Group Search
...
Group Search where the member attribute does not contain the account name but the common name
...
memberOf in the account record
...
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
...
public LDAP Server
...
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:
...
Password LDAP Group Role gauss password mathematicians all
newton password scientists
...
application_
...
manager
Logging
References
...
- 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.