LDAP Configuration items
We refer in this document to a public LDAP server. To configure a realm for accessing the public LDAP server please add the following lines to the [main] section.
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"
Setting up the configuration
- 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
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.
|
[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 ...
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.
Examples for the userDnTemplate:
- Example
ldapRealm.userDnTemplate = uid={0},ou=People, dc=sos
- Configuration with public LDAP Server
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 you userDnTemplate with this ldapSearchCommand.
ldapsearch -h localhost -p 389 -b "uid=ur,ou=People, dc=sos" -x
Should give a result like:
Example with the public server
ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -x
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.
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.
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.
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
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=sosldapRealm.userSearchFilter = (uid=%s)
Verification with ldapSearch
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. 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.
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