283 lines
11 KiB
Plaintext
283 lines
11 KiB
Plaintext
[[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.
|