[id='ldap-security-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.
====

[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 attribute that validates passwords with the `user-password-mapper` element.

[NOTE]
====
You cannot use endpoint authentication mechanisms that perform hashing with the `direct-verification` attribute.

Because Active Directory does not expose the `password` attribute you can use the `direct-verification` attribute only and not the `user-password-mapper` element.
As a result you must use the `BASIC` authentication mechanism with the REST endpoint and `PLAIN` with the Hot Rod endpoint to integrate with Active Directory Server.
A more secure alternative is to use Kerberos, which allows the `SPNEGO`, `GSSAPI`, and `GS2-KRB5` authentication mechanisms.
====

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`.

[discrete]
== LDAP realm configuration

.XML
[source,xml,options="nowrap",subs=attributes+,role="primary"]
----
include::xml/server_ldap_realm.xml[]
----

.JSON
[source,json,options="nowrap",subs=attributes+,role="secondary"]
----
include::json/server_ldap_realm.json[]
----

.YAML
[source,yaml,options="nowrap",subs=attributes+,role="secondary"]
----
include::yaml/server_ldap_realm.yaml[]
----
