LDAP user authentication

Determine which mode you want to use. The ldap realm supports two modes of operation, a user search mode and a mode with specific templates for user DNs.

LDAP user search is the most common mode of operation. In this mode, a specific user with permission to search the LDAP directory is used to search for the DN of the authenticating user based on the provided username and an LDAP attribute. Once found, the user is authenticated by attempting to bind to the LDAP server using the found DN and the provided password.

If your LDAP environment uses a few specific standard naming conditions for users, you can use user DN templates to configure the realm. The advantage of this method is that a search does not have to be performed to find the user DN. However, multiple bind operations might be needed to find the correct user DN.

To configure an ldap realm with user search:

To configure an ldap realm with user DN templates:

(Optional) Configure how the security features interact with multiple LDAP servers.

The load_balance.type setting can be used at the realm level. The Elasticsearch security features support both failover and load balancing modes of operation. See LDAP realm settings.

Map LDAP groups to roles.

The ldap realm enables you to map LDAP users to roles via their LDAP groups, or other metadata. This role mapping can be configured via the add role mapping API or by using a file stored on each node. When a user authenticates with LDAP, the privileges for that user are the union of all privileges defined by the roles to which the user is mapped.

Within a mapping definition, you specify groups using their distinguished names. For example, the following mapping configuration maps the LDAP admins group to both the monitoring and user roles, and maps the users group to the user role.

Configured via the role-mapping API:

resp = client.security.put_role_mapping(
    name="admins",
    roles=[
        "monitoring",
        "user"
    ],
    rules={
        "field": {
            "groups": "cn=admins,dc=example,dc=com"
        }
    },
    enabled=True,
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "admins",
  roles: ["monitoring", "user"],
  rules: {
    field: {
      groups: "cn=admins,dc=example,dc=com",
    },
  },
  enabled: true,
});
console.log(response);

PUT /_security/role_mapping/admins
{
  "roles" : [ "monitoring" , "user" ],
  "rules" : { "field" : {
    "groups" : "cn=admins,dc=example,dc=com" 
  } },
  "enabled": true
}

resp = client.security.put_role_mapping(
    name="basic_users",
    roles=[
        "user"
    ],
    rules={
        "field": {
            "groups": "cn=users,dc=example,dc=com"
        }
    },
    enabled=True,
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "basic_users",
  roles: ["user"],
  rules: {
    field: {
      groups: "cn=users,dc=example,dc=com",
    },
  },
  enabled: true,
});
console.log(response);

PUT /_security/role_mapping/basic_users
{
  "roles" : [ "user" ],
  "rules" : { "field" : {
    "groups" : "cn=users,dc=example,dc=com" 
  } },
  "enabled": true
}

Or, alternatively, configured via the role-mapping file:

monitoring: 
  - "cn=admins,dc=example,dc=com" 
user:
  - "cn=users,dc=example,dc=com" 
  - "cn=admins,dc=example,dc=com"

For more information, see Mapping LDAP groups to roles and Mapping users and groups to roles.

(Optional) Configure the metadata setting on the LDAP realm to include extra fields in the user’s metadata.

By default, ldap_dn and ldap_groups are populated in the user’s metadata. For more information, see User metadata in LDAP realms.

The example below includes the user’s common name (cn) as an additional field in their metadata.

xpack:
  security:
    authc:
      realms:
        ldap:
          ldap1:
            order: 0
            metadata: cn