Introduction
This article describes the configuration of the JOC Cockpit to use an LDAP Server for Authentication. 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 JOC Cockpit is provided in the JOC Cockpit - Authentication and Authorization article.
A Simple LDAP Test Configuration
A 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, either before or after the default line:
securityManager.sessionManager.globalSessionTimeout = 900000
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 necessary to restart the Jetty web server.)
You will now be able to use the 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 users listed above.
The LDAP group memberships will be mapped onto 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.
How to set up an LDAP configuration
Carry out the following steps:
- Set up the basic LDAP configuration
- Set up the authentication
- Set up the authorization
- Defining the groupRolesMapping (optional)
- Defining the Roles per user in the [users] section (optional)
- Defining the search for groups
Relevant Tools
- An LDAP Browser:
- The screenshots shown in this article were made with the "Softerra LDAP Browser" that had been configured to use the relevant LDAP server.
- A command line utility:
- The example commands shown were implemented in ldapSearch
1. Basic LDAP Configuration
The following table lists the basic items used to configure an LDAP realm. These items are configured in the [main]
section of the shiro.ini
file and cannot be changed with the Account Management in JOC.
(See the Authentication and Authorization - Configuration article for more information about the shiro.ini
file)
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 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 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 Please note the the server must be prepared to serve with Starttls. To check this, you can use a LDAP browser such as the "Softerra LDAP Browser". Configure your LDAP Server there and click the "Enable Starttls Button" On client site you will need the certificate and you have to add the certificate to your truststore. The path for your truststore is defined in the
Example values:
Note: we have had difficulties with using starttls with the JRE1.8.0_151 and have overcome these by installing a JDK. |
ldapRealm.hostNameVerification | on|off true|false | To enable the host name verification of the certificate. The default is off. |
rolePermissionResolver | com.sos.auth.shiro.SOSPermissionResolverAdapter | The implementation of the permission resolver. The SOS implementation sets an org.apache.shiro.realm.text.IniRealm to resolve the permissions. That means that the permissions a role have are specified in the configuration file shiro.ini in the same way it is done when using the iniRealm . |
ldapRealm.rolePermissionResolver | $rolePermissionResolver | Sets the role permission resolver for the LDAP realm. |
securityManager.realms | $ldapRealm | Sets the list of realms that should be used for authentication. This is a comma separated list of items. Example values:
|
In a simple configuration these items could appear as shown in the code block below (see also the example configuration for the public LDAP server listed in the previous section):
[main] ... ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm ldapRealm.contextFactory.url = ldap://myHost:389 ldapRealm.useStartTls = true ldapRealm.hostNameVerification = off rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter rolePermissionResolver.ini = $iniRealm ldapRealm.rolePermissionResolver = $rolePermissionResolver securityManager.realms = $ldapRealm ...
2. Authentication
The user template
With the authentication you will check for a valid username/password combination. To achieve this, you have to specify the userDnTemplate
. The parameters for the userDnTemplate
can be read from a user's properties page as shown in the screenshot from an LDAP browser below.
For the User in the screenshot the template would be (replacing the uid value with {0}
):
ldapRealm.userDnTemplate = uid={0},ou=People,dc=sos
Only one template can be specified per realm, separate realms have to be configured for different user templates.
Usernames
The username can have one of the following login patterns:
username@domain
domain\username
username
Note that LDAP Usernames may contain blank spaces. See the Authorization section below for a description of how blank spaces are handled when LDAP authentication is used in together with Shiro authorization.
Configuration in the shiro.ini file
The [main]
section of the shiro.ini file with authentication for the example "ur" User from the screenshot above is shown in the next code block:
Examples for the userDnTemplate
:
- Example for the ur User
ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos
- Configuration for the public LDAP Server mentioned at the start of this article
publicLdapRealm.userDnTemplate = uid={0},dc=example,dc=com
- Configuration with a Microsoft AD
adLdapRealm.userDnTemplate = sAMAccountName={0},dc=company,dc=com
Verification with ldapSearch
You can check the userDnTemplate by integrating it in a command for the ldapSearch utility such as:
ldapsearch -h localhost -p 389 -b "uid=ur,ou=People, dc=sos" -x
This should give a result such as:
Example for the public LDAP server
For this server the command to check the userDnTemplate in the ldapSearch utility would be:
ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -x
The server will return the following:
Note: ldapSearch Parameters
The option -x is used in all the ldapSearch examples in this article. It is possible that your LDAP Server does not allow this option and you have to specify a User and a Password. If this is the case 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 Search-Dn=userDnTemplate. You should find exactly one entry.
Verification with the JOC Cockpit
Try to login with an LDAP username:password combination. Use a username which you have verified is correct by executing the ldapSearch described above. If there are no role(s) configured for the user but the authentication works you will see the following:
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. A User has the sum of all the Permissions coming from the Roles they have been assigned.
There are two options for assigning Roles to Users: with an LDAP Group to Shiro Role mapping and with a Shiro User Account. Both options can be combined. The result is a combination of - i.e. the union of - all assigned Roles.
Assigning roles in the shiro.ini
File
Roles assignment in the shiro.ini
file is configured in the Manage Accounts view of the JOC Cockpit. Do not enter the Password for a User Account that is to be authenticated by an LDAP server.
The roles assigned to an entry are saved in the [users]
section of the shiro.ini
configuration file.
User Accounts with LDAP Authentication will be saved in the [users]
section of the shiro.ini
file according to the following syntax:
username = ,list_of_roles
Please refer to the "Username" section above to see which username patterns can be configured.
The list_of_roles is a comma separated list such as:
it_operator,administrator
Here is a typical configuration with LDAP Authentication - using the Public LDAP server mentioned above and Shiro authorization.
Note that the following applies if an LDAP User is to use Shiro authorization to allocate Roles:
- Usernames may have blank spaces if they are stored in a LDAP directory. Usernames 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 theshiro.ini
file. - Every occurrence of %20 in an Account User Name saved in the
shiro.ini
file will be automatically converted to a blank space before this name is submitted to the LDAP server.
- 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
- Passwords should not be specified for Accounts with LDAP authentication when configuring such Accounts using the JOC Cockpit's Manage Accounts view .
- When you login with a domain the reference must contain the whole domain/username pattern e.g.
user@domain
.
Assigning Roles from LDAP Groups
The group-roles mapping
When assigning the roles from the LDAP Groups a user is a member of, the groups will be mapped to the roles that are defined in the shiro.ini configuration file. This is done with the groupRolesMap
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 you have specified in the groupNameAttribute
.
Example
ldapRealm.groupRolesMap = \
sos : it_operator, \
apl : administrator|application_manager
Example with the Public LDAP Server
ldapRealm.groupRolesMap = \
scientists : it_operator, \
mathematicians : all
Getting the Groups a User is a member of
There are two options to find the Group membership(s) for a User Account.
a) Using memberOf with User Search
This approach looks for the user entry and then reads the "memberOf" attribute.
Especially when using an AD LDAP Server or when is enabled (for example, in OpenLDAP) you can make use of the "memberOf" attribute for the given user.
Define an userSearchFilter
and a searchBase
that will find the user (%s will be replaced by the username from the login without the domain)
Example for user search
ldapRealm.searchBase = ou=People,dc=sos
ldapRealm.userSearchFilter = (uid=%s)
Example for user search in AD
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 exactly 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" you can specify the name of the attribute with groupNameAttribute
key as described in the next section.
b) Using group search
When the memberOf
attribute is not available for the user, 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)
It is helpful to use an LDAP client like the "Softerra LDAP Browser" to get the correct values for these keys. This is described in the next two subsections.
Getting the value for the groupSearchBase
Identify the place 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 User 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
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 user 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
.
The whole configuration will now look like:
Substitution of the username
Sometimes the values of the member do not contain the username from the login but, for example, the cn
of the user. In that case you have to search for the user first and then specify the name of the attribute that should be used instead of the username 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 user with the given username. Identify the attribute that should be used for the substitution in the group search base if it is not the username from the login.
Verification with an LDAP Browser
Perform a directory search with your LDAP client to check the User search configuration. You should find only the one User entry with the given username.
Then identify the name of the attribute that contains the value for the substitution. For example:
ldapRealm.userNameAttribute = cn
The whole configuration looks like this: