9.4.2. Configuring LDAP Mapping

LDAP mapping is configured in the EKM server configuration file: EKM_HOME/conf/ekm.xml.

To enable LDAP mapping, define the ldap configuration element, as shown below. Values for each setting are in bold:

<ldap>
  <authBindDN>uid=ekmuser,ou=users,dc=yourdomain,dc=com</authBindDN>
  <authBindCredential>password</authBindCredential>
  <baseCtxDN>ou=users,dc=yourdomain,dc=com</baseCtxDN>
  <userFilter>mail={USERNAME}</userFilter>
  <ekmUserNameAttribute>uid</ekmUserNameAttribute>
  <ekmFirstNameAttribute>givenName</ekmFirstNameAttribute>
  <ekmLastNameAttribute>sn</ekmLastNameAttribute>
  <ekmEmailAttribute>mail</ekmEmailAttribute>
  <ekmTitleAttribute>title</ekmTitleAttribute>
  <ekmPhoneAttribute>telephoneNumber</ekmPhoneAttribute>
  <responseTimeout>60</responseTimeout>
  <searchTimeLimit>30</searchTimeLimit>
  <secure>false</secure>
  <secureType>SECURE</secureType>
  <serverHost>ldapserver.yourdomain.com</serverHost>
  <serverPort>389</serverPort>
</ldap>

If you are also using LDAP for authentication (see Configuring Login Authentication), it is recommended that you configure LDAP mapping with similar settings so that the same LDAP data will be used. This is recommended, but not required.

The only requirement is that when searching under the specified baseCtxDN, a unique entry matching the userFilter is found, and this entry has an attribute of the name specified by ekmUserNameAttribute.


Important:  If more than one user entry is found that matches the filter, the EKM login will fail. It is important to set up the userFilter carefully so that this is avoided.


The following configuration settings control the behavior of LDAP mapping:

authBindDN

(optional) Specifies the identity to use when connecting to the LDAP server to perform searches. To connect anonymously, comment out or delete this option as well as the authBindCredential option.

authBindCredential

(optional) Specifies the password to use when connecting to the LDAP server to perform searches. Include this option only when you have specified a value for authBindDN.

baseCtxDN

Specifies the DN (LDAP distinguished name) of the entry in your LDAP server under which to perform searches. If using LDAP authentication, it is recommended that you use the same value used in that module. It may not be named baseCtxDN, but it is the setting that specifies where to search in the directory.

userFilter

Specifies the LDAP search filter used to find the EKM user entry for the user logging in. The default value of this setting is mail={USERNAME}. {USERNAME} is a special token that is replaced with the authentication identity that is attempting to log in — do not alter it. The search scope is SUB and the base DN for the search is defined by baseCtxDN.

The format of this search filter ranges from simple to complex based on RFC 4515 Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters.

The default value mail={USERNAME} will match any entry with a mail attribute equal to the username token.

Below is an example filter that will match only entries of type inetOrgPerson where either the mail or uid attribute matches the username token:

(&(|(mail={USERNAME})(uid={USERNAME}))(objectClass=inetOrgPerson))

Important:
  • You must include the attribute that contains the authentication identity in this filter.

  • Be careful when choosing an attribute to match against {USERNAME}. Each ID must be unique. If more than one user entry is matched with the search, the EKM login will fail.


ekmUserNameAttribute

Specifies the attribute containing the name to be used as the EKM user name. When an entry is found under the baseCtxDN entry (ou=ekm,dc=example,dc=com in Example 9.1: LDAP Mapping) that is matched by the userFilter, the value of the ekmUserNameAttribute attribute of that entry will be used for the EKM user name in place of what was entered at login.

ekmFirstNameAttribute

Specifies the attribute containing the first name of the EKM user.

ekmLastNameAttribute

Specifies the attribute containing the last name of the EKM user.

ekmEmailAttribute

Specifies the attribute containing the email address of the EKM user.

ekmTitleAttribute

Specifies the attribute containing the phone number of the EKM user.

ekmPhoneAttribute

Specifies the attribute containing the title of the EKM user.

responseTimeout

Specifies the maximum length of time in seconds that an operation should be allowed to block while waiting for a response from the server. A value of 0 indicates that there should be no timeout.

searchTimeLimit

Specifies the maximum length of time in seconds that the server should spend processing a search request. A value of 0 indicates that there should be no limit. Only one search is performed for each mapping. See userFilter above for details.

secure

Specifies if the connection should be secure. It true, it will be secure and use the encryption method specified by secureType. If false, the connection will not be secure.

secureType

Specifies the encryption method for the secure connection. Supported values are SSL and TLS. Use SSL for an LDAPS connection. Use TLS when using the extended operation StartTLS. Both SSL and TLS will require the configuration of the LDAP server with an appropriate certificate.

serverHost

Specifies the fully-qualified hostname where the LDAP server is running. If the EKM server is a single-node server and the LDAP server is on the same server host as the EKM server, you may keep the default value of localhost. For any other configuration, including any multi-node EKM server, do not use localhost.

serverPort

Specifies the port on which the LDAP server is listening.

Standard ports include:

  • LDAP: 389/10389

  • SSL: 636/10636

  • TLS: 389/10389

Example 9.1:  LDAP Mapping

In this example, LDAP mapping is configured as follows in EKM_HOME/conf/ekm.xml:

<ldap>
  ...
  <baseCtxDN>ou=ekm,dc=example,dc=com</baseCtxDN>
  <userFilter>mail={USERNAME}</userFilter>
  <ekmUserNameAttribute>uid</ekmUserNameAttribute>
  ...
</ldap>

A user logs in to EKM as joe.adams@example.com.

EKM uses LDAP mapping to search under ou=ekm,dc=example,dc=com for any entries where mail={USERNAME}, which expands to mail=joe.adams@example.com. The search matches the entry shown below. It then gets the value of the uid attribute for the entry, as specified by ekmUserNameAttribute. This value is jadams. Therefore, the user is logged in with the EKM user name jadams in place of joe.adams@example.com.

dn: uid=jadams,ou=Users,ou=ekm,dc=example,dc=com
objectClass: top
objectClass: inetOrgPerson
objectClass: person
objectClass: organizationalPerson
cn: Joe Adams
sn: Adams
mail: joe.adams@example.com
uid: jadams


Release 18.2 - © ANSYS, Inc. All rights reserved.