Skip to end of metadata
Go to start of metadata

Introduction

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. Note that the authoritative documentation of Shiro is provided by the Shiro project and may differ from the descriptions below depending on the Shiro version in use.

Release 1.12.0

FEATURE AVAILABILITY ENDING WITH RELEASE 1.12

LDAP configuration information is stored in the [main] section of 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 with JOC Cockpit is provided with the JOC Cockpit - Authentication and Authorization article.

LDAP configuration can only be edited by system administrators using a text editor to update the shiro.ini file. There is no web-based editing feature available.

A restart of JOC Cockpit is not required after changes are made to the shiro.ini configuration file.

Release 1.12.1 and Newer

Three changes relevant to the configuration of LDAP authentication and authorization are introduced with Release 1.12.1:

  • All authentication and authorization information is stored in the Reporting database.
  • A form based editor which users can use to configure LDAP authentication is available in the JOC Cockpit. This editor is only available for users with the necessary permissions such as the default root user with the all role. The editor is accessed via the "Manage Accounts" menu.
  • Automatic import and backup functions for the authentication and authorization information are available. Both the import and backup functions use Shiro files and their execution is triggered by a user logging into JOC Cockpit interface.
    • The import function automatically imports a file named shiro.ini to the Reporting database and the contents of this file will overwrite all the authentication and authorization information stored in the Reporting database at that point.
    • The backup function automatically stores the authentication and authorization information in a file named shiro.ini.active. At the same time an existing shiro.ini.active file will be renamed shiro.ini.backup and any already existing file with that name will be overwritten.

The shiro.ini.active file provides a convenient overview of the authentication and authorization configuration and will be referred to repeatedly in the rest of this article.

Relevant Tools

  • An LDAP Browser:
    • The screenshots used in this article were made with the "Softerra LDAP Browser", which was configured to use the relevant LDAP Directory Service.
  • A command line utility:
    • The example commands used were executed with ldapSearch.

How to set up an LDAP Configuration

Carry out the following steps:

  1. Set up the Basic LDAP configuration
  2. Set up the authentication
  3. Set up the authorization
  4. Add Shiro settings

The Setup Procedure

The following diagram provides an overview of the setup procedure:

1. Basic LDAP Configuration

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:

Basic LDAP configuration

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.

Important

Icon

Note that the securityManager.realms = $ldapRealm element as added and shown above does not make provision for logging in via the iniRealm - i.e. using a "locally" configured account specified in the Shiro [users] section such as root. This means that once any current local user has either logged out or been timed out, the JOC Cockpit interface will remain blocked until the LDAP configuration has been completed or provision for the iniRealm is added.

Administrators wishing to use a local user while configuring LDAP are therefore recommended to modify the securityManager element immediately to:

securityManager.realms = $ldapRealm, $iniRealm

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)

KeyValueDescription
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 realm configuration but each realm requires a unique name.

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

See Documentation LDAP With SSL

Note:

we habe had difficulties when using Starttls with the JRE 1.8.0_151 and have overcome these by installing the corresponding JDK.

ldapRealm.hostNameVerification   
on|off true|falseEnables 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 uses the  org.apache.shiro.realm.text.IniRealm class to resolve the permissions. 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.

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.

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:

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:

userDnTemplate configuration  Expand source

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

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 Configuration for an arbitrary hierarchy:
    • ldapRealm.userDnTemplate = uid={0},ou=People,dc=sos

  • Example Configuration for the public LDAP Server mentioned in this article:
    • ldapRealm.userDnTemplate = uid={0},dc=example,dc=com

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

Result: ldapsearch -h localhost -p 389 -b "uid=ur,ou=People, dc=sos" -x  Expand source

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:

The server will return the following:

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

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.

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:

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. 

Both options can be combined. The result will be the union of all the assigned Roles.

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.

Assigning Roles in the shiro.ini File

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

LDAP Authentication and shiri.ini Authoriziation  Expand source

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:

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.

Assigning Roles from LDAP Groups

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

When assigning 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 in the a [main] section with the groupRolesMap setting.
After specifying the Group/Roles mapping your shiro ini file will look like this:
 Expand source

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. 

a) Using memberOf with User Search

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:

Configuration with memberOf search  Expand source

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

Configuration with Group Search  Expand source

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

 

 Expand source

 

Verifing the groupSearchBase and groupSearchFilter with an LDAP Browser
You can verify your 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 .

Substitution of the account name

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

Username Substitution  Expand source

 

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.

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

  • ldapRealm.userNameAttribute = cn

The configuration will look like this:

Configuration with Username Substitution  Expand source

4. Add Shiro settings

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:

 Expand source

 

Examples and special configurations

Example LDAP Configuration with mixed LDAP and Shiro Authentication

Add the iniRealm to 

  • securityManager.realms = $ldapRealm, $iniRealm

 

Configuration with mixed LDAP and Shiro authentication  Expand source

 

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]

 

Configuration with mixed LDAP and Shiro authentication  Expand source

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

 

Configuration with multiple LDAP realms  Expand source

A full shiro.ini example with Group Search 

 

Configuration with group search  Expand source

 

A full shiro.ini example with Group Search where the member attribute does not contain the account name but the common name


Configuration when the member attribute contains cn  Expand source

A full shiro.ini example with memberOf in the account record

 

Configuration with memberOf in the user record  Expand source

 

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 NamePasswordLDAP GroupShiro Role
gausspasswordmathematicians

all

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

 

Public LDAP Server

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/log4j.properties
  • Change:
    • #for debugging JOC set the following logger to 'debug'
      log4j.logger.com.sos = info
  • to
    • #for debugging JOC set the following logger to 'debug'
      log4j.logger.com.sos = debug

Log File location

The log file is located  in:

  • ./sos-berlin.com/joc/logs/yyyy_mm_dd.stderrout.log

 


  • No labels