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

SEC-1229: Partial doc update

This commit is contained in:
Luke Taylor 2009-10-02 18:48:19 +00:00
parent 073198886d
commit dd3b9553a0
2 changed files with 121 additions and 176 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
docs/manual/src/docbook/concurrent-sessions.xml
View File

@ -1,14 +1,31 @@
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="concurrent-sessions"
xml:id="concurrent-sessions" xmlns:xlink="http://www.w3.org/1999/xlink"> xmlns:xlink="http://www.w3.org/1999/xlink">
<info> <info>
<title>Concurrent Session Handling</title> <title>Session Management</title>
</info> </info>
<!-- TODO: Expand and refer to namespace options --> <!-- TODO: Expand and refer to namespace options -->
<section>
<title>SessionManagementFilter</title>
<para>HTTP session related functonality is handled by the
<classname>SessionManagementFilter</classname>. This </para>
</section>
<section>
<title>Concurrency Control</title>
<para>Spring Security is able to prevent a principal from concurrently authenticating to the <para>Spring Security is able to prevent a principal from concurrently authenticating to the
same application more than a specified number of times. Many ISVs take advantage of this to same application more than a specified number of times. Many ISVs take advantage of this to
enforce licensing, whilst network administrators like this feature because it helps prevent enforce licensing, whilst network administrators like this feature because it helps prevent
people from sharing login names. You can, for example, stop user "Batman" from logging onto people from sharing login names. You can, for example, stop user "Batman" from logging onto
the web application from two different sessions.</para> the web application from two different sessions.</para>
<para>This feature is supported by the namespace, so please check the earlier namespace chapter
for the simplest configuration. Sometimes you need to customize things though. </para>
<para>The implementation has changed substantially in Spring Security 3. Previously the
concurrent authentication check was made by the <classname>ProviderManager</classname>, which
could be injected with a <literal>ConcurrentSessionController</literal> which would check if
the user was attempting to exceed the number of sessions permitted. However, this approach
required that an HTTP session be created in advance, which is undesirable. In Spring Security
3, the user is first authenticated by the <interfacename>AuthenticationManager</interfacename>
and once they are successfully authenticated, a session is created and the check is made
whether they are allowed to have another session open.</para>
<para>To use concurrent session support, you'll need to add the following to <para>To use concurrent session support, you'll need to add the following to
<literal>web.xml</literal>: <programlisting><![CDATA[ <literal>web.xml</literal>: <programlisting><![CDATA[
<listener> <listener>
@ -51,4 +68,5 @@
</bean> </bean>
]]></programlisting> ]]></programlisting>
</para> </para>
</section>
</chapter> </chapter>

273
docs/manual/src/docbook/namespace-config.xml
View File

@ -21,13 +21,13 @@
]]></programlisting> This is much simpler than wiring up the equivalent Apache Directory Server ]]></programlisting> This is much simpler than wiring up the equivalent Apache Directory Server
beans. The most common alternative configuration requirements are supported by attributes on beans. The most common alternative configuration requirements are supported by attributes on
the <literal>ldap-server</literal> element and the user is isolated from worrying about which the <literal>ldap-server</literal> element and the user is isolated from worrying about which
beans they need to be set on and what the bean property names are. <footnote> beans they need to be set on and what the bean property names are. <footnote><para>You can
<para>You can find out more about the use of the <literal>ldap-server</literal> element in find out more about the use of the <literal>ldap-server</literal> element in the chapter
the chapter on <link xlink:href="#ldap">LDAP</link>.</para> on <link xlink:href="#ldap">LDAP</link>.</para></footnote>. Use of a good XML editor while
</footnote>. Use of a good XML editor while editing the application context file should editing the application context file should provide information on the attributes and elements
provide information on the attributes and elements that are available. We would recommend that that are available. We would recommend that you try out the <link
you try out the <link xlink:href="http://www.springsource.com/products/sts">SpringSource Tool xlink:href="http://www.springsource.com/products/sts">SpringSource Tool Suite</link> as it
Suite</link> as it has special features for working with standard Spring namespaces. </para> has special features for working with standard Spring namespaces. </para>
<para> To start using the security namespace in your application context, all you need to do is <para> To start using the security namespace in your application context, all you need to do is
add the schema declaration to your application context file: <programlisting language="xml"> add the schema declaration to your application context file: <programlisting language="xml">
<![CDATA[ <![CDATA[
@ -61,41 +61,25 @@
<para> The namespace is designed to capture the most common uses of the framework and provide <para> The namespace is designed to capture the most common uses of the framework and provide
a simplified and concise syntax for enabling them within an application. The design is based a simplified and concise syntax for enabling them within an application. The design is based
around the large-scale dependencies within the framework, and can be divided up into the around the large-scale dependencies within the framework, and can be divided up into the
following areas: <itemizedlist> following areas: <itemizedlist><listitem><para>
<listitem>
<para>
<emphasis>Web/HTTP Security</emphasis> - the most complex part. Sets up the filters <emphasis>Web/HTTP Security</emphasis> - the most complex part. Sets up the filters
and related service beans used to apply the framework authentication mechanisms, to and related service beans used to apply the framework authentication mechanisms, to
secure URLs, render login and error pages and much more.</para> secure URLs, render login and error pages and much
</listitem> more.</para></listitem><listitem><para>
<listitem>
<para>
<emphasis>Business Object (Method) Security</emphasis> - options for securing the <emphasis>Business Object (Method) Security</emphasis> - options for securing the
service layer.</para> service layer.</para></listitem><listitem><para>
</listitem>
<listitem>
<para>
<emphasis>AuthenticationManager</emphasis> - handles authentication requests from <emphasis>AuthenticationManager</emphasis> - handles authentication requests from
other parts of the framework.</para> other parts of the framework.</para></listitem><listitem><para>
</listitem>
<listitem>
<para>
<emphasis>AccessDecisionManager</emphasis> - provides access decisions for web and <emphasis>AccessDecisionManager</emphasis> - provides access decisions for web and
method security. A default one will be registered, but you can also choose to use a method security. A default one will be registered, but you can also choose to use a
custom one, declared using normal Spring bean syntax.</para> custom one, declared using normal Spring bean
</listitem> syntax.</para></listitem><listitem><para>
<listitem>
<para>
<emphasis>AuthenticationProvider</emphasis>s - mechanisms against which the <emphasis>AuthenticationProvider</emphasis>s - mechanisms against which the
authentication manager authenticates users. The namespace provides supports for authentication manager authenticates users. The namespace provides supports for
several standard options and also a means of adding custom beans declared using a several standard options and also a means of adding custom beans declared using a
traditional syntax. </para> traditional syntax. </para></listitem><listitem><para>
</listitem>
<listitem>
<para>
<emphasis>UserDetailsService</emphasis> - closely related to authentication providers, <emphasis>UserDetailsService</emphasis> - closely related to authentication providers,
but often also required by other beans.</para> but often also required by other beans.</para></listitem>
</listitem>
<!-- todo: diagram and link to other sections which describe the interfaces --> <!-- todo: diagram and link to other sections which describe the interfaces -->
</itemizedlist></para> </itemizedlist></para>
<para>We'll see how these work together in the following sections.</para> <para>We'll see how these work together in the following sections.</para>
@ -177,9 +161,10 @@
application (which will be used for access control). It is also possible to load user application (which will be used for access control). It is also possible to load user
information from a standard properties file using the <literal>properties</literal> information from a standard properties file using the <literal>properties</literal>
attribute on <literal>user-service</literal>. See the section on <link attribute on <literal>user-service</literal>. See the section on <link
xlink:href="#core-services-in-memory-service">in-memory authentication</link> for more details. Using xlink:href="#core-services-in-memory-service">in-memory authentication</link> for more
the <literal>&lt;authentication-provider&gt;</literal> element means that the user details. Using the <literal>&lt;authentication-provider&gt;</literal> element means that the
information will be used by the authentication manager to process authentication requests. </para> user information will be used by the authentication manager to process authentication
requests. </para>
<para> At this point you should be able to start up your application and you will be required <para> At this point you should be able to start up your application and you will be required
to log in to proceed. Try it out, or try experimenting with the "tutorial" sample to log in to proceed. Try it out, or try experimenting with the "tutorial" sample
application that comes with the project. The above configuration actually adds quite a few application that comes with the project. The above configuration actually adds quite a few
@ -196,15 +181,14 @@
</http> </http>
]]> ]]>
</programlisting> These other elements are responsible for setting up form-login, </programlisting> These other elements are responsible for setting up form-login,
basic authentication and logout handling services respectively <footnote> basic authentication and logout handling services respectively <footnote><para>In versions
<para>In versions prior to 3.0, this list also inluded remember-me functionality. This prior to 3.0, this list also inluded remember-me functionality. This could cause some
could cause some confusing errors with some configurations and was removed in 3.0. In confusing errors with some configurations and was removed in 3.0. In 3.0, the addition
3.0, the addition of an <classname>AnonymousProcessingFilter</classname> was made part of an <classname>AnonymousProcessingFilter</classname> was made part of the default
of the default <literal>&lt;http></literal> configuration, so the <literal>&lt;http></literal> configuration, so the <literal>&lt;anonymous
<literal>&lt;anonymous /></literal> element is effectively added regardless of /></literal> element is effectively added regardless of whether
whether <literal>auto-config</literal> is enabled.</para> <literal>auto-config</literal> is enabled.</para></footnote> . They each have
</footnote> . They each have attributes which can be used to alter their behaviour. attributes which can be used to alter their behaviour. </para>
</para>
</section> </section>
<section xml:id="ns-form-and-basic"> <section xml:id="ns-form-and-basic">
<title>Form and Basic Login Options</title> <title>Form and Basic Login Options</title>
@ -366,11 +350,13 @@
<port-mapping http="9080" https="9443"/> <port-mapping http="9080" https="9443"/>
</port-mappings> </port-mappings>
</http>]]> </http>]]>
</programlisting> <!--You can find a more in-depth discussion of channel security </programlisting>
in <xref xlink:href="#channel-security"/--> </para> <!--You can find a more in-depth discussion of channel security
in <xref xlink:href="#channel-security"/-->
</para>
</section> </section>
<section xml:id="ns-concurrent-session"> <section xml:id="ns-concurrent-session">
<title>Concurrent Session Control</title> <title>Session Management</title>
<para> If you wish to place constraints on a single user's ability to log in to your <para> If you wish to place constraints on a single user's ability to log in to your
application, Spring Security supports this out of the box with the following simple application, Spring Security supports this out of the box with the following simple
additions. First you need to add the following listener to your <filename>web.xml</filename> additions. First you need to add the following listener to your <filename>web.xml</filename>
@ -381,21 +367,30 @@
org.springframework.security.web.session.HttpSessionEventPublisher org.springframework.security.web.session.HttpSessionEventPublisher
</listener-class> </listener-class>
</listener> </listener>
]]></programlisting> Then add the following line to your application context: <programlisting language="xml"><![CDATA[ ]]></programlisting> Then add the following lines to your application context: <programlisting language="xml"><![CDATA[
<http> <http>
... ...
<concurrent-session-control max-sessions="1" /> <session-management>
<concurrency-control max-sessions="1" />
</session-management>
</http>]]> </http>]]>
</programlisting> This will prevent a user from logging in multiple times - a </programlisting> This will prevent a user from logging in multiple times - a
second login will cause the first to be invalidated. Often you would prefer to prevent a second login will cause the first to be invalidated. Often you would prefer to prevent a
second login, in which case you can use <programlisting language="xml"><![CDATA[ second login, in which case you can use <programlisting language="xml"><![CDATA[
<http> <http>
... ...
<concurrent-session-control max-sessions="1" exception-if-maximum-exceeded="true"/> <session-management>
<concurrency-control max-sessions="1" error-if-maximum-exceeded="true" />
</session-management>
</http>]]> </http>]]>
</programlisting> The second login will then be rejected. </programlisting> The second login will then be rejected. By
<!-- TODO: Link to main section in docs --> <quote>rejected</quote>, we mean that the user will be sent to the
</para> <literal>authentication-failure-url</literal> if form-based login is being used. If the
second authentication takes place through another non-interactive mechanism, such as
<quote>remember-me</quote>, an <quote>unauthorized</quote> (402) error will be sent to the
client. If instead you want to use an error page, you can add the attribute
<literal>error-url</literal> to the <literal>concurrency-control</literal>
element.<!-- TODO: Link to main section in docs --></para>
</section> </section>
<section xml:id="ns-openid"> <section xml:id="ns-openid">
<title>OpenID Login</title> <title>OpenID Login</title>
@ -427,112 +422,50 @@
<para>The order of the filters is always strictly enforced when using the namespace. When the <para>The order of the filters is always strictly enforced when using the namespace. When the
application context is being created, the filter beans are sorted by the namespace handling application context is being created, the filter beans are sorted by the namespace handling
code and the standard Spring Security filters each have an alias in the namespace and a code and the standard Spring Security filters each have an alias in the namespace and a
well-known position.<note> well-known position.<note><para>In previous versions, the sorting took place after the
<para>In previous versions, the sorting took place after the filter instances had been filter instances had been created, during post-processing of the application context. In
created, during post-processing of the application context. In version 3.0+ the sorting version 3.0+ the sorting is now done at the bean metadata level, before the classes have
is now done at the bean metadata level, before the classes have been instantiated. This been instantiated. This has implications for how you add your own filters to the stack
has implications for how you add your own filters to the stack as the entire filter list as the entire filter list must be known during the parsing of the
must be known during the parsing of the <literal>&lt;http></literal> element, so the <literal>&lt;http></literal> element, so the syntax has changed slightly in
syntax has changed slightly in 3.0.</para> 3.0.</para></note>The filters, aliases and namespace elements/attributes which create
</note>The filters, aliases and namespace elements/attributes which create the filters are the filters are shown in <xref linkend="filter-stack"/>. The filters are listed in the order
shown in <xref linkend="filter-stack"/>. The filters are listed in the order in which they in which they occur in the filter chain. <table xml:id="filter-stack"><title>Standard Filter
occur in the filter chain. <table xml:id="filter-stack"> Aliases and Ordering</title><tgroup cols="3" align="left"><thead><row><entry
<title>Standard Filter Aliases and Ordering</title> align="center">Alias</entry><entry align="center">Filter Class</entry><entry
<tgroup cols="3" align="left"> align="center">Namespace Element or
<thead> Attribute</entry></row></thead><tbody><row><entry>
<row> CHANNEL_FILTER</entry><entry><literal>ChannelProcessingFilter</literal></entry><entry><literal>http/intercept-url</literal></entry></row><row><entry>
<entry align="center">Alias</entry> CONCURRENT_SESSION_FILTER</entry><entry><literal>ConcurrentSessionFilter</literal>
<entry align="center">Filter Class</entry> </entry><entry><literal>http/concurrent-session-control</literal></entry></row><row><entry>
<entry align="center">Namespace Element or Attribute</entry> SESSION_CONTEXT_INTEGRATION_FILTER</entry><entry><classname>HttpSessionContextIntegrationFilter</classname></entry><entry><literal>http</literal></entry></row><row><entry>
</row> LOGOUT_FILTER
</thead> </entry><entry><literal>LogoutFilter</literal></entry><entry><literal>http/logout</literal></entry></row><row><entry>
<tbody> X509_FILTER
<row> </entry><entry><literal>X509PreAuthenticatedProcessigFilter</literal></entry><entry><literal>http/x509</literal></entry></row><row><entry>
<entry> CHANNEL_FILTER</entry> PRE_AUTH_FILTER
<entry><literal>ChannelProcessingFilter</literal></entry> </entry><entry><literal>AstractPreAuthenticatedProcessingFilter</literal>
<entry><literal>http/intercept-url</literal></entry> Subclasses</entry><entry>N/A</entry></row><row><entry> CAS_PROCESSING_FILTER
</row> </entry><entry><literal>CasProcessingFilter</literal></entry><entry>N/A</entry></row><row><entry>
<row> AUTHENTICATION_PROCESSING_FILTER
<entry> CONCURRENT_SESSION_FILTER</entry> </entry><entry><literal>UsernamePasswordAuthenticationProcessingFilter</literal></entry><entry><literal>http/form-login</literal></entry></row><row><entry>
<entry><literal>ConcurrentSessionFilter</literal> BASIC_PROCESSING_FILTER
</entry> </entry><entry><literal>BasicProcessingFilter</literal></entry><entry><literal>http/http-basic</literal></entry></row><row><entry>
<entry><literal>http/concurrent-session-control</literal></entry> SERVLET_API_SUPPORT_FILTER</entry><entry><literal>SecurityContextHolderAwareRequestFilter</literal></entry><entry><literal>http/@servlet-api-provision</literal></entry></row><row><entry>
</row> REMEMBER_ME_FILTER
<row> </entry><entry><classname>RememberMeProcessingFilter</classname></entry><entry><literal>http/remember-me</literal></entry></row><row><entry>
<entry> SESSION_CONTEXT_INTEGRATION_FILTER</entry> ANONYMOUS_FILTER
<entry><classname>HttpSessionContextIntegrationFilter</classname></entry> </entry><entry><literal>AnonymousProcessingFilter</literal></entry><entry><literal>http/anonymous</literal></entry></row><row><entry>
<entry><literal>http</literal></entry> EXCEPTION_TRANSLATION_FILTER
</row> </entry><entry><classname>ExceptionTranslationFilter</classname></entry><entry><literal>http</literal></entry></row><row><entry>
<row> NTLM_FILTER
<entry> LOGOUT_FILTER </entry> </entry><entry><literal>NtlmProcessingFilter</literal></entry><entry>N/A</entry></row><row><entry>
<entry><literal>LogoutFilter</literal></entry> FILTER_SECURITY_INTERCEPTOR
<entry><literal>http/logout</literal></entry> </entry><entry><classname>FilterSecurityInterceptor</classname></entry><entry><literal>http</literal></entry></row><row><entry>
</row> SWITCH_USER_FILTER
<row> </entry><entry><literal>SwitchUserProcessingFilter</literal></entry><entry>N/A</entry></row></tbody></tgroup></table>
<entry> X509_FILTER </entry> You can add your own filter to the stack, using the <literal>custom-filter</literal> element
<entry><literal>X509PreAuthenticatedProcessigFilter</literal></entry> and one of these names to specify the position your filter should appear at: <programlisting language="xml"><![CDATA[
<entry><literal>http/x509</literal></entry>
</row>
<row>
<entry> PRE_AUTH_FILTER </entry>
<entry><literal>AstractPreAuthenticatedProcessingFilter</literal> Subclasses</entry>
<entry>N/A</entry>
</row>
<row>
<entry> CAS_PROCESSING_FILTER </entry>
<entry><literal>CasProcessingFilter</literal></entry>
<entry>N/A</entry>
</row>
<row>
<entry> AUTHENTICATION_PROCESSING_FILTER </entry>
<entry><literal>UsernamePasswordAuthenticationProcessingFilter</literal></entry>
<entry><literal>http/form-login</literal></entry>
</row>
<row>
<entry> BASIC_PROCESSING_FILTER </entry>
<entry><literal>BasicProcessingFilter</literal></entry>
<entry><literal>http/http-basic</literal></entry>
</row>
<row>
<entry> SERVLET_API_SUPPORT_FILTER</entry>
<entry><literal>SecurityContextHolderAwareRequestFilter</literal></entry>
<entry><literal>http/@servlet-api-provision</literal></entry>
</row>
<row>
<entry> REMEMBER_ME_FILTER </entry>
<entry><classname>RememberMeProcessingFilter</classname></entry>
<entry><literal>http/remember-me</literal></entry>
</row>
<row>
<entry> ANONYMOUS_FILTER </entry>
<entry><literal>AnonymousProcessingFilter</literal></entry>
<entry><literal>http/anonymous</literal></entry>
</row>
<row>
<entry> EXCEPTION_TRANSLATION_FILTER </entry>
<entry><classname>ExceptionTranslationFilter</classname></entry>
<entry><literal>http</literal></entry>
</row>
<row>
<entry> NTLM_FILTER </entry>
<entry><literal>NtlmProcessingFilter</literal></entry>
<entry>N/A</entry>
</row>
<row>
<entry> FILTER_SECURITY_INTERCEPTOR </entry>
<entry><classname>FilterSecurityInterceptor</classname></entry>
<entry><literal>http</literal></entry>
</row>
<row>
<entry> SWITCH_USER_FILTER </entry>
<entry><literal>SwitchUserProcessingFilter</literal></entry>
<entry>N/A</entry>
</row>
</tbody>
</tgroup>
</table> You can add your own filter to the stack, using the
<literal>custom-filter</literal> element and one of these names to specify the position
your filter should appear at: <programlisting language="xml"><![CDATA[
<http> <http>
<custom-filter position="AUTHENTICATION_PROCESSING_FILTER" ref="myFilter" /> <custom-filter position="AUTHENTICATION_PROCESSING_FILTER" ref="myFilter" />
</http> </http>
@ -583,20 +516,14 @@
Security protects against this automatically by creating a new session when a user logs in. Security protects against this automatically by creating a new session when a user logs in.
If you don't require this protection, or it conflicts with some other requirement, you can If you don't require this protection, or it conflicts with some other requirement, you can
control the behaviour using the <literal>session-fixation-protection</literal> attribute on control the behaviour using the <literal>session-fixation-protection</literal> attribute on
<literal>&lt;http&gt;</literal>, which has three options <itemizedlist> <literal>&lt;http&gt;</literal>, which has three options
<listitem> <itemizedlist><listitem><para><literal>migrateSession</literal> - creates a new
<para><literal>migrateSession</literal> - creates a new session and copies the existing session and copies the existing session attributes to the new session. This is the
session attributes to the new session. This is the default.</para> default.</para></listitem><listitem><para><literal>none</literal> - Don't do anything.
</listitem> The original session will be
<listitem> retained.</para></listitem><listitem><para><literal>newSession</literal> - Create a
<para><literal>none</literal> - Don't do anything. The original session will be new "clean" session, without copying the existing session
retained.</para> data.</para></listitem></itemizedlist></para>
</listitem>
<listitem>
<para><literal>newSession</literal> - Create a new "clean" session, without copying the
existing session data.</para>
</listitem>
</itemizedlist></para>
</section> </section>
</section> </section>
<section xml:id="ns-method-security"> <section xml:id="ns-method-security">