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

Ref manual updates and correction

This commit is contained in:
Luke Taylor 2009-10-07 19:48:32 +00:00
parent 2b99c6331e
commit 9bece3bc9a
3 changed files with 105 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
docs/manual/src/docbook/introduction.xml
View File

@ -17,16 +17,19 @@
standards, it's important to recognise that they are not portable at a WAR or EAR level.
Therefore, if you switch server environments, it is typically a lot of work to
reconfigure your application's security in the new target environment. Using Spring
Security overcomes these problems, and also brings you dozens of other useful, entirely
Security overcomes these problems, and also brings you dozens of other useful,
customisable security features.</para>
<para>As you probably know, security comprises two major operations. The first is known as
"authentication", which is the process of establishing a principal is who they claim to
be. A "principal" generally means a user, device or some other system which can perform
an action in your application. "Authorization" refers to the process of deciding whether
a principal is allowed to perform an action in your application. To arrive at the point
where an authorization decision is needed, the identity of the principal has already
been established by the authentication process. These concepts are common, and not at
all specific to Spring Security.</para>
<para>As you probably know two major areas of application security are
<quote>authentication</quote> and <quote>authorization</quote> (or
<quote>access-control</quote>). These are the the two main areas that Spring
Security targets. <quote>Authentication</quote> is the process of establishing a
principal is who they claim to be (a <quote>principal</quote> generally means a user,
device or some other system which can perform an action in your application).
<quote>Authorization</quote> refers to the process of deciding whether a principal
is allowed to perform an action within your application. To arrive at the point where an
authorization decision is needed, the identity of the principal has already been
established by the authentication process. These concepts are common, and not at all
specific to Spring Security. </para>
<para>At an authentication level, Spring Security supports a wide range of authentication
models. Most of these authentication models are either provided by third parties, or are
developed by relevant standards bodies such as the Internet Engineering Task Force. In
@ -54,7 +57,8 @@
<para>OpenID authentication</para>
</listitem>
<listitem>
<para>Computer Associates Siteminder</para>
<para>Authentication based on pre-established request headers (such as Computer
Associates Siteminder)</para>
</listitem>
<listitem>
<para>JA-SIG Central Authentication Service (otherwise known as CAS, which is a
@ -80,8 +84,11 @@
<para>Java Authentication and Authorization Service (JAAS)</para>
</listitem>
<listitem>
<para>Container integration with JBoss, Jetty, Resin and Tomcat (so you can still
use Container Manager Authentication if desired)</para>
<para>JEE container autentication (so you can still use Container Managed
Authentication if desired)</para>
</listitem>
<listitem>
<para>Kerberos</para>
</listitem>
<listitem>
<para>Java Open Source Single Sign On (JOSSO) *</para>
@ -142,20 +149,18 @@
differentiate security based on the way a principal is interacting with your
application. For example, you might want to ensure requests only arrive over HTTPS, in
order to protect passwords from eavesdropping or end users from man-in-the-middle
attacks. Or, you might want to ensure that an actual human being is making the requests
and not some robot or other automated process. This is especially helpful to protect
password recovery processes from brute force attacks, or simply to make it harder for
people to duplicate your application's key content. To help you achieve these goals,
Spring Security fully supports automatic "channel security", together with JCaptcha
integration for human user detection.</para>
attacks. This is especially helpful to protect password recovery processes from brute
force attacks, or simply to make it harder for people to duplicate your application's
key content. To help you achieve these goals, Spring Security fully supports automatic
"channel security", together with JCaptcha integration for human user detection.</para>
<para>Irrespective of how authentication was undertaken, Spring Security provides a deep set
of authorization capabilities. There are three main areas of interest in respect of
authorization, these being authorizing web requests, authorizing methods can be invoked,
and authorizing access to individual domain object instances. To help you understand the
differences, consider the authorization capabilities found in the Servlet Specification
web pattern security, EJB Container Managed Security and file system security
respectively. Spring Security provides deep capabilities in all of these important
areas, which we'll explore later in this reference guide.</para>
authorization, these being authorizing web requests, authorizing whether methods can be
invoked, and authorizing access to individual domain object instances. To help you
understand the differences, consider the authorization capabilities found in the Servlet
Specification web pattern security, EJB Container Managed Security and file system
security respectively. Spring Security provides deep capabilities in all of these
important areas, which we'll explore later in this reference guide.</para>
</sect1>
<sect1 xml:id="history">
<title>History</title>

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

@ -21,9 +21,9 @@
]]></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
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><para>You can
find out more about the use of the <literal>ldap-server</literal> element in the chapter
on <link xlink:href="#ldap">LDAP</link>.</para></footnote>. Use of a good XML editor while
beans they need create and what the bean property names are. <footnote><para>You can find out
more about the use of the <literal>ldap-server</literal> element in the chapter on <link
xlink:href="#ldap">LDAP</link>.</para></footnote>. Use of a good XML editor while
editing the application context file should provide information on the attributes and elements
that are available. We would recommend that you try out the <link
xlink:href="http://www.springsource.com/products/sts">SpringSource Tool Suite</link> as it
@ -42,7 +42,7 @@
</beans>
]]></programlisting> In many of the examples you will see (and in the sample) applications, we
will often use "security" as the default namespace rather than "beans", which means we can
omit the prefix on all the security namespace elements, making the context easier to read. You
omit the prefix on all the security namespace elements, making the content easier to read. You
may also want to do this if you have your application context divided up into separate files
and have most of your security configuration in one of them. Your security application context
file would then start like this <programlisting language="xml"><![CDATA[
@ -155,20 +155,25 @@
elements must be within the <literal>authentication-manager</literal> element, which
creates a <classname>ProviderManager</classname> and registers the authentication
providers with it. You can find more detailed information on the beans that are created in
the <link xlink:href="#appendix-namespace">namespace appendix</link>. </para>
the <link xlink:href="#appendix-namespace">namespace appendix</link>. It's worth
cross-checking this if you want to start understanding what the important classes in the
framework are and how they are used, particularly if you want to customise things
later.</para>
</sidebar>
<para> The configuration above defines two users, their passwords and their roles within the
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>
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 the <literal>&lt;authentication-provider&gt;</literal> element means that the
user information will be used by the authentication manager to process authentication
requests. </para>
details on the file format. Using the <literal>&lt;authentication-provider&gt;</literal>
element means that the user information will be used by the authentication manager to
process authentication requests. You can have multiple
<literal>&lt;authentication-provider&gt;</literal> elements to define different
authentication sources and each will be consulted in turn.</para>
<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
application that comes with the project. The above configuration actually adds quite a few
services to the application because we have used the <literal>auto-config</literal>
to log in to proceed. Try it out, or try experimenting with the <quote>tutorial</quote>
sample application that comes with the project. The above configuration actually adds quite
a few services to the application because we have used the <literal>auto-config</literal>
attribute. For example, form-based login processing is automatically enabled. </para>
<section xml:id="ns-auto-config">
<title>What does <literal>auto-config</literal> Include?</title>
@ -179,16 +184,15 @@
<http-basic />
<logout />
</http>
]]>
</programlisting> These other elements are responsible for setting up form-login,
basic authentication and logout handling services respectively <footnote><para>In versions
prior to 3.0, this list also inluded remember-me functionality. This could cause some
]]></programlisting> These other elements are responsible for setting up form-login, basic
authentication and logout handling services respectively <footnote><para>In versions prior
to 3.0, this list also included remember-me functionality. This could cause some
confusing errors with some configurations and was removed in 3.0. In 3.0, the addition
of an <classname>AnonymousProcessingFilter</classname> was made part of the default
of an <classname>AnonymousProcessingFilter</classname> is part of the default
<literal>&lt;http></literal> configuration, so the <literal>&lt;anonymous
/></literal> element is effectively added regardless of whether
<literal>auto-config</literal> is enabled.</para></footnote> . They each have
attributes which can be used to alter their behaviour. </para>
/></literal> element is added regardless of whether <literal>auto-config</literal>
is enabled.</para></footnote> . They each have attributes which can be used to alter
their behaviour. </para>
</section>
<section xml:id="ns-form-and-basic">
<title>Form and Basic Login Options</title>
@ -196,22 +200,39 @@
in, since we made no mention of any HTML files or JSPs. In fact, since we didn't
explicitly set a URL for the login page, Spring Security generates one automatically,
based on the features that are enabled and using standard values for the URL which
processes the submitted login, the default target URL the user will be sent to and so on.
However, the namespace offers plenty of suppport to allow you to customize these options.
For example, if you want to supply your own login page, you could use: <programlisting language="xml"><![CDATA[
processes the submitted login, the default target URL the user will be sent to after
loggin in and so on. However, the namespace offers plenty of support to allow you to
customize these options. For example, if you want to supply your own login page, you could
use: <programlisting language="xml"><![CDATA[
<http auto-config='true'>
<intercept-url pattern="/login.jsp*" filters="none"/>
<intercept-url pattern="/login.jsp*" access="IS_AUTHENTICATED_ANONYMOUSLY"/>
<intercept-url pattern="/**" access="ROLE_USER" />
<form-login login-page='/login.jsp'/>
</http>
]]>
</programlisting> Note that you could still use <literal>auto-config</literal>. The
</programlisting> Note that you can still use <literal>auto-config</literal>. The
<literal>form-login</literal> element just overrides the default settings. Also note
that we've added an extra <literal>intercept-url</literal> element to say that any
requests for the login page should be excluded from processing by the security filters.
Otherwise the request would be matched by the pattern <literal>/**</literal> and it
wouldn't be possible to access the login page itself! If you want to use basic
authentication instead of form login, then change the configuration to <programlisting language="xml"><![CDATA[
requests for the login page should be available to anonymous users <footnote><para>See the
chapter on <link xlink:href="#anonymous">anonymous authentication</link> for more
details.</para></footnote>. Otherwise the request would be matched by the pattern
<literal>/**</literal> and it wouldn't be possible to access the login page itself! This
is a common configuration error and will result in an infinite loop in the application.
Spring Security will emit a warning in the log if your login page appears to be secured.
It is also possible to have all requests matching a particular pattern bypass the security
filter chain completely: <programlisting language="xml"><![CDATA[
<http auto-config='true'>
<intercept-url pattern="/css/**" filters="none"/>
<intercept-url pattern="/login.jsp*" filters="none"/>
<intercept-url pattern="/**" access="ROLE_USER" />
<form-login login-page='/login.jsp'/>
</http>
]]>
</programlisting> Note that these requests will be completely oblivious to Spring
Security, so you will not be able to access information on the current user or call
secured methods during the request. </para>
<para>If you want to use basic authentication instead of form login, then change the
configuration to <programlisting language="xml"><![CDATA[
<http auto-config='true'>
<intercept-url pattern="/**" access="ROLE_USER" />
<http-basic />
@ -501,7 +522,7 @@
and remove any elements which create filters whose functionality you want to replace. </para>
<para> Note that you can't replace filters which are created by the use of the
<literal>&lt;http&gt;</literal> element itself -
<classname>HttpSessionContextIntegrationFilter</classname>,
<classname>SecurityContextPersistenceFilter</classname>,
<classname>ExceptionTranslationFilter</classname> or
<classname>FilterSecurityInterceptor</classname>. </para>
</tip>

53
docs/manual/src/docbook/springsecurity.xml
View File

@ -1,14 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xml:id="spring-security-reference-guide" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<info><title>Spring Security</title><subtitle>Reference Documentation</subtitle><authorgroup>
<author>
<info><title>Spring Security</title><subtitle>Reference
Documentation</subtitle><authorgroup><author>
<personname>Ben Alex</personname>
</author>
<author>
</author><author>
<personname>Luke Taylor</personname>
</author>
</authorgroup>
</author></authorgroup>
<productname>Spring Security</productname>
<releaseinfo>3.0.0.M2</releaseinfo>
</info>
@ -49,15 +47,15 @@
custom requirements make application security interesting, challenging and rewarding. </para>
<para>Please read <xref linkend="getting-started"/>, in its entirety to begin with. This will
introduce you to the framework and the namespace-based configuration system with which you can
get up and running quite quickly. To get more of an understanding of an in-depth understaning
of how Spring Security works, and some of the classes you might need to use, you should then
read <xref linkend="overall-architecture"/>. The remaining parts of this guide are structured
in a more traditional reference style, designed to be read on an as-required basis. We'd also
recommend that you read up as much as possible on application security issues in general.
Spring Security is not a panacea which will solve all security issues. It is important that
the application is designed with security in mind from the start. Attempting to retrofit it is
not a good idea. In particular, if you are building a web application, you should be aware of
the many potential vulnerabilities such as cross-site scripting, request-forgery and
get up and running quite quickly. To get more of an understanding of how Spring Security
works, and some of the classes you might need to use, you should then read <xref
linkend="overall-architecture"/>. The remaining parts of this guide are structured in a more
traditional reference style, designed to be read on an as-required basis. We'd also recommend
that you read up as much as possible on application security issues in general. Spring
Security is not a panacea which will solve all security issues. It is important that the
application is designed with security in mind from the start. Attempting to retrofit it is not
a good idea. In particular, if you are building a web application, you should be aware of the
many potential vulnerabilities such as cross-site scripting, request-forgery and
session-hijacking which you should be taking into account from the start. The OWASP web site
(http://www.owasp.org/) maintains a top ten list of web application vulnerabilities as well as
a lot of useful reference information. </para>
@ -70,12 +68,12 @@
<title>Getting Started</title>
<partintro>
<para>The later parts of this guide provide an in-depth discussion of the framework
architecture and implementation classes, an understanding of which is important if you need
to do any serious customization. In this part, we'll introduce Spring Security 3.0, give a
brief overview of the project's history and take a slightly gentler look at how to get
started using the framework. In particular, we'll look at namespace configuration which
provides a much simpler way of securing your application compared to the traditional Spring
bean approach where you had to wire up all the implementation classes individually. </para>
architecture and implementation classes, which you need to understand if you want to do any
serious customization. In this part, we'll introduce Spring Security 3.0, give a brief
overview of the project's history and take a slightly gentler look at how to get started
using the framework. In particular, we'll look at namespace configuration which provides a
much simpler way of securing your application compared to the traditional Spring bean
approach where you have to wire up all the implementation classes individually. </para>
<para> We'll also take a look at the sample applications that are available. It's worth trying
to run these and experimenting with them a bit even before you read the later sections - you
can dip back into them as your understanding of the framework increases. </para>
@ -115,9 +113,9 @@
<xi:include href="basic-and-digest-auth.xml"/>
<xi:include href="remember-me-authentication.xml"/>
<xi:include href="concurrent-sessions.xml"/>
<xi:include href="anon-auth-provider.xml"/>
<xi:include href="anon-auth-provider.xml"/>
</part>
<!--
<!--
<part xml:id="authentication">
<title>Authentication</title>
<partintro>
@ -141,7 +139,7 @@
</partintro>
<xi:include href="dao-auth-provider.xml"/>
</part>
-->
-->
<part xml:id="authorization">
<title>Authorization</title>
<partintro>
@ -165,15 +163,16 @@
Essentially standalone features which do not have to follow on directly from earlier chapters
-->
<partintro>
<para> In this part we cover some of the more advanced and less-commonly used features of the framework.</para>
<para> In this part we cover some of the more advanced and less-commonly used features of the
framework.</para>
</partintro>
<xi:include href="domain-acls.xml"/>
<xi:include href="domain-acls.xml"/>
<xi:include href="preauth.xml"/>
<xi:include href="ldap-auth-provider.xml"/>
<xi:include href="jaas-auth-provider.xml"/>
<xi:include href="cas-auth-provider.xml"/>
<xi:include href="x509-auth-provider.xml"/>
<xi:include href="runas-auth-provider.xml"/>
<xi:include href="runas-auth-provider.xml"/>
</part>
<xi:include href="appendix-db-schema.xml"/>
<xi:include href="appendix-namespace.xml"/>