LDAP

Use LDAP to authenticate users and map directory groups to Analytics Hub roles. The built-in connector supports Microsoft Active Directory and performs a bind using a DNClosed A distinguished name (DN) uniquely identifies an entry in an LDAP/X.500 directory by specifying a sequence of relative distinguished names (attribute=value pairs) from the entry up to the directory root. It’s written as a comma-separated string—for example: cn=Alice,ou=People,dc=keyexample,dc=com—with the specific attributes defined by the directory’s schema. constructed from your configuration and the username entered at sign-in. On successful bind, the system reads user attributes (for example, display name and group membership) and grants access based on your authorized group to role mappings.

Note:  CipherInsights does not write to LDAP. All user and group changes must be made in your directory.
Tip:  Where to find this in the Analytics Hub portal:
Admin Area → Access Control → LDAP
How it Works

The basic LDAP login flow works as follows:

  1. The user enters a username and password on the Analytics Hub portal sign-in page.
  2. The system builds a Distinguished Name (DN) using your LDAP settings and the supplied username, then attempts a bind.
  3. If the bind succeeds, the system queries the user’s memberOf (group) attributes.

  4. Returned groups are matched against your Authorized Groups list to assign roles in the Analytics Hub portal.

    • If the user is not in any authorized group, access is denied.

    • If the user matches multiple groups, the user receives the union of mapped roles.

Example:  If your Base DN is dc=keyexample,dc=com and users live under cnClosed A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com).=Users, a typical user DN would be: cn=John Smith,cn=Users,dc=keyexample,dc=com

Your environment may use a different structure; configure the DN pattern to match your directory.

Configure LDAP

To configure LDAP:

  1. Browse to Admin Area → Access Control → LDAP and complete the fields as per the table, below.

    Figure 68: Configure LDAP

  2. At the bottom of the form click Commit to save.

Table 5: LDAP Settings

Section Field Description Default
General Enable

Turn LDAP authentication on or off. When enabled, the system uses the LDAP settings on this page for sign-in.

(Server certificate checks are controlled by Validate SSL certificates and Trusted CA, not by this toggle.)

 Disabled
General Server

LDAP directory endpoint as a URI (scheme + host + optional port).

Examples

ldaps://ad1.keyexample.com:636 (LDAPS)
ldap://ad1.keyexample.com:389 (use with StartTLS, if configured)
Tip:  Use a hostname that matches the server certificate; avoid raw IPs when using TLS.
  
General Native takes precedence (if enabled)

Controls the order of authentication when both Native (local) and LDAP are enabled.

  • Enabled (recommended): If a matching local user exists, authenticate/authorize locally and do not query LDAP for that login. If no local account matches, fall back to LDAP.

  • Disabled: Always query LDAP for logins, even when a matching local account exists; local accounts won’t short-circuit LDAP.

Note:  Enabling this setting is useful for break-glass local admin access during LDAP outages.
 Enabled
General Session timeout (seconds) Number of seconds that must elapse before the application logs out the user automatically. 3600
Certification Certificate based authentication

Whether to authenticate to LDAP using a client certificate (mutual TLS).

  • Enabled: The system presents a client certificate during the TLS handshake and (directory-dependent) may authenticate via SASL EXTERNAL instead of a password.

    Requirements:

    • LDAPS or StartTLS

    • The LDAP server must trust your issuing CA.

    • You must provide the client certificate and private key (fields vary by build).

  • Disabled: The system uses a standard bind with Manager DN and Manager password.

 Enabled
Certification Validate SSL certificates

Whether to validate the SSL certificate of the LDAP server.

  • Enabled (recommended): The system verifies the LDAP server’s certificate and hostname against trusted CAs. Use the Trusted CA field if your directory uses a private CA.
  • Disabled: Certificate checking is skipped—connections may succeed but are not secure (susceptible to MITM). Use only for troubleshooting.
 Enabled
Certification OCSP check When enabled, verifies the revocation status of the LDAP server’s certificate using the Online Certificate Status Protocol (OCSP). Requires outbound access to the CA’s OCSP responder; if unreachable, the outcome (fail-open or fail-closed) follows your system’s policy. Disabled
Certification Trusted CA

Paste the certificate authority (CA) certificate(s) used to verify the LDAP server’s TLS certificate when using LDAPS or StartTLS.

  • Provide the issuing CA chain (intermediate(s) then root) in PEM (base-64) format.
  • Do not paste the server certificate or any private key.
  • Leave blank if your LDAP server’s certificate is issued by a public CA already trusted by the system.
  
Attributes Base search DN

Distinguished Name that serves as the root of all LDAP searches (users and groups).

Example

ou=Corp,dc=example,dc=com or simply dc=example,dc=com
If left blank, the system attempts to discover the default naming context from the directory (RootDSE) and use that as the base.
Tip:  Narrowing this to the OU where your users/groups live improves performance.
  
Attributes Manager DN

Distinguished Name (DN) of the LDAP service account the system uses to bind to the directory and perform user/group lookups. Also called Bind DN.

  • Use a read-only account with search access under your Base search DN (and to the OUs where users and groups live).

  • Required when anonymous bind is disabled (most environments).

  • Paired with Manager password.

Examples

  • Active Directory: CN=svc_cipher,OU=Service Accounts,OU=IT,DC=keyexample,DC=com

  • OpenLDAP: uid=svc_cipher,ou=service,dc=keyexample,dc=com

  
Attributes Manager password

Password for the LDAP Manager DN (Bind DN) account used to connect to the directory and perform user/group lookups. Required when anonymous bind is not allowed (most environments).

Important:  Keyfactor highly recommends that you use strong passwords for any accounts, certificates, or files related to CipherInsights and associated products, especially when these have elevated or administrative access or contain sensitive information. A strong password has at least 12 characters (more is better) and multiple character classes (lowercase letters, uppercase letters, numeral, and symbols). Ideally, each password would be randomly generated. Avoid password re-use.
  
Attributes User attribute

Name of the attribute on the user object that the system matches against the login value during lookup. This is the field used in your user search (e.g., it’s the left side of (<attribute>=$1) in the filter). Enter a single attribute name—not a DN or full filter.

  • Use cn only if users sign in with their common name (e.g., John Smith) and it’s unique/stable in your directory.

  • In most environments, set this to the actual login attribute:

    • Active Directory: sAMAccountName (short name) or userPrincipalName (e.g., jsmith@keyexample.com)

    • OpenLDAP / generic: uid

    • Email-as-login: mail

    This attribute must align with your User search filter. For example:

    • If User attribute = sAMAccountName, use a filter like (&(objectClass=user)(sAMAccountName=$1)).

    • If User attribute = uid, use (&(objectClass=inetOrgPerson)(uid=$1)).

 cn
Attributes User name attribute

LDAP attribute on the user object that holds the account’s login identifier (the “username” you want shown in the UI and used in audit logs). Enter just the attribute name.

Common Choices

  • Active Directory: sAMAccountName (short name) or userPrincipalName (UPN like jsmith@keyexample.com)

  • OpenLDAP / generic: uid

  • If your org logs in with email: mail

Tip:  Pick the same attribute users type at sign-in (aligns with your User search filter). It should be unique within your directory scope and consistently populated. This is not the friendly/full name—use Display name for that.
  
Attributes User search filter

LDAP filter used to locate the user entry during login. The filter is evaluated under the Base search DN and should match exactly one user.

Examples

  • Active Directory (objectClass):

    (&(objectClass=user)(|(sAMAccountName=$1)(userPrincipalName=$1)))

  • Active Directory (objectCategory):

    (&(objectCategory=User)(|(sAMAccountName=$1)(userPrincipalName=$1)))

  • OpenLDAP / generic (uid):

    (&(objectClass=inetOrgPerson)(uid=$1))

  • OpenLDAP (mail as login):

    (&(objectClass=inetOrgPerson)(mail=$1))

  • OpenLDAP / generic (uid or mail):

    (&(objectClass=inetOrgPerson)(|(uid=$1)(mail=$1)))
Tip:  Include an objectClass to keep searches fast (e.g., user, person, inetOrgPerson). Make sure the attribute you match is the one users actually type at login. If users can type either name or name@keyexample.com, use an OR in the filter (see the AD example above).
  
Attributes Group attribute

Name of the LDAP attribute used to determine a user’s group membership. What it points to depends on how you retrieve membership:

  • Membership on user = Enabled: Attribute on the user that lists their groups (e.g., memberOf).

  • Membership on user = Disabled: Attribute on the group that lists its members (e.g., member, uniqueMember, or memberUid), used by the Group search filter.

Common Examples

  • Active Directory: memberOf (user), member (group)

  • OpenLDAP groupOfNames: member (DN)

  • OpenLDAP groupOfUniqueNames: uniqueMember (DN)

  • posixGroup: memberUid (username)

Note:  Enter a single attribute name (not a DN or filter). Make sure your Group search filter matches the attribute style you use (DN vs. username).
  
Attributes Membership on user

Controls where the system reads a user’s group memberships from.

  • Enabled: Read groups directly from the user object (for example, memberOf). Recommended for directories that populate group membership on users (e.g., Active Directory). The Group search filter option is not used in this mode.

  • Disabled: Do not read groups from the user object. Instead, find groups by searching group entries with the Group search filter (e.g., groups where member, uniqueMember, or memberUid matches the user).

Tip:   If sign-in succeeds but no roles are assigned, either enable this setting (if your directory exposes memberOf) or leave it disabled and verify that your Group search filter returns the expected groups.
 Enabled
Attributes Group search filter

LDAP filter used to find group objects that contain the user when the Membership on user option is disabled. The filter is evaluated under the Base search DN.

Use the attributes your directory stores on groups (e.g., member, uniqueMember, or memberUid).

Examples

  • Active Directory / group (member contains DN):

    (&(objectClass=group)(member={userDN}))

  • groupOfNames / generic LDAP:

    (&(objectClass=groupOfNames)(member={userDN}))

  • posixGroup (member by username):

    (&(objectClass=posixGroup)(memberUid={username}))
Note:  This filter typically matches direct group membership only. Nested/indirect membership requires directory-specific features and may not be evaluated by a simple filter. For performance, include objectClass in the filter and scope searches to the OU where groups live.
  
Attributes Connection timeout Number of milliseconds before timing out an attempted connection to the LDAP server. 6000
Attributes Display name

Name of the attribute on the user object that holds the user’s friendly name as it should appear in the UI. Enter a single attribute name (no DN).

Common Choices

  • Active Directory: displayName (recommended), or cn if displayName isn’t populated.

  • OpenLDAP / generic LDAP: cn (often the full name), or displayName if your schema populates it.

Examples

  • displayName: Martha Jones

  • cn: Martha Jones

  • givenName (Less typical): Martha (first name only)

  • mail (Not really a display name, but supported if desired): martha.jones@keyexample.com

Tip:  Use ldapsearch (or your directory browser) to confirm which attribute is populated for your users before choosing.
  
Role to Group Mapping Administrator groups Comma-separated list of groups to associate with the Administrator role (see Roles).  
Role to Group Mapping Operator groups Comma-separated list of groups to associate with the Operator role (see Roles).  
Role to Group Mapping Unrestricted groups Comma-separated list of groups to associate with the Unrestricted role (see Roles).  
Role to Group Mapping User groups Comma-separated list of groups to associate with the User role (see Roles).