Cwikius-Spring
/
spring-security
mirror of https://github.com/spring-projects/spring-security.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Polish LDAP Authentication 

Issue gh-7628
This commit is contained in:
Rob Winch 2020-01-16 09:38:34 -06:00
parent f1f158b37e
commit a769f6a0c4
2 changed files with 383 additions and 323 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

705
docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/storage/ldap.adoc
View File

@ -4,11 +4,17 @@
LDAP is often used by organizations as a central repository for user information and as an authentication service.
It can also be used to store the role information for application users.
Spring Security's LDAP based authentication is used by Spring Security when it is configured to <<servlet-authentication-unpwd-input,accept a username/password>> for authentication.
However, despite leveraging a username/password for authentication it does not integrate using `UserDetailsService` because in <<servlet-authentication-ldap-bind,bind authentication>> the LDAP server does not return the password so the application cannot perform validation of the password.
There are many different scenarios for how an LDAP server may be configured so Spring Security's LDAP provider is fully configurable.
It uses separate strategy interfaces for authentication and role retrieval and provides default implementations which can be configured to handle a wide range of situations.
[[servlet-authentication-ldap-prerequisites]]
== Prerequisites
You should be familiar with LDAP before trying to use it with Spring Security.
The following link provides a good introduction to the concepts involved and a guide to setting up a directory using the free LDAP server OpenLDAP: http://www.zytrax.com/books/ldap/[http://www.zytrax.com/books/ldap/].
The following link provides a good introduction to the concepts involved and a guide to setting up a directory using the free LDAP server OpenLDAP: https://www.zytrax.com/books/ldap/.
Some familiarity with the JNDI APIs used to access LDAP from Java may also be useful.
We don't use any third-party LDAP libraries (Mozilla, JLDAP etc.) in the LDAP provider, but extensive use is made of Spring LDAP, so some familiarity with that project may be useful if you plan on adding your own customizations.
@ -16,322 +22,30 @@ When using LDAP authentication, it is important to ensure that you configure LDA
If you are unfamiliar with how to do this, you can refer to the https://docs.oracle.com/javase/jndi/tutorial/ldap/connect/config.html[Java LDAP documentation].
[[servlet-authentication-ldap-server]]
== Configuring an LDAP Server
The first thing you need to do is configure the server against which authentication should take place.
This is done using the `<ldap-server>` element from the security namespace.
This can be configured to point at an external LDAP server, using the `url` attribute:
[source,xml]
----
<ldap-server url="ldap://springframework.org:389/dc=springframework,dc=org" />
----
[NOTE]
====
`spring-security` provides integration with `apacheds` and `unboundid` as a embedded ldap servers. You can choose between them using the attribute `mode` in `ldap-server`.
====
// FIXME:
// ldap server
// embedded (both java and xml)
// external
// authentication
// bind
// password
// roles
// search, etc (other APIs)
[[servlet-authentication-ldap-embedded]]
== Using an Embedded Test Server
The `<ldap-server>` element can also be used to create an embedded server, which can be very useful for testing and demonstrations.
In this case you use it without the `url` attribute:
== Setting up an Embedded LDAP Server
[source,xml]
----
<ldap-server root="dc=springframework,dc=org"/>
----
The first thing you will need to do is to ensure that you have an LDAP Server to point your configuration to.
For simplicity, it often best to start with an embedded LDAP Server.
Spring Security supports using either:
Here we've specified that the root DIT of the directory should be "dc=springframework,dc=org", which is the default.
Used this way, the namespace parser will create an embedded Apache Directory server and scan the classpath for any LDIF files, which it will attempt to load into the server.
You can customize this behaviour using the `ldif` attribute, which defines an LDIF resource to be loaded:
* <<servlet-authentication-ldap-unboundid>>
* <<servlet-authentication-ldap-apacheds>>
[source,xml]
----
<ldap-server ldif="classpath:users.ldif" />
----
This makes it a lot easier to get up and running with LDAP, since it can be inconvenient to work all the time with an external server.
It also insulates the user from the complex bean configuration needed to wire up an Apache Directory server.
Using plain Spring Beans the configuration would be much more cluttered.
You must have the necessary Apache Directory dependency jars available for your application to use.
These can be obtained from the LDAP sample application.
[[servlet-authentication-ldap-bind]]
== Using Bind Authentication
This is the most common LDAP authentication scenario.
[source,xml]
----
<ldap-authentication-provider user-dn-pattern="uid={0},ou=people"/>
----
This simple example would obtain the DN for the user by substituting the user login name in the supplied pattern and attempting to bind as that user with the login password.
This is OK if all your users are stored under a single node in the directory.
If instead you wished to configure an LDAP search filter to locate the user, you could use the following:
[source,xml]
----
<ldap-authentication-provider user-search-filter="(uid={0})"
user-search-base="ou=people"/>
----
If used with the server definition above, this would perform a search under the DN `ou=people,dc=springframework,dc=org` using the value of the `user-search-filter` attribute as a filter.
Again the user login name is substituted for the parameter in the filter name, so it will search for an entry with the `uid` attribute equal to the user name.
If `user-search-base` isn't supplied, the search will be performed from the root.
[[servlet-authentication-ldap-authorities]]
== Loading Authorities
How authorities are loaded from groups in the LDAP directory is controlled by the following attributes.
* `group-search-base`.
Defines the part of the directory tree under which group searches should be performed.
* `group-role-attribute`.
The attribute which contains the name of the authority defined by the group entry.
Defaults to `cn`
* `group-search-filter`.
The filter which is used to search for group membership.
The default is `uniqueMember={0}`, corresponding to the `groupOfUniqueNames` LDAP class footnote:[Note that this is different from the default configuration of the underlying `DefaultLdapAuthoritiesPopulator` which uses `member={0}`.].
In this case, the substituted parameter is the full distinguished name of the user.
The parameter `{1}` can be used if you want to filter on the login name.
So if we used the following configuration
[source,xml]
----
<ldap-authentication-provider user-dn-pattern="uid={0},ou=people"
group-search-base="ou=groups" />
----
and authenticated successfully as user "ben", the subsequent loading of authorities would perform a search under the directory entry `ou=groups,dc=springframework,dc=org`, looking for entries which contain the attribute `uniqueMember` with value `uid=ben,ou=people,dc=springframework,dc=org`.
By default the authority names will have the prefix `ROLE_` prepended.
You can change this using the `role-prefix` attribute.
If you don't want any prefix, use `role-prefix="none"`.
For more information on loading authorities, see the Javadoc for the `DefaultLdapAuthoritiesPopulator` class.
[[servlet-authentication-ldap-implementation]]
== Implementation Classes
The namespace configuration options we've used above are simple to use and much more concise than using Spring beans explicitly.
There are situations when you may need to know how to configure Spring Security LDAP directly in your application context.
You may wish to customize the behaviour of some of the classes, for example.
If you're happy using namespace configuration then you can skip this section and the next one.
The main LDAP provider class, `LdapAuthenticationProvider`, doesn't actually do much itself but delegates the work to two other beans, an `LdapAuthenticator` and an `LdapAuthoritiesPopulator` which are responsible for authenticating the user and retrieving the user's set of `GrantedAuthority` s respectively.
[[servlet-authentication-ldap-authenticators]]
=== LdapAuthenticator Implementations
The authenticator is also responsible for retrieving any required user attributes.
This is because the permissions on the attributes may depend on the type of authentication being used.
For example, if binding as the user, it may be necessary to read them with the user's own permissions.
There are currently two authentication strategies supplied with Spring Security:
* Authentication directly to the LDAP server ("bind" authentication).
* Password comparison, where the password supplied by the user is compared with the one stored in the repository.
This can either be done by retrieving the value of the password attribute and checking it locally or by performing an LDAP "compare" operation, where the supplied password is passed to the server for comparison and the real password value is never retrieved.
[[servlet-authentication-ldap-authenticators-common]]
=== Common Functionality
Before it is possible to authenticate a user (by either strategy), the distinguished name (DN) has to be obtained from the login name supplied to the application.
This can be done either by simple pattern-matching (by setting the `setUserDnPatterns` array property) or by setting the `userSearch` property.
For the DN pattern-matching approach, a standard Java pattern format is used, and the login name will be substituted for the parameter `{0}`.
The pattern should be relative to the DN that the configured `SpringSecurityContextSource` will bind to (see the section on <<ldap-context-source,connecting to the LDAP server>> for more information on this).
For example, if you are using an LDAP server with the URL `ldap://monkeymachine.co.uk/dc=springframework,dc=org`, and have a pattern `uid={0},ou=greatapes`, then a login name of "gorilla" will map to a DN `uid=gorilla,ou=greatapes,dc=springframework,dc=org`.
Each configured DN pattern will be tried in turn until a match is found.
For information on using a search, see the section on <<ldap-searchobjects,search objects>> below.
A combination of the two approaches can also be used - the patterns will be checked first and if no matching DN is found, the search will be used.
[[servlet-authentication-ldap-authenticators-bind]]
=== BindAuthenticator
The class `BindAuthenticator` in the package `org.springframework.security.ldap.authentication` implements the bind authentication strategy.
It simply attempts to bind as the user.
[[servlet-authentication-ldap-authenticators-password]]
=== PasswordComparisonAuthenticator
The class `PasswordComparisonAuthenticator` implements the password comparison authentication strategy.
[[servlet-authentication-ldap-authenticators-connect]]
== Connecting to the LDAP Server
The beans discussed above have to be able to connect to the server.
They both have to be supplied with a `SpringSecurityContextSource` which is an extension of Spring LDAP's `ContextSource`.
Unless you have special requirements, you will usually configure a `DefaultSpringSecurityContextSource` bean, which can be configured with the URL of your LDAP server and optionally with the username and password of a "manager" user which will be used by default when binding to the server (instead of binding anonymously).
For more information read the Javadoc for this class and for Spring LDAP's `AbstractContextSource`.
[[servlet-authentication-ldap-search]]
=== LDAP Search Objects
Often a more complicated strategy than simple DN-matching is required to locate a user entry in the directory.
This can be encapsulated in an `LdapUserSearch` instance which can be supplied to the authenticator implementations, for example, to allow them to locate a user.
The supplied implementation is `FilterBasedLdapUserSearch`.
[[servlet-authentication-ldap-filter]]
=== FilterBasedLdapUserSearch
This bean uses an LDAP filter to match the user object in the directory.
The process is explained in the Javadoc for the corresponding search method on the https://java.sun.com/j2se/1.4.2/docs/api/javax/naming/directory/DirContext.html#search(javax.naming.Name%2C%2520java.lang.String%2C%2520java.lang.Object%5B%5D%2C%2520javax.naming.directory.SearchControls)[JDK DirContext class].
As explained there, the search filter can be supplied with parameters.
For this class, the only valid parameter is `{0}` which will be replaced with the user's login name.
[[ldap-authorities]]
== LdapAuthoritiesPopulator
After authenticating the user successfully, the `LdapAuthenticationProvider` will attempt to load a set of authorities for the user by calling the configured `LdapAuthoritiesPopulator` bean.
The `DefaultLdapAuthoritiesPopulator` is an implementation which will load the authorities by searching the directory for groups of which the user is a member (typically these will be `groupOfNames` or `groupOfUniqueNames` entries in the directory).
Consult the Javadoc for this class for more details on how it works.
If you want to use LDAP only for authentication, but load the authorities from a difference source (such as a database) then you can provide your own implementation of this interface and inject that instead.
[[ldap-bean-config]]
== Spring Bean Configuration
A typical configuration, using some of the beans we've discussed here, might look like this:
[source,xml]
----
<bean id="contextSource"
class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">
<constructor-arg value="ldap://monkeymachine:389/dc=springframework,dc=org"/>
<property name="userDn" value="cn=manager,dc=springframework,dc=org"/>
<property name="password" value="password"/>
</bean>
<bean id="ldapAuthProvider"
class="org.springframework.security.ldap.authentication.LdapAuthenticationProvider">
<constructor-arg>
<bean class="org.springframework.security.ldap.authentication.BindAuthenticator">
<constructor-arg ref="contextSource"/>
<property name="userDnPatterns">
<list><value>uid={0},ou=people</value></list>
</property>
</bean>
</constructor-arg>
<constructor-arg>
<bean class="org.springframework.security.ldap.userdetails.DefaultLdapAuthoritiesPopulator">
<constructor-arg ref="contextSource"/>
<constructor-arg value="ou=groups"/>
<property name="groupRoleAttribute" value="ou"/>
</bean>
</constructor-arg>
</bean>
----
This would set up the provider to access an LDAP server with URL `ldap://monkeymachine:389/dc=springframework,dc=org`.
Authentication will be performed by attempting to bind with the DN `uid=<user-login-name>,ou=people,dc=springframework,dc=org`.
After successful authentication, roles will be assigned to the user by searching under the DN `ou=groups,dc=springframework,dc=org` with the default filter `(member=<user's-DN>)`.
The role name will be taken from the "ou" attribute of each match.
To configure a user search object, which uses the filter `(uid=<user-login-name>)` for use instead of the DN-pattern (or in addition to it), you would configure the following bean
[source,xml]
----
<bean id="userSearch"
class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">
<constructor-arg index="0" value=""/>
<constructor-arg index="1" value="(uid={0})"/>
<constructor-arg index="2" ref="contextSource" />
</bean>
----
and use it by setting the `BindAuthenticator` bean's `userSearch` property.
The authenticator would then call the search object to obtain the correct user's DN before attempting to bind as this user.
[[ldap-custom-user-details]]
== LDAP Attributes and Customized UserDetails
The net result of an authentication using `LdapAuthenticationProvider` is the same as a normal Spring Security authentication using the standard `UserDetailsService` interface.
A `UserDetails` object is created and stored in the returned `Authentication` object.
As with using a `UserDetailsService`, a common requirement is to be able to customize this implementation and add extra properties.
When using LDAP, these will normally be attributes from the user entry.
The creation of the `UserDetails` object is controlled by the provider's `UserDetailsContextMapper` strategy, which is responsible for mapping user objects to and from LDAP context data:
[source,java]
----
public interface UserDetailsContextMapper {
UserDetails mapUserFromContext(DirContextOperations ctx, String username,
Collection<GrantedAuthority> authorities);
void mapUserToContext(UserDetails user, DirContextAdapter ctx);
}
----
Only the first method is relevant for authentication.
If you provide an implementation of this interface and inject it into the `LdapAuthenticationProvider`, you have control over exactly how the UserDetails object is created.
The first parameter is an instance of Spring LDAP's `DirContextOperations` which gives you access to the LDAP attributes which were loaded during authentication.
The `username` parameter is the name used to authenticate and the final parameter is the collection of authorities loaded for the user by the configured `LdapAuthoritiesPopulator`.
The way the context data is loaded varies slightly depending on the type of authentication you are using.
With the `BindAuthenticator`, the context returned from the bind operation will be used to read the attributes, otherwise the data will be read using the standard context obtained from the configured `ContextSource` (when a search is configured to locate the user, this will be the data returned by the search object).
[[ldap-active-directory]]
== Active Directory Authentication
Active Directory supports its own non-standard authentication options, and the normal usage pattern doesn't fit too cleanly with the standard `LdapAuthenticationProvider`.
Typically authentication is performed using the domain username (in the form `user@domain`), rather than using an LDAP distinguished name.
To make this easier, Spring Security 3.1 has an authentication provider which is customized for a typical Active Directory setup.
== ActiveDirectoryLdapAuthenticationProvider
Configuring `ActiveDirectoryLdapAuthenticationProvider` is quite straightforward.
You just need to supply the domain name and an LDAP URL supplying the address of the server footnote:[It is also possible to obtain the server's IP address using a DNS lookup.
This is not currently supported, but hopefully will be in a future version.].
An example configuration would then look like this:
[source,xml]
----
<bean id="adAuthenticationProvider"
class="org.springframework.security.ldap.authentication.ad.ActiveDirectoryLdapAuthenticationProvider">
<constructor-arg value="mydomain.com" />
<constructor-arg value="ldap://adserver.mydomain.com/" />
</bean>
----
Note that there is no need to specify a separate `ContextSource` in order to define the server location - the bean is completely self-contained.
A user named "Sharon", for example, would then be able to authenticate by entering either the username `sharon` or the full Active Directory `userPrincipalName`, namely `sharon@mydomain.com`.
The user's directory entry will then be located, and the attributes returned for possible use in customizing the created `UserDetails` object (a `UserDetailsContextMapper` can be injected for this purpose, as described above).
All interaction with the directory takes place with the identity of the user themselves.
There is no concept of a "manager" user.
By default, the user authorities are obtained from the `memberOf` attribute values of the user entry.
The authorities allocated to the user can again be customized using a `UserDetailsContextMapper`.
You can also inject a `GrantedAuthoritiesMapper` into the provider instance to control the authorities which end up in the `Authentication` object.
=== Active Directory Error Codes
By default, a failed result will cause a standard Spring Security `BadCredentialsException`.
If you set the property `convertSubErrorCodesToExceptions` to `true`, the exception messages will be parsed to attempt to extract the Active Directory-specific error code and raise a more specific exception.
Check the class Javadoc for more information.
== LDAP Java Configuration
You can find the updates to support LDAP based authentication.
The https://github.com/spring-projects/spring-security/tree/master/samples/javaconfig/ldap[ldap-javaconfig] sample provides a complete example of using LDAP based authentication.
[source,java]
----
@Autowired
private DataSource dataSource;
@Autowired
public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
auth
.ldapAuthentication()
.userDnPatterns("uid={0},ou=people")
.groupSearchBase("ou=groups");
}
----
The example above uses the following LDIF and an embedded Apache DS LDAP instance.
In the samples below, we expose the following as `users.ldif` as a classpath resource to initialize the embedded LDAP server with the users `user` and `admin` both of which have a password of `password`.
.users.ldif
[source,ldif]
----
dn: ou=groups,dc=springframework,dc=org
objectclass: top
@ -377,23 +91,370 @@ cn: admin
uniqueMember: uid=admin,ou=people,dc=springframework,dc=org
----
[[servlet-authentication-ldap-unboundid]]
=== Embedded UnboundID Server
If you wish to use https://ldap.com/unboundid-ldap-sdk-for-java/[UnboundID], then specify the following dependencies:
.UnboundID Dependencies
====
.Maven
[source,xml,role="primary",subs="verbatim,attributes"]
----
<dependency>
<groupId>com.unboundid</groupId>
<artifactId>unboundid-ldapsdk</artifactId>
<version>{unboundid-ldapsdk-version}</version>
<scope>runtime</scope>
</dependency>
----
.Gradle
[source,groovy,role="secondary",subs="verbatim,attributes"]
----
depenendencies {
runtimeOnly "com.unboundid:unboundid-ldapsdk:{unboundid-ldapsdk-version}"
}
----
====
You can then configure the Embedded LDAP Server
.Embedded LDAP Server Configuration
====
.Java
[source,java,role="primary"]
----
@Bean
UnboundIdContainer ldapContainer() {
return new UnboundIdContainer("dc=springframework,dc=org",
"classpath:users.ldif");
}
----
.XML
[source,xml]
----
<b:bean class="org.springframework.security.ldap.server.UnboundIdContainer"
c:defaultPartitionSuffix="dc=springframework,dc=org"
c:ldif="classpath:users.ldif"/>
----
====
[[servlet-authentication-ldap-apacheds]]
=== Embedded ApacheDS Server
[NOTE]
====
Spring Security uses ApacheDS 1.x which is no longer maintained.
Unfortunately, ApacheDS 2.x has only released milestone versions with no stable release.
Once a stable release of ApacheDS 2.x is available, we will consider updating.
====
If you wish to use https://directory.apache.org/apacheds/[Apache DS], then specify the following dependencies:
.ApacheDS Dependencies
====
.Maven
[source,xml,role="primary",subs="+attributes"]
----
<dependency>
<groupId>org.apache.directory.server</groupId>
<artifactId>apacheds-core</artifactId>
<version>{apacheds-core-version}</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.apache.directory.server</groupId>
<artifactId>apacheds-server-jndi</artifactId>
<version>{apacheds-core-version}</version>
<scope>runtime</scope>
</dependency>
----
.Gradle
[source,groovy,role="secondary",subs="+attributes"]
----
depenendencies {
runtimeOnly "org.apache.directory.server:apacheds-core:{apacheds-core-version}"
runtimeOnly "org.apache.directory.server:apacheds-server-jndi:{apacheds-core-version}"
}
----
====
You can then configure the Embedded LDAP Server
.Embedded LDAP Server Configuration
====
.Java
[source,java,role="primary"]
----
@Bean
ApacheDSContainer ldapContainer() {
return new ApacheDSContainer("dc=springframework,dc=org",
"classpath:users.ldif");
}
----
.XML
[source,xml,role="secondary"]
----
<b:bean class="org.springframework.security.ldap.server.ApacheDSContainer"
c:defaultPartitionSuffix="dc=springframework,dc=org"
c:ldif="classpath:users.ldif"/>
----
====
[[servlet-authentication-ldap-contextsource]]
== LDAP ContextSource
Once you have an LDAP Server to point your configuration to, you need configure Spring Security to point to an LDAP server that should be used to authenticate users.
This is done by creating an LDAP `ContextSource`, which is the equivalent of a JDBC `DataSource`.
.LDAP Context Source
====
.Java
[source,java,role="primary"]
----
ContextSource contextSource(UnboundIdContainer container) {
return new DefaultSpringSecurityContextSource("ldap://localhost:53389/dc=springframework,dc=org");
}
----
.XML
[source,xml,role="secondary"]
----
<ldap-server
url="ldap://localhost:53389/dc=springframework,dc=org" />
----
====
[[servlet-authentication-ldap-authentication]]
== Authentication
Spring Security's LDAP support does not use the <<servlet-authentication-userdetailsservice>> because LDAP bind authentication does not allow clients to read the password or even a hashed version of the password.
This means there is no way a password to be read and then authenticated by Spring Security.
For this reason, LDAP support is implemented using the `LdapAuthenticator` interface.
The `LdapAuthenticator` is also responsible for retrieving any required user attributes.
This is because the permissions on the attributes may depend on the type of authentication being used.
For example, if binding as the user, it may be necessary to read them with the user's own permissions.
There are two `LdapAuthenticator` implementations supplied with Spring Security:
* <<servlet-authentication-ldap-bind>>
* <<servlet-authentication-ldap-pwd>>
[[servlet-authentication-ldap-bind]]
== Using Bind Authentication
https://ldap.com/the-ldap-bind-operation/[Bind Authentication] is the most common mechanism for authenticating users with LDAP.
In bind authentication the users credentials (i.e. username/password) are submitted to the LDAP server which authenticates them.
The advantage to using bind authentication is that the user's secrets (i.e. password) do not need to be exposed to clients which helps to protect them from leaking.
[[servlet-authentication-ldap-using]]
== Using LDAP with Spring Security
LDAP authentication in Spring Security can be roughly divided into the following stages.
An example of bind authentication configuration can be found below.
* Obtaining the unique LDAP "Distinguished Name", or DN, from the login name.
This will often mean performing a search in the directory, unless the exact mapping of usernames to DNs is known in advance.
So a user might enter the name "joe" when logging in, but the actual name used to authenticate to LDAP will be the full DN, such as `uid=joe,ou=users,dc=spring,dc=io`.
.Bind Authentication
====
.Java
[source,java,role="primary"]
----
@Bean
BindAuthenticator authenticator(BaseLdapPathContextSource contextSource) {
BindAuthenticator authenticator = new BindAuthenticator(contextSource);
authenticator.setUserDnPatterns(new String[] { "uid={0},ou=people" });
return authenticator;
}
* Authenticating the user, either by "binding" as that user or by performing a remote "compare" operation of the user's password against the password attribute in the directory entry for the DN.
@Bean
LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticator) {
return new LdapAuthenticationProvider(authenticator);
}
----
* Loading the list of authorities for the user.
.XML
[source,xml,role="secondary"]
----
<ldap-authentication-provider
user-dn-pattern="uid={0},ou=people"/>
----
====
The exception is when the LDAP directory is just being used to retrieve user information and authenticate against it locally.
This may not be possible as directories are often set up with limited read access for attributes such as user passwords.
This simple example would obtain the DN for the user by substituting the user login name in the supplied pattern and attempting to bind as that user with the login password.
This is OK if all your users are stored under a single node in the directory.
If instead you wished to configure an LDAP search filter to locate the user, you could use the following:
We will look at some configuration scenarios below.
For full information on available configuration options, please consult the security namespace schema (information from which should be available in your XML editor).
.Bind Authentication with Search Filter
====
.Java
[source,java,role="primary"]
----
@Bean
BindAuthenticator authenticator(BaseLdapPathContextSource contextSource) {
String searchBase = "ou=people";
String filter = "(uid={0})";
FilterBasedLdapUserSearch search =
new FilterBasedLdapUserSearch(searchBase, filter, contextSource);
BindAuthenticator authenticator = new BindAuthenticator(contextSource);
authenticator.setUserSearch(search);
return authenticator;
}
@Bean
LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticator) {
return new LdapAuthenticationProvider(authenticator);
}
----
.XML
[source,xml,role="secondary"]
----
<ldap-authentication-provider
user-search-filter="(uid={0})"
user-search-base="ou=people"/>
----
====
If used with the `ContextSource` <<servlet-authentication-ldap-contextsource,definition above>>, this would perform a search under the DN `ou=people,dc=springframework,dc=org` using `(uid={0})` as a filter.
Again the user login name is substituted for the parameter in the filter name, so it will search for an entry with the `uid` attribute equal to the user name.
If a user search base isn't supplied, the search will be performed from the root.
[[servlet-authentication-ldap-pwd]]
== Using Password Authentication
Password comparison is when the password supplied by the user is compared with the one stored in the repository.
This can either be done by retrieving the value of the password attribute and checking it locally or by performing an LDAP "compare" operation, where the supplied password is passed to the server for comparison and the real password value is never retrieved.
An LDAP compare cannot be done when the password is properly hashed with a random salt.
.Minimal Password Compare Configuration
====
.Java
[source,java,role="primary"]
----
@Bean
PasswordComparisonAuthenticator authenticator(BaseLdapPathContextSource contextSource) {
return new PasswordComparisonAuthenticator(contextSource);
}
@Bean
LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticator) {
return new LdapAuthenticationProvider(authenticator);
}
----
.XML
[source,xml,role="secondary"]
----
<ldap-authentication-provider
user-dn-pattern="uid={0},ou=people">
<password-compare />
</ldap-authentication-provider>
----
====
A more advanced configuration with some customizations can be found below.
.Password Compare Configuration
====
.Java
[source,java,role="primary"]
----
@Bean
PasswordComparisonAuthenticator authenticator(BaseLdapPathContextSource contextSource) {
PasswordComparisonAuthenticator authenticator =
new PasswordComparisonAuthenticator(contextSource);
authenticator.setPasswordAttributeName("pwd"); // <1>
authenticator.setPasswordEncoder(new BCryptPasswordEncoder()); // <2>
return authenticator;
}
@Bean
LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticator) {
return new LdapAuthenticationProvider(authenticator);
}
----
.XML
[source,xml,role="secondary"]
----
<ldap-authentication-provider
user-dn-pattern="uid={0},ou=people">
<password-compare password-attribute="pwd"> <!--1-->
<password-encoder ref="passwordEncoder" /> <!--2-->
</password-compare>
</ldap-authentication-provider>
<b:bean id="passwordEncoder"
class="org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder" />
----
====
<1> Specify the password attribute as `pwd`
<2> Use `BCryptPasswordEncoder`
== LdapAuthoritiesPopulator
Spring Security's `LdapAuthoritiesPopulator` is used to determine what authorites are returned for the user.
.Minimal Password Compare Configuration
====
.Java
[source,java,role="primary"]
----
@Bean
LdapAuthoritiesPopulator authorities(BaseLdapPathContextSource contextSource) {
String groupSearchBase = "";
DefaultLdapAuthoritiesPopulator authorities =
new DefaultLdapAuthoritiesPopulator(contextSource, groupSearchBase);
authorities.setGroupSearchFilter("member={0}");
return authorities;
}
@Bean
LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticator, LdapAuthoritiesPopulator authorities) {
return new LdapAuthenticationProvider(authenticator, authorities);
}
----
.XML
[source,xml,role="secondary"]
----
<ldap-authentication-provider
user-dn-pattern="uid={0},ou=people"
group-search-filter="member={0}"/>
----
====
== Active Directory
Active Directory supports its own non-standard authentication options, and the normal usage pattern doesn't fit too cleanly with the standard `LdapAuthenticationProvider`.
Typically authentication is performed using the domain username (in the form `user@domain`), rather than using an LDAP distinguished name.
To make this easier, Spring Security has an authentication provider which is customized for a typical Active Directory setup.
Configuring `ActiveDirectoryLdapAuthenticationProvider` is quite straightforward.
You just need to supply the domain name and an LDAP URL supplying the address of the server footnote:[It is also possible to obtain the server's IP address using a DNS lookup.
This is not currently supported, but hopefully will be in a future version.].
An example configuration can be seen below:
.Example Active Directory Configuration
====
.Java
[source,java,role="primary"]
----
@Bean
ActiveDirectoryLdapAuthenticationProvider authenticationProvider() {
return new ActiveDirectoryLdapAuthenticationProvider("example.com", "ldap://company.example.com/");
}
----
.XML
[source,xml,role="secondary"]
----
<bean id="authenticationProvider"
class="org.springframework.security.ldap.authentication.ad.ActiveDirectoryLdapAuthenticationProvider">
<constructor-arg value="example.com" />
<constructor-arg value="ldap://company.example.com/" />
</bean>
----
====

1
etc/nohttp/whitelist.lines
View File

@ -4,4 +4,3 @@
^http://jaspan.com.*
^http://lists.webappsec.org/.*
^http://webblaze.cs.berkeley.edu/.*
^http://www.zytrax.com/books/ldap/