...
This article describes the configuration of the JOC Cockpit to use an LDAP Server Directory Service for Authenticationauthentication. 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 with the JOC Cockpit - Authentication and Authorization article.
After changing the shiro.ini configuration file either by using the JOC Account Manager or a text editor, no restart of JOC is neccessaryrequired.
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 executed with ldapSearch
...
After setting up the Basic LDAP Configuration your [main]
section looks like this
Code Block | ||||
---|---|---|---|---|
| ||||
[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 |
...
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 Cockpit.
(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 Starttls set the value to Please note that the the server must be prepared to serve with Starttls. To check this, you can use a an LDAP browser such as the "Softerra LDAP Browser". Configure your LDAP Server there and click the "Enable Starttls Button" On client site side you will need the certificate and you have to add the certificate to your truststore. The path for to your truststore is defined in the
Example values:
Note: we have had difficulties with using starttls when 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 is assigned are specified in 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:
|
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 below section):
Anchor | ||||
---|---|---|---|---|
|
...
With authentication you will check for a valid usernameaccount/password combination. To achieve this , you have to specify the userDnTemplate
. The parameters for the userDnTemplate
can be read taken from a useraccount's properties page as shown in the screenshot from an LDAP browser below.
For the User account in the screenshot the template would be (replacing the uid value with {0}
):
...
Only one template can be specified per realm, separate realms have to be configured for different user templates.
Login with the sAMAccountName
...
or CN
This works with a Microsoft AD Active Directory that supports domain login.
- Change the
userDnTemplate
toldapRealm.userDnTemplate = uid={0}
- Add the userSearch
- Use
domain\useraccount
oruser@domain
account@domain
for the login where useraccount
is the value of the sAMAcountName attribute.
Anchor | ||||
---|---|---|---|---|
|
...
Account Names
The username account name can have one of the following login patterns:
sAMAccountName@domain
- the
sAMAccountName
attribute is a unique identifier for an account
username@domain
- the
domain\username
username
sAMAccountName
cn
- the Common Name attribute of the account is used
- this format requires the Common Name of an account to be unique
Note that LDAP Usernames 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 in together with Shiro authorization.
...
The [main]
section of the shiro.ini
file with authentication for the example "ur" User account from the screenshot above is shown in the next code block:
Examples for the userDnTemplate
:
- Example for the ur UserConfiguration for an arbitrary hierarchy:
ldapRealm.userDnTemplate = uid={0}, ou=People, dc=sos
- Example Configuration for the public LDAP Server mentioned at the start of in this article:
publicLdapRealm.userDnTemplate = uid={0},dc=example,dc=com
- Example Configuration with a Microsoft ADActive Directory:
adLdapRealm.userDnTemplate = CN cn={0},CNou=Users,dc=sos,DCdc=berlin,DCdc=com
Verification with ldapSearch
You can check the value of the userDnTemplate
by integrating using it in with a command for the ldapSearch utility such as:
ldapsearch -h localhost -p 389 -b "uid=ur,ou=People,dc=sos" -x
This should give return a result such as:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
# 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 |
...
For this server the command to check the userDnTemplate
in the ldapSearch utility would be:
...
The option -x is used in all the ldapSearch examples in this article. It is possible that your LDAP Server Directory Service does not allow this option and you have to specify a User 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 Search-Dn=userDnTemplatethe value from the userDnTemplate
in the Search DN input field. You should find only one entry.
...
Try to login with an LDAP usernameaccount:password combination. Use a username which an account that you have verified is to be correct by executing the ldapSearch command described above. If there are no role(s) configured for the user account but the authentication works then you will see the following screen:
Anchor | ||||
---|---|---|---|---|
|
...
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 An Account has the sum of all the Permissions coming from the Roles they have been assigned.
There are two options for assigning Roles to UsersAccounts:
- First Option: with an LDAP Group to Shiro Role mapping
- Second Option: with a Shiro User Account.
...
- If Roles are to be assigned in the
shiro.ini
file using the JOC Account Manager. Management: The LDAP groups Groups the user account is a member of does 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 user 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
...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[users]
user1 = ,all
user2 = ,it_operator,administrator
[main]
... |
Role 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 serverDirectory Service.
The roles assigned to an entry are saved in the [users]
section of the shiro.ini
configuration file according to the following syntax:
username account = ,list_of_roles
The list_of_roles
is a comma separated list such as:
...
The JOC Account Manager will add entries to the [users]
section for the Role assignment.
- Usernames Account names may have include blank spaces if they are stored in a an LDAP directoryDirectory Service. Usernames 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 theshiro.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 theshiro.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
- Passwords may 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 login is used then the reference must has to contain the whole domain/username account pattern e.g.
user@domain
domain\account
oraccount@domain
.
Anchor | ||||
---|---|---|---|---|
|
...
If the roles are assigned with the JOC Account Manager (i.e. there is [users]
section in the shiro.ini
configuration file) then you can skip this chapter.
shiro.ini
configuration file. This is done with the groupRolesMap
....
Code Block | ||
---|---|---|
| ||
[main]
...
ldapRealm.groupRolesMap = \
group1 : it_operator, \
group2 : all |
The groupRolesMap
looks like this.
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 the groupNameAttribute
.
...
If the roles are assigned with the JOC Account Manager (there is is a [users]
section 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:
- The user records have account has a memberOf attribute. The Then you can get retrieve the list of groups with the userSearch. Then proceed with Using memberOf with User Search.
- The user record account does not have a memberOf attribute. The group contains the users accounts that are member members of the group, Then proceed with Using group search.
...
Anchor | ||||
---|---|---|---|---|
|
If the user account entries do not have the memberOf attribute then you can skip this section and proceed with Using group search.
...
ldapRealm.searchBase
ldapRealm.userSearchFilter
After specifying the user search
the shiro.ini
configuration file will look like:
...
This approach looks for the user account entry and then reads the memberOf attribute. This attribute is often used when, for example, configuring AD Active Directory LDAP servers.
Define an a userSearchFilter
and a searchBase
that will find the user account (%s will be replaced by the username 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)
...
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.
...
If the user entries do have the memberOf attribute then you can skip this section and proceed with Using memberOf with User Search. Settings:
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389
ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos
ldapRealm.groupSearchBase = ou=Groups,dc=sos
ldapRealm.groupNameAttribute = cn
ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)
# Mapping of a LDAP group to roles. You can assign more than one role with separator sign |
ldapRealm.groupRolesMap = \
sos : it_operator, \
apl : administrator|application_manager
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm
|
When the memberOf attribute is not available for the user, account then you can use the group search.
...
This search should return the group entries the User 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
...
groupSearchBase
and groupSearchFilter
values by using them to perform a directory search. The result should show all groups the user account is a member of.Now set the groupNameAttribute
to the name of the attribute that contains the group name.
...
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 | ||||
---|---|---|---|---|
|
...
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 username account name from the login then you can skip this chapter
Sometimes the values of the member do not contain the username account name from the login but, for example, the cn
of the useraccount. In that case you have to search for the user account first and then specify the name of the attribute that should be used instead of the username acount name from the login .
To achieve this, specify a searchBase
, a userSearchFilter
and a userNameAttribute
.
...
This search should return the user account with the given usernameaccount name. Identify the attribute that should be used for the substitution in the group search base if it is not the username account name from the login.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
# 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 |
...
Perform a directory search with your LDAP client to check the User search configuration. You should find only the one User Account entry with the given usernameaccount name.
Then identify the name of the attribute that contains the value for the substitution. For example:
...
The whole configuration will looks look like this:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389
ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos
ldapRealm.searchBase = ou=People,dc=sos
ldapRealm.userNameAttribute = cn
ldapRealm.userSearchFilter = (uid=%s)
ldapRealm.groupSearchBase = ou=Groups,dc=sos
ldapRealm.groupNameAttribute = cn
ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)
# Mapping of a LDAP group to roles. You can assign more than one role with separator sign |
ldapRealm.groupRolesMap = \
sos : it_operator, \
apl : administrator|application_manager
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm
|
...
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:
Code Block | ||
---|---|---|
| ||
[main] .... cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager securityManager.cacheManager = $cacheManager securityManager.sessionManager.globalSessionTimeout = 900000 |
...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[users] ... [main] ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos ldapRealm.groupSearchBase = ou=Groups,dc=sos ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389 ldapRealm.groupNameAttribute = cn ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos) ldapRealm.groupRolesMap = \ group1: it_operator, \ group2: administrator|application_manager rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter rolePermissionResolver.ini = $iniRealm ldapRealm.rolePermissionResolver = $rolePermissionResolver securityManager.realms = $ldapRealm cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager securityManager.cacheManager = $cacheManager securityManager.realms = $ldapRealm, $iniRealm # Session timeout in milliseconds securityManager.sessionManager.globalSessionTimeout = 900000 |
Example LDAP Configuration with Several LDAP Servers
...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[main] ldapRealm1 = com.sos.auth.shiro.SOSLdapAuthorizingRealm ldapRealm1.userDnTemplate = uid={0},ou=People, dc=sos ldapRealm1.groupSearchBase = ou=Groups,dc=sos ldapRealm1.contextFactory.url = ldap://centos6_9_ldap.sos:389 ldapRealm1.groupNameAttribute = cn ldapRealm1.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos) ldapRealm1.groupRolesMap = \ group1: it_operator, \ group2: administrator|application_manager ldapRealm2 = com.sos.auth.shiro.SOSLdapAuthorizingRealm ldapRealm2.userDnTemplate = uid={0},ou=People, dc=sos ldapRealm2.groupSearchBase = ou=Groups,dc=sos ldapRealm2.contextFactory.url = ldap://anotherHost:389 ldapRealm2.groupNameAttribute = cn ldapRealm2.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos) ldapRealm2.groupRolesMap = \ group1: it_operator, \ group2: administrator|application_manager rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter rolePermissionResolver.ini = $iniRealm ldapRealm.rolePermissionResolver = $rolePermissionResolver securityManager.realms = $ldapRealm1, $ldapRealm2 cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager securityManager.cacheManager = $cacheManager # Session timeout in milliseconds securityManager.sessionManager.globalSessionTimeout = 900000 |
...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[main] ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos ldapRealm.groupSearchBase = ou=Groups,dc=sos ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389 ldapRealm.groupNameAttribute = cn ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos) ldapRealm.groupRolesMap = \ group1: it_operator, \ group2: administrator|application_manager rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter rolePermissionResolver.ini = $iniRealm ldapRealm.rolePermissionResolver = $rolePermissionResolver securityManager.realms = $ldapRealm cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager securityManager.cacheManager = $cacheManager # Session timeout in milliseconds securityManager.sessionManager.globalSessionTimeout = 900000 |
...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[main] ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos ldapRealm.groupSearchBase = ou=Groups,dc=sos ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389 ldapRealm.groupNameAttribute = cn ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos) ldapRealm.searchBase = ou=People,dc=sos ldapRealm.userNameAttribute = cn ldapRealm.userSearchFilter = (uniqueMember=uid=%s,dc=example,dc=com) ldapRealm.groupRolesMap = \ group1: it_operator, \ group2: administrator|application_manager rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter rolePermissionResolver.ini = $iniRealm ldapRealm.rolePermissionResolver = $rolePermissionResolver securityManager.realms = $ldapRealm cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager securityManager.cacheManager = $cacheManager # Session timeout in milliseconds securityManager.sessionManager.globalSessionTimeout = 900000 |
A full shiro.ini example with memberOf in the
...
account record
...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[main] ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389 ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos ldapRealm.searchBase = ou=People,dc=sos ldapRealm.userSearchFilter = (uid=%s) ldapRealm.groupRolesMap = \ group1: it_operator, \ group2: administrator|application_manager rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter rolePermissionResolver.ini = $iniRealm ldapRealm.rolePermissionResolver = $rolePermissionResolver securityManager.realms = $ldapRealm cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager securityManager.cacheManager = $cacheManager # Session timeout in milliseconds securityManager.sessionManager.globalSessionTimeout = 900000 |
A public LDAP Server for testing the connection
...
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
...