spring-security/docs/modules/ROOT/pages/servlet/appendix/namespace/ldap.adoc

[[nsa-ldap]]
= LDAP Namespace Options
LDAP is covered in some details in xref:servlet/authentication/passwords/ldap.adoc#servlet-authentication-ldap[its own chapter].
We will expand on that here with some explanation of how the namespace options map to Spring beans.
The LDAP implementation uses Spring LDAP extensively, so some familiarity with that project's API may be useful.


[[nsa-ldap-server]]
== Defining the LDAP Server using the
`<ldap-server>` Element
This element sets up a Spring LDAP `ContextSource` for use by the other LDAP beans, defining the location of the LDAP server and other information (such as a username and password, if it doesn't allow anonymous access) for connecting to it.
It can also be used to create an embedded server for testing.
Details of the syntax for both options are covered in the xref:servlet/authentication/passwords/ldap.adoc#servlet-authentication-ldap[LDAP chapter].
The actual `ContextSource` implementation is `DefaultSpringSecurityContextSource` which extends Spring LDAP's `LdapContextSource` class.
The `manager-dn` and `manager-password` attributes map to the latter's `userDn` and `password` properties respectively.

If you only have one server defined in your application context, the other LDAP namespace-defined beans will use it automatically.
Otherwise, you can give the element an "id" attribute and refer to it from other namespace beans using the `server-ref` attribute.
This is actually the bean `id` of the `ContextSource` instance, if you want to use it in other traditional Spring beans.


[[nsa-ldap-server-attributes]]
=== <ldap-server> Attributes

[[nsa-ldap-server-mode]]
* **mode**
Explicitly specifies which embedded ldap server should use. Values are `apacheds` and `unboundid`. By default, it will depends if the library is available in the classpath.

[[nsa-ldap-server-id]]
* **id**
A bean identifier, used for referring to the bean elsewhere in the context.


[[nsa-ldap-server-ldif]]
* **ldif**
Explicitly specifies an ldif file resource to load into an embedded LDAP server.
The ldif should be a Spring resource pattern (i.e. classpath:init.ldif).
The default is classpath*:*.ldif


[[nsa-ldap-server-manager-dn]]
* **manager-dn**
Username (DN) of the "manager" user identity which will be used to authenticate to a (non-embedded) LDAP server.
If omitted, anonymous access will be used.


[[nsa-ldap-server-manager-password]]
* **manager-password**
The password for the manager DN.
This is required if the manager-dn is specified.


[[nsa-ldap-server-port]]
* **port**
Specifies an IP port number.
Used to configure an embedded LDAP server, for example.
The default value is 33389.


[[nsa-ldap-server-root]]
* **root**
Optional root suffix for the embedded LDAP server.
Default is "dc=springframework,dc=org"


[[nsa-ldap-server-url]]
* **url**
Specifies the ldap server URL when not using the embedded LDAP server.


[[nsa-ldap-authentication-provider]]
== <ldap-authentication-provider>
This element is shorthand for the creation of an `LdapAuthenticationProvider` instance.
By default this will be configured with a `BindAuthenticator` instance and a `DefaultAuthoritiesPopulator`.
As with all namespace authentication providers, it must be included as a child of the `authentication-provider` element.


[[nsa-ldap-authentication-provider-parents]]
=== Parent Elements of <ldap-authentication-provider>


* xref:servlet/appendix/namespace/authentication-manager.adoc#nsa-authentication-manager[authentication-manager]



[[nsa-ldap-authentication-provider-attributes]]
=== <ldap-authentication-provider> Attributes


[[nsa-ldap-authentication-provider-group-role-attribute]]
* **group-role-attribute**
The LDAP attribute name which contains the role name which will be used within Spring Security.
Maps to the ``DefaultLdapAuthoritiesPopulator``'s `groupRoleAttribute` property.
Defaults to "cn".


[[nsa-ldap-authentication-provider-group-search-base]]
* **group-search-base**
Search base for group membership searches.
Maps to the ``DefaultLdapAuthoritiesPopulator``'s `groupSearchBase` constructor argument.
Defaults to "" (searching from the root).


[[nsa-ldap-authentication-provider-group-search-filter]]
* **group-search-filter**
Group search filter.
Maps to the ``DefaultLdapAuthoritiesPopulator``'s `groupSearchFilter` property.
Defaults to `+(uniqueMember={0})+`.
The substituted parameter is the DN of the user.


[[nsa-ldap-authentication-provider-role-prefix]]
* **role-prefix**
A non-empty string prefix that will be added to role strings loaded from persistent.
Maps to the ``DefaultLdapAuthoritiesPopulator``'s `rolePrefix` property.
Defaults to "ROLE_".
Use the value "none" for no prefix in cases where the default is non-empty.


[[nsa-ldap-authentication-provider-server-ref]]
* **server-ref**
The optional server to use.
If omitted, and a default LDAP server is registered (using <ldap-server> with no Id), that server will be used.


[[nsa-ldap-authentication-provider-user-context-mapper-ref]]
* **user-context-mapper-ref**
Allows explicit customization of the loaded user object by specifying a UserDetailsContextMapper bean which will be called with the context information from the user's directory entry


[[nsa-ldap-authentication-provider-user-details-class]]
* **user-details-class**
Allows the objectClass of the user entry to be specified.
If set, the framework will attempt to load standard attributes for the defined class into the returned UserDetails object


[[nsa-ldap-authentication-provider-user-dn-pattern]]
* **user-dn-pattern**
If your users are at a fixed location in the directory (i.e. you can work out the DN directly from the username without doing a directory search), you can use this attribute to map directly to the DN.
It maps directly to the `userDnPatterns` property of `AbstractLdapAuthenticator`.
The value is a specific pattern used to build the user's DN, for example `+uid={0},ou=people+`.
The key `+{0}+` must be present and will be substituted with the username.


[[nsa-ldap-authentication-provider-user-search-base]]
* **user-search-base**
Search base for user searches.
Defaults to "".
Only used with a 'user-search-filter'.

+

If you need to perform a search to locate the user in the directory, then you can set these attributes to control the search.
The `BindAuthenticator` will be configured with a `FilterBasedLdapUserSearch` and the attribute values map directly to the first two arguments of that bean's constructor.
If these attributes aren't set and no `user-dn-pattern` has been supplied as an alternative, then the default search values of `+user-search-filter="(uid={0})"+` and `user-search-base=""` will be used.


[[nsa-ldap-authentication-provider-user-search-filter]]
* **user-search-filter**
The LDAP filter used to search for users (optional).
For example `+(uid={0})+`.
The substituted parameter is the user's login name.

+

If you need to perform a search to locate the user in the directory, then you can set these attributes to control the search.
The `BindAuthenticator` will be configured with a `FilterBasedLdapUserSearch` and the attribute values map directly to the first two arguments of that bean's constructor.
If these attributes aren't set and no `user-dn-pattern` has been supplied as an alternative, then the default search values of `+user-search-filter="(uid={0})"+` and `user-search-base=""` will be used.


[[nsa-ldap-authentication-provider-children]]
=== Child Elements of <ldap-authentication-provider>


* <<nsa-password-compare,password-compare>>



[[nsa-password-compare]]
== <password-compare>
This is used as child element to `<ldap-provider>` and switches the authentication strategy from `BindAuthenticator` to `PasswordComparisonAuthenticator`.


[[nsa-password-compare-parents]]
=== Parent Elements of <password-compare>


* <<nsa-ldap-authentication-provider,ldap-authentication-provider>>



[[nsa-password-compare-attributes]]
=== <password-compare> Attributes


[[nsa-password-compare-hash]]
* **hash**
Defines the hashing algorithm used on user passwords.
We recommend strongly against using MD4, as it is a very weak hashing algorithm.


[[nsa-password-compare-password-attribute]]
* **password-attribute**
The attribute in the directory which contains the user password.
Defaults to "userPassword".


[[nsa-password-compare-children]]
=== Child Elements of <password-compare>


* xref:servlet/appendix/namespace/authentication-manager.adoc#nsa-password-encoder[password-encoder]



[[nsa-ldap-user-service]]
== <ldap-user-service>
This element configures an LDAP `UserDetailsService`.
The class used is `LdapUserDetailsService` which is a combination of a `FilterBasedLdapUserSearch` and a `DefaultLdapAuthoritiesPopulator`.
The attributes it supports have the same usage as in `<ldap-provider>`.


[[nsa-ldap-user-service-attributes]]
=== <ldap-user-service> Attributes


[[nsa-ldap-user-service-cache-ref]]
* **cache-ref**
Defines a reference to a cache for use with a UserDetailsService.


[[nsa-ldap-user-service-group-role-attribute]]
* **group-role-attribute**
The LDAP attribute name which contains the role name which will be used within Spring Security.
Defaults to "cn".


[[nsa-ldap-user-service-group-search-base]]
* **group-search-base**
Search base for group membership searches.
Defaults to "" (searching from the root).


[[nsa-ldap-user-service-group-search-filter]]
* **group-search-filter**
Group search filter.
Defaults to `+(uniqueMember={0})+`.
The substituted parameter is the DN of the user.


[[nsa-ldap-user-service-id]]
* **id**
A bean identifier, used for referring to the bean elsewhere in the context.


[[nsa-ldap-user-service-role-prefix]]
* **role-prefix**
A non-empty string prefix that will be added to role strings loaded from persistent storage (e.g.
"ROLE_").
Use the value "none" for no prefix in cases where the default is non-empty.


[[nsa-ldap-user-service-server-ref]]
* **server-ref**
The optional server to use.
If omitted, and a default LDAP server is registered (using <ldap-server> with no Id), that server will be used.


[[nsa-ldap-user-service-user-context-mapper-ref]]
* **user-context-mapper-ref**
Allows explicit customization of the loaded user object by specifying a UserDetailsContextMapper bean which will be called with the context information from the user's directory entry


[[nsa-ldap-user-service-user-details-class]]
* **user-details-class**
Allows the objectClass of the user entry to be specified.
If set, the framework will attempt to load standard attributes for the defined class into the returned UserDetails object


[[nsa-ldap-user-service-user-search-base]]
* **user-search-base**
Search base for user searches.
Defaults to "".
Only used with a 'user-search-filter'.


[[nsa-ldap-user-service-user-search-filter]]
* **user-search-filter**
The LDAP filter used to search for users (optional).
For example `+(uid={0})+`.
The substituted parameter is the user's login name.