LDAP and Active Directory

This page contains the following sections:

Activating LDAP for user management
Conditions
Connection Settings
Search Settings
Role Mapping
Group Mapping
Attribute Mapping
Import
Export
Microsoft Active Directory Service (ADS)
- Simple/None Authentication
- Kerberos Authentication

It is possible to integrate existing LDAP directories as a source of user information. The LDAP directory then replaces the internal user database and is used for the purpose of authenticating users. When using the LDAP adapter, the built-in user manager enters passive mode. This means that the user information from LDAP is displayed, but cannot be changed. Existing LDAP applications can be used for the purpose of user management.

Activating LDAP for user management

Perform the following steps, to enable LDAP for user management and begin configuration:

set the configuration property usermgr.type to either ldap or hybrid.
sign in as super administrator (smadmin) and click Settings → LDAP/ADS Configuration.

Conditions

To ensure that the LDAP integration works smoothly, the technical user, or in the case of an anonymous connection, the anonymous user, must have full reading permissions on the section of the LDAP tree that is to be searched.

In addition to the explicit assignment of LDAP attributes or nodes to group names, it is possible to select the implicit assignment of users to groups. In this case, the group of a user is derived from the name of the parent node in the LDAP. To search for implicit groups, the operational attributes hasSubordinates and numSubordinates are used. If your LDAP system does not support these attributes then the objectClass values of groups are detected by the parent node of the first user. The implicit groups resolving can be customized using the connection properties de.conterra.implicitgroups.enabled and de.conterra.hassubordinates.enabled.

Connection Settings

In this view, the configuration parameters for the connection to the LDAP are configured:

You can define the following properties:

java.naming.provider.url (required)

The value of this property is the connection URL to the LDAP, for example ldaps://myhost.mydomain.eu

java.naming.security.principal (optional)

This is the name of the technical user used for setting up the connection and searching in the LDAP. The value is optional and depends on the method of authentication used.

java.naming.security.credentials (optional)

This property describes the password of the technical user. The value is optional and depends on the method of authentication used.

java.naming.security.authentication (optional)

This property describes the type of authentication. The default value is simple. Available options are

none: The Administrator accesses the LDAP as an anonymous user, which means he does not necessarily need to be a technical user.
simple: Requires a technical user that can be used by the Administrator to authenticate against the LDAP. This technical user must be allowed to search in the LDAP. The authentication uses the "simple bind" method.
GSSAPI: Use Kerberos authentication. This means that a technical user is required that can be used by the Administrator to authenticate against the LDAP. The Administrator first logs into the domain controller to obtain a Kerberos ticket. With this ticket, the Administrator is able to authenticate itself against the LDAP. The technical user must be permitted to search in the LDAP.

java.naming.factory.initial (optional)

This is the internal property, and it must have the value com.sun.jndi.ldap.LdapCtxFactory.

de.conterra.provider.alternatives (optional)

The value of this property is a comma separated list of fallback connection URLs, for example ldaps://myhost1.mydomain.eu,ldaps://myhost2.mydomain.eu.

de.conterra.implicitgroups.enabled (optional)

Enables the detection of possible parent nodes of users (implicit groups). Default value is true. Allowed values are true or false.

de.conterra.hassubordinates.enabled (optional)

Allows the use of 'hasSubOrdinates' in ldap queries. Default value is true. Allowed values are true or false.

If the LDAP is using an SSL certificate not signed by an official certificate authority you need to import the SSL certificate as described in Use of SSL Certificates.

Alternatively you can tie to the Windows certificate store by adding the Java VM option -Djavax.net.ssl.trustStoreType=WINDOWS-ROOT. More information can be found at Use Windows Trust Store.

Search Settings

This is where the parameters for the user search are defined. Based on these parameters, the DNs of the users are derived from the usernames and a search is defined that deduces the user’s node in the LDAP. The following values can be defined:

Base DN

Defines the root node of the LDAP search from which the search for users is made, for example CN=Users,DC=Company,DC=Net.

Filter

Defines a general filter expression for recognizing user nodes; make it as precise as possible (objectClass=user).

Match

Defines an additional filter expression to be compared with the username entered by the user with an attribute in the user node. The name entered by the user can be referenced with {0}. This filter expression must be unambiguous to allow the correct user node to be identified in the LDAP, for example userPrincipalName={0}.

Scope

Defines the level of the search in the LDAP. Possible values are:

base: the search is limited to the node identified with the base DN.
onelevel: The search includes the direct offspring nodes of the node defined with the Base DN.
subtree: The search takes in the entire tree section of the node identified with the Base DN.

Authentication

Defines an individual user’s type of login for password authentication. Possible values are:

simple: the data entered by the user (username and password) is validated with respect to the LDAP via a simple-bind authentication.
GSSAPI: the data entered by the user (username and password) is validated by Kerberos authentication at the domain controller. If this authentication is successful, only the user data in the LDAP/ADS is searched.

Role Mapping

This is where the mapping of a user’s attribute values in the LDAP to a role name within the application is defined. The definition corresponds with the statement "If attribute X exists and possesses the value Y, then the user possesses the role Z". Examples of typical role attribute are a user’s memberOf attributes. For LDAP attribute values, '*' is allowed as a wildcard. This allows the mapping of roles to email domains of users, such as mapping '*.gov.uk' to the role 'Government'.

Group Mapping

The configuration in this dialog lays down how an attribute value or distinguished name (DN) of a user node enables the mapping to a group. Various types of group mapping can be used. The following types are distinguished:

Mapping of a group by way of its LDAP attribute and its value.

The interpretation of this mapping corresponds with the role mapping, which means if the attribute 'X' exists and has the value 'Y', the use is mapped to the group 'Z'. As with roles, the attribute memberOf is commonly used in group mappings.
Mapping of a group by stating the base DN.

In this case, the group mapping can take place on the basis of a parent node of a user node. For example, if a user node the DN cn=Lex Luthor,ou=Villains,dc=dev,dc=conterra,dc=com then a group mapping can be made on the basis of the direct parent node ou=Villains,dc=dev,dc=conterra,dc=com or a higher parent node dc=dev,dc=conterra,dc=com. These mappings can also be mixed. If several valid mappings exist for a user, then the more precise or specific mapping is used.
Implicit mapping by deriving the group from the direct parent node of the user node.

This type is a mapping based on the user’s DN, whereby the group is given the name of the direct parent node. This mapping is always active internally and is overwritten by the explicit configuration of the other mapping types.

These three types of mapping can be mixed with each other, but the following order has to be borne in mind:

Attribute-based mappings have the greatest weighting and overwrite all other mappings.
Base DN-based mappings overwrite the implicit group mapping.
Implicit group mappings have the lowest weighting and can be overwritten by all other types.

Attribute Mapping

It is possible to transfer LDAP attribute values into the SAML token generated by the authentication service. Some values are used directly for the display within the Administrator (such as first name and email address). All other values can be automatically transferred into the SAML token by making an attribute mapping. They are then available for use in the applications. The dialog distinguishes between obligatory and optional attribute mappings.

In the case of obligatory attribute mappings, assignments are defined that the Administrator requires for displaying user information in the Users tab. These values already have an internal SAML attribute ID, so this does not need to be defined here. If an SAML attribute ID is still issued, the attribute is incorporated twice in the SAML ticket.

With optional attribute mappings, it is possible to make further LDAP attribute assignments. These assignments will, however, only be visible in the SAML tickets issued by the WAS and cannot be viewed in the user manager of the Administrator. For optional attribute mappings, it is necessary to issue an SAML attribute ID, under which the attribute is incorporated in the SAML ticket.

Import

Use the Import dialog to import a previously exported file of LDAP settings.

Export

Use the export dialog to export the current LDAP settings into an XML file.

Microsoft Active Directory Service (ADS)

This section describes the technical requirements for ADS support. In general, an ADS is configured in the same manner as a normal LDAP, but in the case of Kerberos authentication, a number of additional steps are necessary.

Simple/None Authentication

In the case of ADS integration with simple or anonymous, authentication is exactly the same as with other LDAP systems. If the match sAMAccountName={0} is used in the search configuration, the user can log on with his username without the domain suffix, for example testuser instead of testuser@conterra.de. If userPrincipalName={0} is used, the exact domain name is needed.

Examples of search settings

base="DC=Test,DC=CONTERRA,DC=Net"
filter="(objectClass=user)"
match="sAMAccountName={0}"
scope="subtree"
authentication="simple"

Kerberos Authentication

To connect an ADS via Kerberos authentication an extended configuration of the JVM of the Tomcat is necessary. Create a krb5.conf file that contains the possible domains and domain controller hostnames.

The following example of a krb5.conf files shows the configuration of a Kerberos realm TEST.CONTERRA.DE.

# For detailed configuration possibilities see:
# http://www.mit.edu/~kerberos/krb5-1.5/krb5-1.5.3/doc/krb5-admin/krb5.conf.html#krb5.conf

[libdefaults]
# defines the default realm, only users of this realm are
# allowed to login without full domain name
default_realm = TEST.CONTERRA.DE

[domain_realm]
# provides a translation from a domain name or hostname
# to a Kerberos realm name
.test.conterra.de = TEST.CONTERRA.DE

[realms]
# defines the possible realms,
# kdc is the hostname of the domain controller used
# for the kerberos authentication
TEST.CONTERRA.DE = {
kdc = test.conterra.de
}

The path to the krb5.conf must be stated as a parameter when JVM or Tomcat is started; the following parameter then needs to be configured:

java.security.krb5.conf=[path_to_krb5.conf]

The configuration of this parameter follows the pattern of proxy settings.

The Kerberos configuration applies to the entire Tomcat process and thereby to all web applications run in it. It is possible to define several Kerberos realms in the krb5.conf file, to allow different domain controllers to be used.

To switch on Kerberos authentication in the LDAP configuration of the Administrator, it is necessary to select GSSAPI subsequently as the method of authentication. If you do not want to define a technical user when defining the connection settings, the connection to the ADS is made with the user who initiated the Tomcat process. This user must possess appropriate search rights for the ADS.

Authentication using the process owner’s identity

Due to system configuration there might be problems to get the Kerberos Ticket Granting Ticket.

To ensure that the user can sign in successfully, the property Match must have the value userPrincipalName={0} and the property Authentication must have the value GSSAPI in the search configuration. A user always logs in (with password authentication) with the Kerberos domain controller. Successful login results in a Kerberos ticket. This Kerberos ticket contains the user’s full domain name. It is with this domain name that the Administrator performs the search for the user node in the ADS. For this reason, the attribute userPrincipalName must be used as the Match. Only when the user node has been found in the ADS is the login successful.

Example search settings

base="DC=Test,DC=CONTERRA,DC=Net"
filter="(objectClass=user)"
match="userPrincipalName={0}"
scope="subtree"
authentication="GSSAPI"

Known error messages with Kerberos

Caused by: KrbException: Server not found in Kerberos database (7)

The DNS lookup for the name of the ADS is not correct. Make an appropriate entry in the hosts file of the system.

Example

172.22.180.157	your.fullqualified.adshostname

Caused by: KrbException: Cannot get kdc for realm <your realm>

This error indicates that the technical user has been configured with an incorrectly spelt realm or domain name. The realm name must be written in exactly the same way as in the krb5.conf file.

Example: testuser@TEST.CONTERRA.DE

It is good practice to write the entire realm name in either lower case or upper case letters.

Caused by: KrbException: Fail to create credential. (63) - No service creds

This error occurs when the Kerberos system attempts to assign the LDAP/ADS to another realm as that of the technical user. This results in the problem of a missing "domain realm" entry for the domain of the ADS.

Example: test.conterra.de = TEST.CONTERRA.DE