This article describes the configuration of the JOC Cockpit to use an LDAP Directory Service for authentication and authorization that is performed with Apache Shiro. The authoritative documentation of Shiro is provided by the Shiro project and may differ from the below explanations depending on the Shiro version in use.

This configuration is done in the JOC Cockpit's shiro.ini file whose overall configuration is described in the Authentication and Authorization - Configuration article. A general introduction to authentication and authorization in the with JOC Cockpit is provided with the JOC Cockpit - Authentication and Authorization article.

After changing the shiro.ini configuration file either by using the JOC Cockpit Account Manager or a text editor, no restart of JOC Cockpit is required.

Relevant Tools

An LDAP Browser:
- The screenshots shown used in this article were are made with for the "Softerra LDAP Browser" that had been is configured to use the relevant LDAP serverDirectory Service.
A command line utility:
- The example commands shown were used are executed with ldapSearch

How to set up an LDAP configuration

...

Set up the basic LDAP configuration
Set up the authentication
Set up the authorization
- Defining the groupRolesMapping (optional)
- Defining the Roles per user account in the [users] section (optional)
- Defining the search for groups
Add Shiro settings

...

Flowchart

1 [label="1. Set up basic LDAP config\n(URL, etc)"]
1 -> 2 [weight=5, len=0.5]
2 [label="2. Set up the authentication\n(userDnTemplate)"]
2 -> 3
3 [label="3. Set up the authorization"]
3 -> 4
4 [shape="diamond", label="Are roles to be assigned \nwith groups from LDAP?",fillcolor="lightblue"]
4 -> 5 [label="Yes"]
5 [label="Define GroupRoles mapping"]
4 -> 10 [label="No"]
10 [label="Use Shiro to assign roles to usersaccounts"]
10 -> E2
E2 [shape="circle", label="", color="pink"]
5 -> 6
6 [shape="diamond", label="Has useraccount record a\nmemberOf attribute?",fillcolor="lightblue"]
6 -> 20 [label="Yes"]
20 [label="Specify User Search\l - searchBase\l - userSearchFilter"]
20 -> E3
E3 [shape="circle", label="", color="pink"]
6 -> 7 [label="No"]
7 [label="Specify Group Search\l - groupSearchBase\l - groupSearchFilter\l - groupNameAttribute"]
7 -> 8
8 [shape="diamond", label="Does member attribute contain\nusernamenaccount name from login?",fillcolor="lightblue"]
8 -> E4 [label="Yes"]
E4 [shape="circle", style="filled", label="", color="pink"]
8 -> 9 [label="No"]
9 [label="Specify User Search\l - searchBase\l - userSearchFilter"] 
9 -> E5
E5 [shape="circle", label="", color="pink"]

...

After setting up the Basic LDAP Configuration your [main] section looks like this:

Code Block

language	text
title	A basic LDAP configuration

[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://myHost:389 
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm

...

Key	Value	Description
ldapReam	com.sos.auth.shiro.SOSLdapAuthorizingRealm	The key is the name of the realm. You can define any name. The name is taken as a reference to set the properties of the realm. The value is the name of the class that implements the realm. The implementation from SOS extends `org.apache.shiro.realm.ldap.JndiLdapRealm` Please note that you can have more than one LDAP configuration.
ldapRealm.contextFactory.url	ldap://host:port	The host and the port of your LDAP server. You can check whether the server is reachable with `telnet host port` Make sure that the firewall is open for the given port.
ldapRealm.useStartTls	`true\|false`	To enable Starttls set the value to `true` (Default is `false`) Please note that the server must be prepared to serve with Starttls. To check this, you can use an LDAP browser such as the "Softerra 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 `joc.properties` configuration file. `truststore_path = path to your truststore.` Example values: `C:/Program Files/Java/jdk1.8.0_131/jre/lib/security/cacerts` or `../../etc/joc.jks` Note: we have had faced difficulties when using Starttls with the JRE1JRE 1.8.0_151 and have overcome these by installing a the respective JDK.
ldapRealm.hostNameVerification	`on\|off true\|false`	To enable Enables the host name verification of the certificate. The default value is `off.`
rolePermissionResolver	com.sos.auth.shiro.SOSPermissionResolverAdapter	The implementation of the permission resolver. The SOS implementation sets an uses the `org.apache.shiro.realm.text.IniRealm` class to resolve the permissions. That This means that the permissions a role is assigned are specified with the configuration file `shiro.ini` in the same way as it is done when using the `iniRealm`.
ldapRealm.rolePermissionResolver	$rolePermissionResolver	Sets the role permission resolver for the LDAP realm.
securityManager.realms	$ldapRealm [, $ldapRealm [, $iniRealm]]	Sets the list of realms that should be used for authentication. This is a comma separated list of items. Example values: `$ldapRealm` --> Only one realm is specified. `$ldapRealm, $iniRealm` --> You can login with an account from the LDAP Directory Service or with an account specified in the `[users]` section in the configuration file shiro.ini. `$ldapRealm1, $ldapRealm2` --> You can login with an account available from the LDAP Directory Service specified with the `$ldapRealm1` realm or with the `$ldapRealm2` realm.

...

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 a from an account's properties page as shown displayed in the below screenshot from an LDAP browser below.

For the account in the screenshot the template would be (replacing the uid value with {0}):

...

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

Change the userDnTemplate to ldapRealm.userDnTemplate = uid={0}
Add the userSearch
Use domain\account or account@domain for the login where account is the value of the sAMAcountName attribute.

Anchor

	username
	username

Account Names

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

sAMAccountName@domain
- the The sAMAccountName attribute is a unique identifier for an account.
domain\sAMAccountName
cn
- the The Common Name attribute of the account is used.
- this 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.

...

Example Configuration with a Microsoft Active Directory^®:

- adLdapRealm.userDnTemplate = cn={0},ou=Users,dc=sos,dc=berlin,dc=com

...

Code Block

language	text
title	Result: ldapsearch -h localhost -p 389 -b "uid=ur,ou=People, dc=sos" -x
linenumbers	true
collapse	true

# 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

For this server the command to check the userDnTemplate in the ldapSearch utility would be:

...

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
	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 the sum of all the Permissions coming from specified by the Roles they have been that the Account is assigned.

There are two options for assigning Roles to Accounts:

...

If Roles are to be assigned in the shiro.ini file using the JOC Account Management: The LDAP Groups the account Account is a member of have no effect. Proceed with Assigning roles in the shiro.ini File
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
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:

Code Block

language	text
title	LDAP Authentication and shiri.ini Authoriziation
linenumbers	true
collapse	true

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

[main]
 ...

...

Anchor

	grouprolesmapping
	grouprolesmapping

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

The

...

Group/Roles mapping

Settings:

ldapRealm.groupRolesMap

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

When assigning roles Roles from LDAP Groups an account is a member of then the groups will be mapped to the Roles that are defined in the shiro.ini configuration file. This is done with the groupRolesMap setting.

After specifying the group roles Group/Roles mapping your shiro ini file will look like this:

Code Block

collapse	true

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

...

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 search. It is the value of the attribute that you have specified in with the groupNameAttribute.

Example

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

Getting the Groups

...

an Account is a member of

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

...

This approach looks for the account entry and then 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)

...

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 = (sAMAcountName=%s)

...

Space shortcuts

Page tree

Versions Compared

Old Version 58

New Version 59

Key

Relevant Tools

How to set up an LDAP configuration

Account Names

Example for

a public LDAP server

The

Group/Roles mapping

Example

Getting the Groups

an Account is a member of

Example for user search in Active Directory^®

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 58

New Version 59

Key

Relevant Tools

How to set up an LDAP configuration

Account Names

Example for

a public LDAP server

The

Group/Roles mapping

Example

Getting the Groups

an Account is a member of

Example for user search in Active Directory®

Example for user search in Active Directory^®