...

This brings forward a popup window with the following tabs:

• Simple Mode: The most frequently used settings are available.
• Expert Mode:: The full set of settings is available.
  
  

x

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:

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

Image Removed

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)

ldapReam

com.sos.auth.shiro.SOSLdapAuthorizingRealm

ldapRealm.contextFactory.url

ldap://host:port

ldapRealm.useStartTls

ldapRealm.hostNameVerification   

rolePermissionResolver  

com.sos.auth.shiro.SOSPermissionResolverAdapter

ldapRealm.rolePermissionResolver 

$rolePermissionResolver

securityManager.realms 

$ldapRealm [, $ldapRealm [, $iniRealm]]

In a simple configuration these items could appear as visible with the code block below (see also the example configuration for the public LDAP server listed in the below section):

...

2. LDAP Authentication

Settings: 

• ldapRealm.userDnTemplate

The userDnTemplate Setting

With authentication you will check for a valid account/password combination. To achieve this you have to specify the userDnTemplate. The parameters for the userDnTemplate can be taken from an account's properties page as displayed in the below screenshot taken from an LDAP browser.

Image Removed

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:

Image Removed

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:

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

1. Change the userDnTemplate to ldapRealm.userDnTemplate = {0}
2. Add the User Search
3. Use domain\account or account@domain for the login where account is the value of the sAMAccountName attribute.

...

Account Names

The account name for a Microsoft Active Directory^® can have one of the following login patterns:

• sAMAccountName@domain
  • The sAMAccountName attribute is a unique identifier for an Account.
• domain\sAMAccountName
• cn
  • The Common Name attribute value of the Account is used.
  • This format requires the Common Name of an Account to be unique.

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

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

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

Image Removed

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:

Image Removed

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.

...

3. Authorization

Authorization is the assignment of Roles to User Accounts. Roles, in turn, have permissions that are listed in the shiro.ini configuration file. An Account has all Permissions specified by the Roles that the Account is assigned.

There are two options for assigning Roles to Accounts:

1. First Option: with an LDAP Group to Shiro Role mapping
2. Second Option: with a Shiro User Account. 

...

Please decide:

1. If Roles are to be assigned in the shiro.ini file using the JOC Cockpit Account Management then the LDAP Groups the Account is a member of have no effect. Proceed with Assigning roles in the shiro.ini File
2. If Roles are to be assigned with the group roles mapping: The LDAP Groups the Account is a member of are assigned to JOC Cockpit roles. Proceed with Assigning Roles from LDAP Groups
3. If a mix of 1. and 2. is to be used: Proceed with Assigning roles in the shiro.ini File and then with Assigning Roles from LDAP Groups.

...

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

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

Image Removed

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.

...

• When a User Account with blank spaces in its name is configured using the JOC Cockpit's Manage Accounts view then every blank space in the name will be automatically replaced with %20 before the name is written to the shiro.ini file.
• When a User Account with blank spaces in its name is added directly to the shiro.ini file then every blank space in the name should replaced with %20 before the name is written to the shiro.ini file.
• Every occurrence of %20 in an User Account name saved in the shiro.ini file will be automatically converted to a blank space before this name is submitted to the LDAP server.

...

Specify general Settings 

The following table lists the general items used to configure an LDAP connection.

Anchor
authentication authentication

Step 2: LDAP Authentication

Specify Authentication Settings

The following table lists possible values for authentication with an LDAP Server:

1. Add the User Search

Verify Authentication Settings

Verify by use of LDAP Browser

Possible values for the LDAP User DN Template can be derived from an account's properties. The below screenshot displays such properties from an LDAP Browser:

In a first step search with the value from the LDAP User DN Template in the Search DN input field. The query should return only one entry.

Image Added

From the properties of the resulting entry the setting for the account is used and the uid value is replaced with: {0}.

Image Added

Verify by use of ldapSearch

Users can check the value of the LDAP User DN Template setting by use of the ldapSearch utility:

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

# This should return a result such as:

# 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 use of a public LDAP Server

The following example uses a publicly available LDAP Server. To our experience this server provides a good example to make an initial LDAP configuration work.

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

# This should return a result such as:

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

The option -x is used in the ldapSearch examples in this article. It is possible that an LDAP Directory Service does not allow this option and instead an account and a password have to be specified. In this case the command would look like this:

ldapsearch -h ldap.forumsys.com -p 389 -b "uid=gauss,dc=example,dc=com" -W -D "uid=gauss,dc=example,dc=com"

Verify by use of 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:

Anchor
authorization authorization

Step 3: Authorization

Authorization includes the assignment of roles to user accounts. Roles, in turn, hold permissions. For details see JS7 - Manage Roles and Permissions.

There are two options for assignment of roles to user accounts depending on the Identity Service Type:

• LDAP: add a Group/Roles mapping: membership of a user account in a security group of the LDAP Server is mapped to a role in the Identity Service.
• LDAP-JOC: add a user account and assign roles. Accounts are managed with the Identity Service in parallel to the LDAP Server. No user passwords are managed with JOC Cockpit as authentication is performed with the LDAP Directory Service.

Anchor
assigning_roles_in_the_shiro.ini_file assigning_roles_in_the_shiro.ini_file

Assign Roles with Identity Service

...

Anchor
assigning_roles_from_ldap_groups assigning_roles_from_ldap_groups

...

Map Roles from LDAP Security Groups

...

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

...

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)

Verify by use of ldapSearch

Verification with an LDAP Browser

...

...

Image Removed

...

...

• ldapRealm.userNameAttribute = cn

...

...

...

...

ldapsearch -h localhost -p 389 -b "ou=People,dc=sos

...

" -s sub "uid=fTester" -x

# This should return the following result

# 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 by use of 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.

Image Added

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

• ldapRealm.userNameAttribute = cn

The configuration will look like this:

...

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:

[main]
....
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager
securityManager.sessionManager.globalSessionTimeout = 900000

Examples and special configurations

...

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:

...

.

Logging

References

• JS7 - Logging
  
  • JS7 - Log Files and Locations
  • JS7 - Log Levels and Debug Options

Use Cases