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

[[nsa-ldap]]
= LDAP Namespace Options
LDAP is covered in some detail in xref:servlet/authentication/passwords/ldap.adoc#servlet-authentication-ldap[its own chapter].
We 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
The `<ldap-server>` 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 does not allow anonymous access) for connecting to it.
You can also use it 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 have only one server defined in your application context, the other LDAP namespace-defined beans use it automatically.
Otherwise, you can give the element an `id` attribute and refer to it from other namespace beans by 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

The `<ldap-server>` element has the following attributes:

[[nsa-ldap-server-mode]]
`mode`::
Explicitly specifies which embedded LDAP server to use. Valid values are `apacheds` and `unboundid`. By default, it depends on whether 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 file should be a Spring resource pattern (such as `classpath:init.ldif`).
Default: `classpath*:*.ldif`


[[nsa-ldap-server-manager-dn]]
`manager-dn`::
Username (DN) of the "`manager`" user identity, which is used to authenticate to a (non-embedded) LDAP server.
If omitted, anonymous access is 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.
You can use use it 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: `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 is 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>

The parent element of the `<ldap-authentication-provider>` is the xref:servlet/appendix/namespace/authentication-manager.adoc#nsa-authentication-manager[authentication-manager]


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

The `<ldap-authentication-provider>` element has the following attributes:

[[nsa-ldap-authentication-provider-group-role-attribute]]
`group-role-attribute`::
The LDAP attribute name, which contains the role name that is used within Spring Security.
Maps to the `groupRoleAttribute` property of the `DefaultLdapAuthoritiesPopulator`.
Default: `cn`


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

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

[[nsa-ldap-authentication-provider-role-prefix]]
`role-prefix`::
A non-empty string prefix that is added to role strings loaded from persistent storage.
Maps to the `rolePrefix` property of `DefaultLdapAuthoritiesPopulator`.
Use a value of `none` for no prefix in cases where the default is non-empty.
Default: `ROLE_`


[[nsa-ldap-authentication-provider-server-ref]]
`server-ref`::
The optional server to use.
If omitted, and a default LDAP server is registered (by using `<ldap-server>` with no ID), that server is 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 is called with the context information from the user's directory entry.


[[nsa-ldap-authentication-provider-user-details-class]]
`user-details-class`::
Lets the `objectClass` of the user entry be specified.
If set, the framework tries 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 (that is, 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 `+{0}+` key must be present and is substituted with the username.


[[nsa-ldap-authentication-provider-user-search-base]]
`user-search-base`::
Search base for user searches.
Only used with a `user-search-filter`.
Default `""`
+
If you need to perform a search to locate the user in the directory, you can set these attributes to control the search.
The `BindAuthenticator` is configured with a `FilterBasedLdapUserSearch`, and the attribute values map directly to the first two arguments of that bean's constructor.
If these attributes are not set and no `user-dn-pattern` has been supplied as an alternative, the default search values of `+user-search-filter="(uid={0})"+` and `user-search-base=""` are used.

[[nsa-ldap-authentication-provider-user-search-filter]]
`user-search-filter`::
The LDAP filter used to search for users (optional) -- for example, `+(uid={0})+`.
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, you can set these attributes to control the search.
The `BindAuthenticator` is configured with a `FilterBasedLdapUserSearch`, and the attribute values map directly to the first two arguments of that bean's constructor.
If these attributes are not set and no `user-dn-pattern` has been supplied as an alternative, the default search values of `+user-search-filter="(uid={0})"+` and `user-search-base=""` is used.


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

The `<ldap-authentication-provider>` has a single child element: <<nsa-password-compare,password-compare>>.

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


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

The parent element of the `<password-compare>` element is the  <<nsa-ldap-authentication-provider,ldap-authentication-provider>> element.


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

The `<password-compare>` has the following 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 that contains the user password.
Default: `userPassword`


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


The `<password-compare>` element has a single child element: xref:servlet/appendix/namespace/authentication-manager.adoc#nsa-password-encoder[password-encoder]



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


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

The `<ldap-user-service>` element has the following 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 that contains the role name to be used within Spring Security.
Default: `cn`


[[nsa-ldap-user-service-group-search-base]]
`group-search-base`::
Search base for group membership searches.
Default: `""` (searching from the root)


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


[[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 is added to role strings loaded from persistent storage (for example,
`ROLE_`).
Use a value of `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 (by using `<ldap-server>` with no ID), that server is 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 is called with the context information from the user's directory entry.


[[nsa-ldap-user-service-user-details-class]]
`user-details-class`::
Lets the `objectClass` of the user entry be specified.
If set, the framework tries 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.
It is used only with a <<nsa-ldap-user-service-user-search-filter,user-search-filter>> element.
Default: `""`


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