9.4.2. Configuring LDAP Mapping

Engineering Knowledge Manager

Installation Guide | Chapter 9: Configuring Login Authentication and Access Settings | 9.4. LDAP Mapping |

9.4.1. When to Use LDAP Mapping |  | Chapter 10: Installing and Configuring EnginFrame
Prev |  | Next

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

Contains proprietary and confidential information of ANSYS, Inc. and its subsidiaries and affiliates.

Prev | Up / Contents | Next

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