[id='ldap-realms_{context}']
= LDAP Realms
LDAP realms connect to LDAP servers, such as OpenLDAP, Red Hat Directory
Server, Apache Directory Server, or Microsoft Active Directory, to authenticate
users and obtain membership information.

[NOTE]
====
LDAP servers can have different entry layouts, depending on the type of server and deployment.
It is beyond the scope of this document to provide examples for all possible configurations.
====

.Endpoint authentication mechanisms

When you configure {brandname} Server to use an LDAP realm, you can configure endpoints to use the following authentication mechanisms:

* Hot Rod (SASL): `PLAIN`, `+DIGEST-*+`, and `+SCRAM-*+`
* REST (HTTP): `Basic` and `Digest`

.LDAP realm configuration
[source,xml,options="nowrap",subs=attributes+]
----
include::config_examples/server_ldap_realm.xml[]
----

[IMPORTANT]
====
The principal for LDAP connections must have necessary privileges to perform
LDAP queries and access specific attributes.
====

As an alternative to verifying user credentials with the `direct-verification` attribute, you can specify an LDAP password with the `user-password-mapper` element.

The `rdn-identifier` attribute specifies an LDAP attribute that finds the user entry based on a provided identifier, which is typically a username; for example, the `uid` or `sAMAccountName` attribute.
Add `search-recursive="true"` to the configuration to search the directory recursively.
By default, the search for the user entry uses the `(rdn_identifier={0})` filter.
Specify a different filter with the `filter-name` attribute.

The `attribute-mapping` element retrieves all the groups of which the user is a member. There are typically two ways in which membership information is stored:

* Under group entries that usually have class `groupOfNames` in the `member` attribute. In this case, you can use an attribute filter as in the preceding example configuration. This filter searches for entries that match the supplied filter, which locates groups with a `member` attribute equal to the user's DN. The filter then extracts the group entry's CN as specified by `from`, and adds it to the user's `Roles`.
* In the user entry in the `memberOf` attribute. In this case you should use an attribute reference such as the following:
+
`<attribute-reference reference="memberOf" from="cn" to="Roles" />`
+
This reference gets all `memberOf` attributes from the user's entry, extracts the CN as specified by `from`, and adds them to the user's `Roles`.
