Table of Contents |
---|
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
Display feature availability | ||
---|---|---|
|
LDAP configuration information is stored in the [main]
section of 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 with JOC Cockpit is provided in with the JOC Cockpit - Authentication and Authorization article.
A Simple LDAP Test
A public LDAP server which can be accessed using a relatively simple configuration is available from Forum Systems. In this article we will refer to the authentication of two users, gauss and newton that are each members of a different group as shown in the following table:
Account Name | Password | Group |
---|---|---|
gauss | password | mathematicians |
newton | password | scientists |
Public Server
To configure a realm for accessing the public LDAP server please add the following lines to the [main] section of the shiro.ini
file.
Code Block | ||
---|---|---|
| ||
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.userSearchFilter = (uniqueMember=uid=%s,dc=example,dc=com)
publicLdapRealm.groupRolesMap = \
scientists : it_operator, \
mathematicians: all |
Verification with ldapSearch
In all ldapSearch examples the option -x is used. It is possible that your LDAP Server does not allow this and you have to specify a user and a password such as:
ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -W -D "uid=gauss,dc=example,dc=com"
Follow these steps to set up the configuration
...
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 existingshiro.ini.active
file will be renamedshiro.ini.backup
and any already existing file with that name will be overwritten.
- The import function automatically imports a file named
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:
- Set up the basic Basic LDAP configuration
- Set up the authentication
- Set up the authorization
- Defining the groupRolesMapping (optional)
- Defining the roles Roles per user account in the
[users]
section (optional) - Defining the search for groups
1. Basic LDAP Configuration
There are some configuration items that configure the ldap realm. These items can not be changed with the Account Management in JOC.
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 like "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 of your truststore is definied in the JOC configuration file joc.properties.
e.g.
|
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 realm that should be used for authentication. This is a comma seperated list of realms. e.g.
|
Code Block |
---|
[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
With the authentication you will check for a valid username/password combination. To achieve this, you have to specify the userDnTemplate
. The value for the userDnTemplate can be read from the properties page of an user.
...
Username
The username is part of the login patterns:
- username@domain
- domain\username
- username
The username may have blanks if they are stored in a LDAP directory. Usernames stored in the configuration file shiro.ini may not have blanks.
When referring to usernames from the LDAP directory to keys in the [users] section to assign roles to the user, you have to change blanks to %20. The password must be empty. When you login with a domain the reference must contain the whole domain/username pattern e.g. user@domain
The JOC Account Manager will consider the handling of blanks. Please note that you have to specify the user with the domain in the JOC Account Manager and without password.
Configuration in the shiro.ini file
Main section with the user authentication. The roles are assigned in the [users] section.
Code Block | ||
---|---|---|
| ||
[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos
ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389
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.sessionManager.globalSessionTimeout = 900000
|
Examples for the userDnTemplate:
...
- Add Shiro settings
The Setup Procedure
The following diagram provides an overview of the setup procedure:
Flowchart |
---|
1 [label="1. Set up the Basic LDAP config\n(URL, etc)"]
1 -> 2 [weight=5, len=0.5]
2 [label="2. Set up Authentication\n(userDnTemplate)"]
2 -> 3
3 [label="3. Set up 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 accounts"]
10 -> E2
E2 [shape="circle", style="filled", label="End", color="pink"]
5 -> 6
6 [shape="diamond", label="Has the account record a\nmemberOf attribute?",fillcolor="lightblue"]
6 -> 20 [label="Yes"]
20 [label="Specify User Search\l - searchBase\l - userSearchFilter"]
20 -> E3
E3 [shape="circle", style="filled", label="End", color="pink"]
6 -> 7 [label="No"]
7 [label="Specify Group Search\l - groupSearchBase\l - groupSearchFilter\l - groupNameAttribute"]
7 -> 8
8 [shape="diamond", label="Does the member attribute contain\nthe account name from the login?",fillcolor="lightblue"]
8 -> E4 [label="Yes"]
E4 [shape="circle", style="filled", label="End", color="pink"]
8 -> 9 [label="No"]
9 [label="Specify User Search\l - searchBase\l - userSearchFilter"]
9 -> E5
E5 [shape="circle", style="filled", label="End", color="pink"] |
Anchor | ||||
---|---|---|---|---|
|
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:
Code Block | ||||
---|---|---|---|---|
| ||||
[main]
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://myHost:389
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager |
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.
Info | ||
---|---|---|
| ||
Note that the Administrators wishing to use a local user while configuring LDAP are therefore recommended to modify the securityManager element immediately to:
|
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)
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 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 Make sure that the firewall is open for the given port. |
ldapRealm.useStartTls | true|false | To enable Starttls set the value to 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
Example values:
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|false | 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 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:
|
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):
Anchor | ||||
---|---|---|---|---|
|
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:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://myHost:389
ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm
|
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.
- Change the
userDnTemplate
toldapRealm.userDnTemplate = {0}
- Add the User Search
- Use
domain\account
oraccount@domain
for the login whereaccount
is the value of thesAMAccountName
attribute.
Anchor | ||||
---|---|---|---|---|
|
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.
- The
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.
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.
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:
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
|
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:
ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -x
The server will return the following:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
# extended LDIF
#
# LDAPv3
# base <uid=gauss,dc=example,dc=com> with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#
# gauss, example.com
dn: uid=gauss,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: Carl Friedrich Gauss
sn: Gauss
uid: gauss
mail: gauss@ldap.forumsys.com
# search result
search: 2
result: 0 Success
# numResponses: 2
# numEntries: 1
|
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:
Multi-Realm Authentication
Authentication can be configured for a multi-realm environment made up of one or more LDAP realms, with or without an ini realm. A simple multi-realm configuration is shown in the mixed LDAP and Shiro Authentication example below.
Note that the a user name can be configured for accounts in more than one realm. The behavior in such a situation (for example, should the roles configured for all realms be assigned to the account or only the roles configured for the realm used for the successful login?) is briefly described in the mixed LDAP and Shiro Authentication example below and in detail in the Multi-Realm Authentication and Authorization article.
Anchor | ||||
---|---|---|---|---|
|
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:
- First Option: with an LDAP Group to Shiro Role mapping
- Second Option: with a Shiro User Account.
Both options can be combined. The default result will be the union of all the assigned Roles. Note, however, that alternative
Please decide:
- 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 - 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.
Anchor | ||||
---|---|---|---|---|
|
shiro.ini
FileAfter assigning Roles in the shiro.ini
file the [users]
section of the file will look like this:
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 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 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 User Account 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 a domain login is used then the reference has to contain the domain/account pattern e.g.
domain\account
oraccount@domain
.
Anchor | ||||
---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
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.
shiro.ini
configuration file. This is done in the a [main]
section with the groupRolesMap
setting.shiro ini
file will look like this:Code Block | ||
---|---|---|
| ||
[main]
...
ldapRealm.groupRolesMap = \
group1 : it_operator, \
group2 : all |
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:
- 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.
- 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.
Anchor | ||||
---|---|---|---|---|
|
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:
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)
# 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
|
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 = (sAMAccountName=%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.
Anchor | ||||
---|---|---|---|---|
|
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:
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 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)
Anchor | ||||
---|---|---|---|---|
|
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
Code Block | ||
---|---|---|
| ||
# extended LDIF
#
# LDAPv3
# base <ou=Groups,dc=sos> with scope subtree
# filter: uniqueMember=uid=ur,ou=People,dc=sos
# requesting: ALL
#
# sos, Groups, sos
dn: cn=sos,ou=Groups,dc=sos
description: Employees of SOS GmbH
objectClass: top
objectClass: groupofuniquenames
cn: sos
uniqueMember: uid=ur,ou=People,dc=sos
uniqueMember: uid=fTester,ou=People,dc=sos
# apl, Groups, sos
dn: cn=apl,ou=Groups,dc=sos
objectClass: top
objectClass: groupofuniquenames
cn: apl
uniqueMember: uid=ur,ou=People,dc=sos
uniqueMember: uid=fTester,ou=People,dc=sos
# search result
search: 2
result: 0 Success
# numResponses: 3
# numEntries: 2
|
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 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
.
Anchor | ||||
---|---|---|---|---|
|
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 contains 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 Account 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.
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
|
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:
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 |
...
- Configuration with a Microsoft AD
adLdapRealm.userDnTemplate = sAMAccountName={0},dc=company,dc=com
Verification with ldapSearch
You can check you userDnTemplate with this ldapSearchCommand.
ldapsearch -h localhost -p 389 -b "uid=ur,ou=People, dc=sos" -x
Should give a result like:
Code Block | |
---|---|
title | Result: ldapsearch -h localhost -p 389 -b "uid=urldapRealm.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 | " -x
collapse | true |
# ur, People, sos
dn: uid=ur,ou=People,dc=sos
mail: uwe.risse@sos-berlin.com
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 with the public server
ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -x
Code Block | ||||
---|---|---|---|---|
| ||||
# extended LDIF
#
# LDAPv3
# base <uid=gauss,dc=example,dc=com> with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#
# gauss, example.com
dn: uid=gauss,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: Carl Friedrich Gauss
sn: Gauss
uid: gauss
mail: gauss@ldap.forumsys.com
# search result
search: 2
result: 0 Success
# numResponses: 2
# numEntries: 1
|
Verification with Softerra LDAP Browser
Search with Search-Dn=userDnTemplate. You should find exactly one entry.
Verification with JOC
Try to login with a username from LDAP and a password. Use a username for which you have verified is correct by executing the ldapSearch described above. When you see this screen, the authentication works.
...
3. Authorization
Authorization means the assignment of roles to users. A role have permissions that are listed in the shiro.ini configuration file. A user have all permissions coming from the assigned roles.
There are two options how to assigns roles to users. Both options can be mixed. The result of the mix is the union of all assigned roles.
Assigning roles in the shiro.ini File
The roles assignment in the shiro.ini file is managed with the JOC Account Manager.
The JOC Account Manager writes the assigned roles to an entry in the [users] section.
In the [users] section you list the users that are available in the LDAP.
username = ,list_of_roles
Please refer to the chapter "Username" to see how to specify the username
The list_of_roles is a comma separated list of roles e.g. it_operator,administrator
Here is a typical configuration with LDAP Authentication and shiro.ini authorization.
)
# 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
|
Anchor | ||||
---|---|---|---|---|
|
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:
Code Block | ||
---|---|---|
| ||
[main]
....
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager
securityManager.sessionManager.globalSessionTimeout = 900000 |
Examples and special configurations
Anchor | ||||
---|---|---|---|---|
|
Add the iniRealm to
securityManager.realms = $ldapRealm, $iniRealm
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
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager
securityManager.realms = $ldapRealm, $iniRealm
# Session timeout in milliseconds
securityManager.sessionManager.globalSessionTimeout = 900000 |
Behavior Notes:
- By default roles from the shiro ini are added to the roles of an authenticated LDAP user with the same name. This happens regardless of whether or not a password is set for the account in the shiro ini file. However, a number of options can be configured to modify this behavior. These are described in the Multi-Realm Authentication and Authorization article.
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]
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
Code Block | ||||||
| ||||||
[users]
gauss = ,all
newton = ,it_operator,administrator
[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos
ldapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389
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.sessionManager.globalSessionTimeout = 900000
|
Assigning roles from LDAP Groups
...
The group roles mapping
When assigning the roles from the LDAP Groups the user is a member of the groups the groups will be mapped to the roles that are defined in the shiro.ini configuration file. This will be 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 defined in the shiro.ini configuration file separated with a bar |
Please not 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 how to find the membership of the user.
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 "memberOf" is enabled in e.g. OpenLdap you can make use of the attribute "memberOf" 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 group search
ldapRealm.searchBase = ou=People,dc=sos
ldapRealm.userSearchFilter = (uid=%s)
Example for AD
ldapRealm.searchBase = dc=example,dc=com
ldapRealm.userSearchFilter = (sAMAcountName=%s)
To get the correct values for the searchBase
and the userSearchFilter
a LDAP client such as the "Softerra LDAP Browser" is very helpful. Perform a directory search with the values. You should find exactly one entry.
The searchBase
is the value of the base DN
Hint: When in your environment the attribute name is not the default "memberOf" you can specify the name of the attribute with groupNameAttribute
key.
...
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
ldapRealm.groupSearchBase = ou=Groups,dc=sos
ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)
To get the correct values for these key a LDAP client like the "Softerra LDAP Browser" is helpful.
...
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 groupEntry and see how the members are stored there.
The groupSearchFilter is
attr=val
where attr
is name of the attribute and val
is the content where the userid is replaced with %s. In this example
ldapRealm.groupSearchFilter = (uniqueMember=uid=%s,ou=People,dc=sos)
Verification with ldapSearch
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. Please identify the attribute that contains the group name that should be used in the user roles mapping.
Code Block | ||
---|---|---|
| ||
# extended LDIF
#
# LDAPv3
# base <ou=Groups,dc=sos> with scope subtree
# filter: uniqueMember=uid=ur,ou=People,dc=sos
# requesting: ALL
#
# sos, Groups, sos
dn: cn=sos,ou=Groups,dc=sos
description: Employees of SOS GmbH
objectClass: top
objectClass: groupofuniquenames
cn: sos
uniqueMember: uid=ur,ou=People,dc=sos
uniqueMember: uid=fTester,ou=People,dc=sos
# apl, Groups, sos
dn: cn=apl,ou=Groups,dc=sos
objectClass: top
objectClass: groupofuniquenames
cn: apl
uniqueMember: uid=ur,ou=People,dc=sos
uniqueMember: uid=fTester,ou=People,dc=sos
# search result
search: 2
result: 0 Success
# numResponses: 3
# numEntries: 2
|
Verification with LDAP Browser
groupSearchBase
and your groupSearchFilter
. 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: Please note that the whole content of this attribute must be used in the groupRolesMap
attribute. Sometimes here is something like ou=Groups, dc=sos, cn=groupname
. Please take the whole value for the mapping.
The whole configuration looks like this
# Locally authenticated users (specified with a hashed password)
root = $shiro1$SHA-512$500000$W0oNBkZY9LRrRIGyc4z2Ug==$NcoU+ZFM9vsM0MeHJ3P5NJ0NdvJrK38qVnl7v7YG7p9o5ZJfMccugJsA9myJsTNx2BF5rbvA696UhTGdUtSnOg==,all
# LDAP authenticated users (specified without a password)
COMPANY\homer = ,all
COMPANY\alice = ,all
[main]
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
# Realm for Domain company.local
# -------------------------------
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://company.local:389
# users can login with COMPANY\account and account@COMPANY.local where the account maps to the sAMAccountName
ldapRealm.userDnTemplate = {0}
ldapRealm.rolePermissionResolver = $rolePermissionResolver
# -------------------------------
# Authentication via domains ite.local, domain.local and via shiro.ini [users] section
securityManager.realms = $ldapRealm, $iniRealm
passwordMatcher = org.apache.shiro.authc.credential.PasswordMatcher
iniRealm.credentialsMatcher = $passwordMatcher
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager
# Session timeout in milliseconds
securityManager.sessionManager.globalSessionTimeout = 1800000 |
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
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
|
A full shiro.ini example with Group Search
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
|
A full shiro.ini example with Group Search where the member attribute does not contain the account name but the common name
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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.contextFactory.url = ldap://centos6_9_ldap.sos:389 ldapRealm.groupNameAttribute = cnldapRealmcn 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.searchBase = ou=People,dc=sos ldapRealm.userNameAttribute = cn ldapRealm.userSearchFilter = (uniqueMember=uid=%s,dc=example,dc=com) ldapRealm.groupRolesMap = \ sos group1: it_operator, \ apl 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 |
Substitution of the username
Sometimes the values of the member do not contain the username from the login but e.g. the cn of the user. In that case you have to search the user first and 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 ldapSearch
...
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
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 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:
Code Block | ||||
---|---|---|---|---|
| ||||
publicLdapRealm |
...
This search should return the user with the given username. Please identify the attribute that should be used for the substitution in the group search base if it is not the username 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
|
Verification with LDAP Browser
To check the user search perform a directory search with your LDAP client. You should find exactly the one user entry of the given username.
Then identify the name of the attribute that contains the value for the substitution. E.g.
ldapRealm.userNameAttribute = cn
The whole information looks like this
Code Block | ||
---|---|---|
| ||
[main] ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm ldapRealm publicLdapRealm.userDnTemplate = uid={0},dc=example,dc=com publicLdapRealm.searchBase = dc=example,dc=com publicLdapRealm.contextFactory.url = ldap://centos6_9_ldap.sos:389 ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos ldapRealm.userNameAttribute = cn ldapRealm.searchBase = ou=People,dc=sos 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 = org.apache.shiro.cache.MemoryConstrainedCacheManager securityManager.cacheManager = $cacheManager # Session timeout in milliseconds securityManager.sessionManager.globalSessionTimeout = 900000 = 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 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/log4j2.xml
- Enable the
AuthAppender
by uncommenting
<!-- logger for authentication and session management -->
<Logger name="com.sos.auth" level="trace" additivity="false">
<AppenderRef ref="AuthAppender"/>
</Logger>
Log File location
The log file is located in:
"${sys:jetty.base}/logs/JOCShiroLog.log