202 lines
13 KiB
XML
202 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="preauth"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<info>
|
|
<title>Pre-Authentication Scenarios</title>
|
|
</info>
|
|
<para> There are situations where you want to use Spring Security for authorization, but the
|
|
user has already been reliably authenticated by some external system prior to accessing the
|
|
application. We refer to these situations as <quote>pre-authenticated</quote> scenarios.
|
|
Examples include X.509, Siteminder and authentication by the J2EE container in which the
|
|
application is running. When using pre-authentication, Spring Security has to <orderedlist>
|
|
<listitem>
|
|
<para>Identify the user making the request. </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Obtain the authorities for the user.</para>
|
|
</listitem>
|
|
</orderedlist>The details will depend on the external authentication mechanism. A user might
|
|
be identified by their certificate information in the case of X.509, or by an HTTP request
|
|
header in the case of Siteminder. If relying on container authentication, the user will be
|
|
identified by calling the <methodname>getUserPrincipal()</methodname> method on the incoming
|
|
HTTP request. In some cases, the external mechanism may supply role/authority information
|
|
for the user but in others the authorities must be obtained from a separate source, such as
|
|
a <interfacename>UserDetailsService</interfacename>. </para>
|
|
<section>
|
|
<title>Pre-Authentication Framework Classes</title>
|
|
<para> Because most pre-authentication mechanisms follow the same pattern, Spring Security
|
|
has a set of classes which provide an internal framework for implementing
|
|
pre-authenticated authentication providers. This removes duplication and allows new
|
|
implementations to be added in a structured fashion, without having to write everything
|
|
from scratch. You don't need to know about these classes if you want to use something
|
|
like <link xlink:href="#x509">X.509 authentication</link>, as it already has a namespace
|
|
configuration option which is simpler to use and get started with. If you need to use
|
|
explicit bean configuration or are planning on writing your own implementation then an
|
|
understanding of how the provided implementations work will be useful. You will find
|
|
classes under the
|
|
<package>org.springframework.security.web.authentication.preauth</package>. We just
|
|
provide an outline here so you should consult the Javadoc and source where appropriate. </para>
|
|
<section>
|
|
<title>AbstractPreAuthenticatedProcessingFilter</title>
|
|
<para> This class will check the current contents of the security context and, if empty,
|
|
it will attempt to extract user information from the HTTP request and submit it to
|
|
the <interfacename>AuthenticationManager</interfacename>. Subclasses override the
|
|
following methods to obtain this information:
|
|
<programlisting language="java">
|
|
protected abstract Object getPreAuthenticatedPrincipal(HttpServletRequest request);
|
|
|
|
protected abstract Object getPreAuthenticatedCredentials(HttpServletRequest request);
|
|
</programlisting>
|
|
After calling these, the filter will create a
|
|
<classname>PreAuthenticatedAuthenticationToken</classname> containing the returned
|
|
data and submit it for authentication. By <quote>authentication</quote> here, we
|
|
really just mean further processing to perhaps load the user's authorities, but the
|
|
standard Spring Security authentication architecture is followed. </para>
|
|
</section>
|
|
<section>
|
|
<title>AbstractPreAuthenticatedAuthenticationDetailsSource</title>
|
|
<para> Like other Spring Security authentication filters, the pre-authentication filter
|
|
has an <literal>authenticationDetailsSource</literal> property which by default will
|
|
create a <classname>WebAuthenticationDetails</classname> object to store additional
|
|
information such as the session-identifier and originating IP address in the
|
|
<literal>details</literal> property of the
|
|
<interfacename>Authentication</interfacename> object. In cases where user role
|
|
information can be obtained from the pre-authentication mechanism, the data is also
|
|
stored in this property. Subclasses of
|
|
<classname>AbstractPreAuthenticatedAuthenticationDetailsSource</classname> use an
|
|
extended details object which implements the
|
|
<interfacename>GrantedAuthoritiesContainer</interfacename> interface, thus enabling
|
|
the authentication provider to read the authorities which were externally allocated
|
|
to the user. We'll look at a concrete example next. </para>
|
|
<section xml:id="j2ee-preauth-details">
|
|
<title>J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource</title>
|
|
<para> If the filter is configured with an
|
|
<literal>authenticationDetailsSource</literal> which is an instance of this
|
|
class, the authority information is obtained by calling the
|
|
<methodname>isUserInRole(String role)</methodname> method for each of a
|
|
pre-determined set of <quote>mappable roles</quote>. The class gets these from a
|
|
configured <interfacename>MappableAttributesRetriever</interfacename>. Possible
|
|
implementations include hard-coding a list in the application context and
|
|
reading the role information from the <literal><security-role></literal>
|
|
information in a <filename>web.xml</filename> file. The pre-authentication
|
|
sample application uses the latter approach. </para>
|
|
<para>There is an additional stage where the roles (or attributes) are mapped to
|
|
Spring Security <interfacename>GrantedAuthority</interfacename> objects using a
|
|
configured <interfacename>Attributes2GrantedAuthoritiesMapper</interfacename>.
|
|
The default will just add the usual <literal>ROLE_</literal> prefix to the
|
|
names, but it gives you full control over the behaviour. </para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>PreAuthenticatedAuthenticationProvider</title>
|
|
<para> The pre-authenticated provider has little more to do than load the
|
|
<interfacename>UserDetails</interfacename> object for the user. It does this by
|
|
delegating to a <interfacename>AuthenticationUserDetailsService</interfacename>. The
|
|
latter is similar to the standard <interfacename>UserDetailsService</interfacename>
|
|
but takes an <interfacename>Authentication</interfacename> object rather than just
|
|
user name:
|
|
<programlisting language="java">
|
|
public interface AuthenticationUserDetailsService {
|
|
UserDetails loadUserDetails(Authentication token) throws UsernameNotFoundException;
|
|
}
|
|
</programlisting>
|
|
This interface may have also other uses but with pre-authentication it allows access
|
|
to the authorities which were packaged in the
|
|
<interfacename>Authentication</interfacename> object, as we saw in the previous
|
|
section. The
|
|
<classname>PreAuthenticatedGrantedAuthoritiesUserDetailsService</classname> class
|
|
does this. Alternatively, it may delegate to a standard
|
|
<interfacename>UserDetailsService</interfacename> via the
|
|
<classname>UserDetailsByNameServiceWrapper</classname> implementation. </para>
|
|
</section>
|
|
<section>
|
|
<title>Http403ForbiddenEntryPoint</title>
|
|
<para> The <interfacename>AuthenticationEntryPoint</interfacename> was discussed in the
|
|
<link xlink:href="#tech-intro-auth-entry-point">technical overview</link> chapter.
|
|
Normally it is responsible for kick-starting the authentication process for an
|
|
unauthenticated user (when they try to access a protected resource), but in the
|
|
pre-authenticated case this doesn't apply. You would only configure the
|
|
<classname>ExceptionTranslationFilter</classname> with an instance of this class if
|
|
you aren't using pre-authentication in combination with other authentication
|
|
mechanisms. It will be called if the user is rejected by the
|
|
<classname>AbstractPreAuthenticatedProcessingFilter</classname> resulting in a null
|
|
authentication. It always returns a <literal>403</literal>-forbidden response code
|
|
if called. </para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Concrete Implementations</title>
|
|
<para> X.509 authentication is covered in its <link xlink:href="#x509">own chapter</link>.
|
|
Here we'll look at some classes which provide support for other pre-authenticated
|
|
scenarios. </para>
|
|
<section>
|
|
<title>Request-Header Authentication (Siteminder)</title>
|
|
<para> An external authentication system may supply information to the application by
|
|
setting specific headers on the HTTP request. A well known example of this is
|
|
Siteminder, which passes the username in a header called <literal>SM_USER</literal>.
|
|
This mechanism is supported by the class
|
|
<classname>RequestHeaderAuthenticationFilter</classname> which simply extracts the
|
|
username from the header. It defaults to using the name <literal>SM_USER</literal>
|
|
as the header name. See the Javadoc for more details. </para>
|
|
<tip>
|
|
<para>Note that when using a system like this, the framework performs no
|
|
authentication checks at all and it is <emphasis>extremely</emphasis> important
|
|
that the external system is configured properly and protects all access to the
|
|
application. If an attacker is able to forge the headers in their original
|
|
request without this being detected then they could potentially choose any
|
|
username they wished. </para>
|
|
</tip>
|
|
<section>
|
|
<title>Siteminder Example Configuration</title>
|
|
<para> A typical configuration using this filter would look like this: <programlisting><![CDATA[
|
|
<security:http>
|
|
<!-- Additional http configuration omitted -->
|
|
<security:custom-filter ref="siteminderFilter" />
|
|
</security:http>
|
|
|
|
<bean id="siteminderFilter" class=
|
|
"org.springframework.security.web.authentication.preauth.header.RequestHeaderAuthenticationFilter">
|
|
<property name="principalRequestHeader" value="SM_USER"/>
|
|
<property name="authenticationManager" ref="authenticationManager" />
|
|
</bean>
|
|
|
|
<bean id="preauthAuthProvider"
|
|
class="org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationProvider">
|
|
<property name="preAuthenticatedUserDetailsService">
|
|
<bean id="userDetailsServiceWrapper"
|
|
class="org.springframework.security.core.userdetails.UserDetailsByNameServiceWrapper">
|
|
<property name="userDetailsService" ref="userDetailsService"/>
|
|
</bean>
|
|
</property>
|
|
</bean>
|
|
|
|
<security:authentication-manager alias="authenticationManager">
|
|
<security:authentication-provider ref="preauthAuthProvider" />
|
|
</security-authentication-manager>
|
|
]]>
|
|
</programlisting> We've assumed here that the security namespace is being used for configuration
|
|
(hence the user of the <literal>custom-filter</literal>,
|
|
<literal>authentication-manager</literal> and
|
|
<literal>custom-authentication-provider</literal> elements (you can read more
|
|
about them in the <link xlink:href="#ns-config">namespace chapter</link>). You
|
|
would leave these out of a traditional bean configuration. It's also assumed
|
|
that you have added a <interfacename>UserDetailsService</interfacename> (called
|
|
<quote>userDetailsService</quote>) to your configuration to load the user's
|
|
roles. </para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>J2EE Container Authentication</title>
|
|
<para> The class <classname>J2eePreAuthenticatedProcessingFilter</classname> will
|
|
extract the username from the <literal>userPrincipal</literal> property of the
|
|
<interfacename>HttpServletRequest</interfacename>. Use of this filter would usually
|
|
be combined with the use of J2EE roles as described above in <xref
|
|
linkend="j2ee-preauth-details"/>. </para>
|
|
<para> There is a sample application in the codebase which uses this approach, so get
|
|
hold of the code from subversion and have a look at the application context file if
|
|
you are interested. The code is in the <filename>samples/preauth</filename>
|
|
directory. </para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|