mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-10-27 20:58:45 +00:00
292 lines
11 KiB
Plaintext
292 lines
11 KiB
Plaintext
[[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.
|