Group-based LDAP authentication

ImageMaster offers the possibility to configure an LDAP authentication, where LDAP groups can be mapped to ImageMaster roles or (since ImageMaster 9.9.2) to ImageMaster groups, and the role or group selection is based on LDAP group membership. The mapping of LDAP attributes for user information (e.g. e-mail) can be customized.

To enable group-based LDAP authentication, set the authenticator class (authModule) in the userlib configuration to the following entry (see External authenticator):

com.tsystems.ima.userlib.ldap.LdapGroupAuthentication

The LDAP configuration is specified as illustrated below:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<ns2:ldapConfiguration xmlns:ns2="http://www.tsystems.com/ima/9.7/authenticationconfig">

<!-- ldaps:// (SSL) can be used if the application server trusts the certificate of the LDAP server -->

<!-- SSL certificates and trust chains are controlled using the standard Java mechanisms. That is, the values of the system properties

- javax.net.ssl.keyStore

- javax.net.ssl.trustStore

- javax.net.ssl.trustStorePassword

- javax.net.ssl.keyStorePassword

control which client certificate is used and which server certificates are trustworthy. -->

<!-- optional port with :port -->

<providerUrl>ldap://ldapHostnameOrIp</providerUrl>

 

<!-- optional for ImageMaster but most likely required by the LDAP server -->

<managerBind>

<!-- distinguished name of the user to uses to search for the user to be logged in -->

<dn>cn=theSystemAccount,ou=Users,dc=example,dc=com</dn>

<passwordAlias>ldap.managerPassword</passwordAlias>

</managerBind>

 

<!-- The entry point for searching a user -->

<userBaseTemplate>ou=Users,dc=example,dc=com</userBaseTemplate>

 

<!-- The LDAP filter expression that is used to restrict the search. Use "(&amp;)" if no restriction needs to be applied. This expression will be extended automatically, and trigger a login name check (name of the attribute to compare is taken from "userNameAttribute"). -->

<userFilter>(uid={user})</userFilter>

 

<!-- Search depth to find a user starting from the entry point, possible values: "subtree", "onelevel" -->

<userSearchScope>subtree</userSearchScope>

 

<!-- Maximum number of forwards to other LDAP / Active Directory instances -->

<maxReferrals>3</maxReferrals>

 

<!-- where to look for groups -->

<groupSearchBase>ou=Groups,dc=imagemaster,dc=local</groupSearchBase>

 

<!-- Mappings from LDAP group to ImageMaster role -->

<!-- optional, default none -->

<groupMappings>

<groupMapping group="cn=GroupA,ou=Groups,dc=example,dc=com" role="powerUser"/>

<groupMapping group="cn=GroupA,ou=Groups,dc=example,dc=com" role="someImageMasterRoleA"/>

<groupMapping group="cn=GroupA,ou=Groups,dc=example,dc=com" role="someImageMasterRoleB"/>

<groupMapping group="cn=GroupB,ou=Groups,dc=example,dc=com" role="someImageMasterRoleB"/>

</groupMappings>

 

<!-- LDAP attribute to use for the users full name -->

<!-- optional, default "cn" -->

<fullNameAttribute>cn</fullNameAttribute>

 

<!-- LDAP attribute to use for the users e-mail address -->

<!-- optional, default "mail" -->

<emailAttribute>mail</emailAttribute>

 

<!-- ImageMaster role to assign if user would otherwise have no roles -->

<!-- optional, defaults to assigning no default role -->

<defaultRole>otherRole</defaultRole>

 

<!-- attribute in user entries for group membership -->

<!-- note that this may be an operational attribute so it may not show up in LDAP tools by default -->

<!-- optional, default "memberOf" -->

<groupMembershipAttribute>memberOf</groupMembershipAttribute>

 

<!-- object class of LDAP group entries -->

<!-- optional, default "group" -->

<groupObjectClass>group</groupObjectClass>

 

<!-- Mappings from LDAP group to ImageMaster user group -->

<!-- optional, default none -->

<userGroupMappings>

<userGroupMapping group="cn=UserGroupA,ou=Groups,dc=example,dc=com" userGroup="someImageMasterUserGroupA"/>

<userGroupMapping group="cn=UserGroupA,ou=Groups,dc=example,dc=com" userGroup="someImageMasterUserGroupB"/>

<userGroupMapping group="cn=UserGroupB,ou=Groups,dc=example,dc=com" userGroup="someImageMasterUserGroupB"/>

</userGroupMappings>

</ns2:ldapConfiguration>

The LDAP configuration is tenant-specific.

NOTE:
To be able to use the group-based LDAP authentication and to show LDAP groups in the AdminClient, the newly added settings may need to be manually adjusted; for details see LDAP / AD settings in [UM AdminClient].
Note that this step can fail during the installation when an old, invalid configuration is present even if LDAP authentication is not enabled. In this case fix or delete the old configuration and rerun the step.

Configuration aspects in case of an upgrade

In practice, a case was observed with an upgrade from 9.7.2 to 9.8.1, where the class name of the external authenticator had to be adjusted:

  • from old: com.tsystems.ima.userlib.ldap.LdapAuthenticationFallback

  • to new: com.tsystems.ima.userlib.ldap.LdapGroupAuthentication

Upgrade to 9.9.2.1

Starting from ImageMaster 9.9.2.1 a new version of the authentication configuration is in use. The existing configuration will be migrated automatically during startup of ImageMaster, but it is strongly recommended verifying it after an upgrade to ImageMaster 9.9.2.1.

The new configuration format has the following changes:

  • userSearchScope: Object-level search is not available anymore.

  • userBaseTemplate: The {user} variable is not available anymore.

  • userFilter: The {user} variable is not available anymore.

  • “userNameAttribute” is a new required attribute. When searching for a user by login, a check based on this attribute will automatically be appended to “userFilter”.

  • The namespace was updated to "http://www.tsystems.com/ima/9.9/authenticationconfig" (contrary to "http://www.tsystems.com/ima/9.7/authenticationconfig" used since 9.7.2.2).

  • “userGroupMappings” allows a configuration of optional attributes for the new feature “user groups”.