Cwikius-Spring/spring-security
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-security.git synced 2025-03-03 20:09:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Converted to docbook5

Browse Source
This commit is contained in:
Luke Taylor 2008-04-05 11:57:29 +00:00
parent 9e9b69ec8f
commit b0a892397b
27 changed files with 739 additions and 994 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/docbkx/anon-auth-provider.xml
View File

@ -1,12 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="anonymous"><info><title>Anonymous Authentication</title></info>
<chapter id="anonymous">
<title>Anonymous Authentication</title>
<sect1 id="anonymous-overview">
<title>Overview</title>
<section xml:id="anonymous-overview"><info><title>Overview</title></info>
<para>Particularly in the case of web request URI security, sometimes
it is more convenient to assign configuration attributes against every
@ -22,10 +18,10 @@
<literal>SecurityContextHolder</literal> always contains an
<literal>Authentication</literal> object, and never
<literal>null</literal>.</para>
</sect1>
</section>
<sect1 id="anonymous-config">
<title>Configuration</title>
<section xml:id="anonymous-config"><info><title>Configuration</title></info>
<para>Spring Security provides three classes that together provide an
anonymous authentication feature.
@ -105,5 +101,5 @@
principals would always be deemed "authenticated" and never be given
an opportunity to login via form, basic, digest or some other normal
authentication mechanism</para>
</sect1>
</section>
</chapter>

51
src/docbkx/authorization-common.xml
View File

@ -1,12 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="authorization-common"><info><title>Common Authorization Concepts</title></info>
<chapter id="authorization-common">
<title>Common Authorization Concepts</title>
<sect1 id="authorities">
<title>Authorities</title>
<section xml:id="authorities"><info><title>Authorities</title></info>
<para>As briefly mentioned in the Authentication section, all
<literal>Authentication</literal> implementations are required to
@ -53,10 +49,10 @@
<literal>AuthenticationProvider</literal>s included with the security
architecture use <literal>GrantedAuthorityImpl</literal> to populate
the <literal>Authentication</literal> object.</para>
</sect1>
</section>
<sect1 id="pre-invocation">
<title>Pre-Invocation Handling</title>
<section xml:id="pre-invocation"><info><title>Pre-Invocation Handling</title></info>
<para>The <literal>AccessDecisionManager</literal> is called by the
<literal>AbstractSecurityInterceptor</literal> and is responsible for
@ -100,9 +96,7 @@ public boolean supports(Class clazz);</programlisting></para>
<para><mediaobject>
<imageobject role="html">
<imagedata align="center"
fileref="images/AccessDecisionVoting.gif"
format="GIF" />
<imagedata align="center" fileref="images/AccessDecisionVoting.gif" format="GIF"/>
</imageobject>
<caption>
@ -252,10 +246,10 @@ public boolean supports(Class clazz);</programlisting></para>
<para>TODO: Remove references to the old ACL package when it's
deprecated, and have all references to the replacement package limited
to the chapter describing the new ACL implementation.</para>
</sect1>
</section>
<sect1 id="after-invocation">
<title>After Invocation Handling</title>
<section xml:id="after-invocation"><info><title>After Invocation Handling</title></info>
<para>Whilst the <literal>AccessDecisionManager</literal> is called by
the <literal>AbstractSecurityInterceptor</literal> before proceeding
@ -272,8 +266,7 @@ public boolean supports(Class clazz);</programlisting></para>
<para><mediaobject>
<imageobject>
<imagedata align="center" fileref="images/AfterInvocation.gif"
format="GIF" />
<imagedata align="center" fileref="images/AfterInvocation.gif" format="GIF"/>
</imageobject>
<caption>
@ -314,8 +307,8 @@ public boolean supports(Class clazz);</programlisting></para>
achieved through a <literal>ROLE_USER</literal> or
<literal>ROLE_AUTHENTICATED</literal> configuration attribute</para>
<sect2 id="after-invocation-acl-aware">
<title>ACL-Aware AfterInvocationProviders</title>
<section xml:id="after-invocation-acl-aware"><info><title>ACL-Aware AfterInvocationProviders</title></info>
<para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
ACL module. The new ACL module is a significant rewrite of the
@ -398,10 +391,10 @@ public boolean supports(Class clazz);</programlisting></para>
<para>The Contacts sample application demonstrates these two
<literal>AfterInvocationProvider</literal>s.</para>
</sect2>
</section>
<sect2 id="after-invocation-acl-aware-old">
<title>ACL-Aware AfterInvocationProviders (old ACL module)</title>
<section xml:id="after-invocation-acl-aware-old"><info><title>ACL-Aware AfterInvocationProviders (old ACL module)</title></info>
<para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
ACL module. The new ACL module is a significant rewrite of the
@ -478,11 +471,11 @@ public boolean supports(Class clazz);</programlisting></para>
<para>The Contacts sample application demonstrates these two
<literal>AfterInvocationProvider</literal>s.</para>
</sect2>
</sect1>
</section>
</section>
<sect1 id="authorization-taglibs">
<title>Authorization Tag Libraries</title>
<section xml:id="authorization-taglibs"><info><title>Authorization Tag Libraries</title></info>
<para><literal>AuthorizeTag</literal> is used to include content if
the current principal holds certain
@ -569,5 +562,5 @@ public boolean supports(Class clazz);</programlisting></para>
should be considered deprecated. For the sake of historical reference,
works exactly the samae as
<literal>AccessControlListTag</literal>.</para>
</sect1>
</section>
</chapter>

19
src/docbkx/basic-authentication.xml
View File

@ -1,13 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="basic"><info><title>BASIC Authentication Mechanism</title></info>
<chapter id="basic">
<title>BASIC Authentication Mechanism</title>
<sect1 id="basic-overview">
<title>Overview</title>
<section xml:id="basic-overview"><info><title>Overview</title></info>
<para>Spring Security provides a
<literal>BasicProcessingFilter</literal> which is capable of
@ -21,10 +16,10 @@
is very widely deployed in user agents and implementation is extremely
simple (it's just a Base64 encoding of the username:password,
specified in an HTTP header).</para>
</sect1>
</section>
<sect1 id="basic-config">
<title>Configuration</title>
<section xml:id="basic-config"><info><title>Configuration</title></info>
<para>To implement HTTP Basic Authentication, it is necessary to
define <literal>BasicProcessingFilter</literal> in the filter chain.
@ -61,5 +56,5 @@
only time the filter chain will be interrupted is if authentication
fails and the <literal>AuthenticationEntryPoint</literal> is called,
as discussed in the previous paragraph</para>
</sect1>
</section>
</chapter>

115
src/docbkx/cas-auth-provider.xml
View File

@ -1,12 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="cas"><info><title>CAS Authentication</title></info>
<chapter id="cas">
<title>CAS Authentication</title>
<sect1 id="cas-overview">
<title>Overview</title>
<section xml:id="cas-overview">
<info><title>Overview</title></info>
<para>JA-SIG produces an enterprise-wide single sign on system known
as CAS. Unlike other initiatives, JA-SIG's Central Authentication
@ -24,10 +21,10 @@
file, you will still need the CAS Java Server Pages and
<literal>web.xml</literal> to customise and deploy your CAS
server.</para>
</sect1>
</section>
<sect1 id="cas-how-it-works">
<title>How CAS Works</title>
<section xml:id="cas-how-it-works"><info><title>How CAS Works</title></info>
<para>Whilst the CAS web site above contains two documents that detail
the architecture of CAS, we present the general overview again here
@ -106,7 +103,7 @@
<para>The basic interaction between a web browser, CAS server and n
Spring Security-secured service is as follows:</para>
<orderedlist>
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>The web user is browsing the service's public pages. CAS or
Spring Security is not involved.</para>
@ -301,18 +298,18 @@
<para>It's good that you're still here! It might sound involved, but
you can relax as Spring Security classes hide much of the complexity.
Let's now look at how this is configured</para>
</sect1>
</section>
<sect1 id="cas-server">
<title>Optional CAS Server Setup</title>
<section xml:id="cas-server"><info><title>Optional CAS Server Setup</title></info>
<para>Spring Security can even act as the backend which a CAS version
2.0 or 3.0 server utilises. The configuration approach is described
below. Of course, if you have an existing CAS environment you might
just like to use it instead.</para>
<sect2 id="cas-server-2">
<title>CAS Version 2.0</title>
<section xml:id="cas-server-2"><info><title>CAS Version 2.0</title></info>
<para>As mentioned above, Spring Security includes a
<literal>PasswordHandler</literal> that bridges your existing
@ -402,10 +399,10 @@
web container's documentation on setting up HTTPS, if you need some
additional help or a test certificate you might like to check the
<literal>samples/contacts/etc/ssl</literal> directory</para>
</sect2>
</section>
<sect2 id="cas-server-3">
<title>CAS Version 3.0</title>
<section xml:id="cas-server-3"><info><title>CAS Version 3.0</title></info>
<para>As mentioned above, Spring Security includes an
<literal>AuthenticationHandler</literal> that bridges your existing
@ -493,11 +490,11 @@
additional help or a test certificate you might like to check the
CAS documentation on setting up SSL:
<literal>http://www.ja-sig.org/products/cas/server/ssl/index.html</literal></para>
</sect2>
</sect1>
</section>
</section>
<sect1 id="cas-client">
<title>Configuration of CAS Client</title>
<section xml:id="cas-client"><info><title>Configuration of CAS Client</title></info>
<para>The web application side of CAS is made easy due to Spring
Security. It is assumed you already know the basics of using Spring
@ -508,11 +505,11 @@
to your application context. This represents your service:</para>
<para><programlisting>
<![CDATA[
<bean id="serviceProperties" class="org.springframework.security.ui.cas.ServiceProperties">
<property name="service" value="https://localhost:8443/contacts-cas/j_spring_cas_security_check"/>
<property name="sendRenew"><value>false</value></property>
</bean> ]]>
&lt;bean id="serviceProperties" class="org.springframework.security.ui.cas.ServiceProperties"&gt;
&lt;property name="service" value="https://localhost:8443/contacts-cas/j_spring_cas_security_check"/&gt;
&lt;property name="sendRenew"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
&lt;/bean&gt;
</programlisting></para>
<para>The <literal>service</literal> must equal a URL that will be
@ -526,38 +523,38 @@
<para>The following beans should be configured to commence the CAS
authentication process:</para>
<para><programlisting><![CDATA[
<bean id="casProcessingFilter" class="org.springframework.security.ui.cas.CasProcessingFilter">
<property name="authenticationManager" ref="authenticationManager"/>
<property name="authenticationFailureUrl" value="/casfailed.jsp"/>
<property name="defaultTargetUrl" value="/"/>
<property name="filterProcessesUrl" value="/j_spring_cas_security_check"/>
</bean>
<para><programlisting>
&lt;bean id="casProcessingFilter" class="org.springframework.security.ui.cas.CasProcessingFilter"&gt;
&lt;property name="authenticationManager" ref="authenticationManager"/&gt;
&lt;property name="authenticationFailureUrl" value="/casfailed.jsp"/&gt;
&lt;property name="defaultTargetUrl" value="/"/&gt;
&lt;property name="filterProcessesUrl" value="/j_spring_cas_security_check"/&gt;
&lt;/bean&gt;
<bean id="exceptionTranslationFilter" class="org.springframework.security.ui.ExceptionTranslationFilter">
<property name="authenticationEntryPoint" ref="casProcessingFilterEntryPoint"/>
</bean>
&lt;bean id="exceptionTranslationFilter" class="org.springframework.security.ui.ExceptionTranslationFilter"&gt;
&lt;property name="authenticationEntryPoint" ref="casProcessingFilterEntryPoint"/&gt;
&lt;/bean&gt;
<bean id="casProcessingFilterEntryPoint"
class="org.springframework.security.ui.cas.CasProcessingFilterEntryPoint">
<property name="loginUrl" value="https://localhost:8443/cas/login"/>
<property name="serviceProperties" ref="serviceProperties"/>
</bean>
]]>
&lt;bean id="casProcessingFilterEntryPoint"
class="org.springframework.security.ui.cas.CasProcessingFilterEntryPoint"&gt;
&lt;property name="loginUrl" value="https://localhost:8443/cas/login"/&gt;
&lt;property name="serviceProperties" ref="serviceProperties"/&gt;
&lt;/bean&gt;
</programlisting></para>
<para>You will also need to add the <literal>CasProcessingFilter</literal> to web.xml:</para>
<para><programlisting><![CDATA[
<filter>
<filter-name>casProcessingFilter</filter-name>
<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
<para><programlisting>
&lt;filter&gt;
&lt;filter-name&gt;casProcessingFilter&lt;/filter-name&gt;
&lt;filter-class&gt;org.springframework.web.filter.DelegatingFilterProxy&lt;/filter-class&gt;
&lt;/filter&gt;
<filter-mapping>
<filter-name>casProcessingFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping> ]]>
&lt;filter-mapping&gt;
&lt;filter-name&gt;casProcessingFilter&lt;/filter-name&gt;
&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;
</programlisting></para>
<para>The <literal>CasProcessingFilter</literal> has very similar
@ -671,10 +668,10 @@
<para>There is also a <literal>contacts-cas.war</literal> file in the
sample applications directory. This sample application uses the above
settings and can be deployed to see CAS in operation</para>
</sect1>
</section>
<sect1 id="cas-advanced">
<title>Advanced Issues</title>
<section xml:id="cas-advanced"><info><title>Advanced Issues</title></info>
<para>The <literal>CasAuthenticationProvider</literal> distinguishes
between stateful and stateless clients. A stateful client is
@ -733,5 +730,5 @@
<para>It is hoped you find CAS integration easy and useful with Spring
Security classes. Welcome to enterprise-wide single sign on!</para>
</sect1>
</chapter>
</section>
</chapter>

74
src/docbkx/channel-security.xml
View File

@ -1,14 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="channel-security">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="channel-security">
<title>Channel Security</title>
<info><title>Channel Security</title></info>
<sect1 id="channel-security-overview">
<title>Overview</title>
<section xml:id="channel-security-overview">
<info><title>Overview</title></info>
<para>In addition to coordinating the authentication and authorization
requirements of your application, Spring Security is also able to
@ -37,39 +33,39 @@
<literal>&lt;welcome-file&gt;</literal> points to an HTTPS location,
and the application never directs the user to an HTTP location. Spring
Security provides a solution to assist with the latter.</para>
</sect1>
</section>
<sect1 id="channel-security-config">
<title>Configuration</title>
<section xml:id="channel-security-config"><info><title>Configuration</title></info>
<para>To use chanel security, you should define the following the filter in your application
context:</para>
<para><programlisting><![CDATA[
<bean id="channelProcessingFilter" class="org.springframework.security.securechannel.ChannelProcessingFilter">
<property name="channelDecisionManager" ref="channelDecisionManager"/>
<property name="filterInvocationDefinitionSource">
<security:filter-invocation-definition-source path-type="regex">
<security:intercept-url pattern="\A/secure/.*\Z" access="REQUIRES_SECURE_CHANNEL"/>
<security:intercept-url pattern="\A/acegilogin.jsp.*\" access="REQUIRES_SECURE_CHANNEL"/>
<security:intercept-url pattern="\A/j_spring_security_check.*\Z" access="REQUIRES_SECURE_CHANNEL"/>
<security:intercept-url pattern="\A/.*\Z" access="REQUIRES_INSECURE_CHANNEL"/>
</security:filter-invocation-definition-source>
</property>
</bean>
<para><programlisting>
&lt;bean id="channelProcessingFilter" class="org.springframework.security.securechannel.ChannelProcessingFilter"&gt;
&lt;property name="channelDecisionManager" ref="channelDecisionManager"/&gt;
&lt;property name="filterInvocationDefinitionSource"&gt;
&lt;security:filter-invocation-definition-source path-type="regex"&gt;
&lt;security:intercept-url pattern="\A/secure/.*\Z" access="REQUIRES_SECURE_CHANNEL"/&gt;
&lt;security:intercept-url pattern="\A/acegilogin.jsp.*\" access="REQUIRES_SECURE_CHANNEL"/&gt;
&lt;security:intercept-url pattern="\A/j_spring_security_check.*\Z" access="REQUIRES_SECURE_CHANNEL"/&gt;
&lt;security:intercept-url pattern="\A/.*\Z" access="REQUIRES_INSECURE_CHANNEL"/&gt;
&lt;/security:filter-invocation-definition-source&gt;
&lt;/property&gt;
&lt;/bean&gt;
<bean id="channelDecisionManager" class="org.springframework.security.securechannel.ChannelDecisionManagerImpl">
<property name="channelProcessors">
<list>
<ref bean="secureChannelProcessor"/>
<ref bean="insecureChannelProcessor"/>
</list>
</property>
</bean>
&lt;bean id="channelDecisionManager" class="org.springframework.security.securechannel.ChannelDecisionManagerImpl"&gt;
&lt;property name="channelProcessors"&gt;
&lt;list&gt;
&lt;ref bean="secureChannelProcessor"/&gt;
&lt;ref bean="insecureChannelProcessor"/&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;/bean&gt;
<bean id="secureChannelProcessor" class="org.springframework.security.securechannel.SecureChannelProcessor"/>
<bean id="insecureChannelProcessor" class="org.springframework.security.securechannel.InsecureChannelProcessor"/>
]]>
&lt;bean id="secureChannelProcessor" class="org.springframework.security.securechannel.SecureChannelProcessor"/&gt;
&lt;bean id="insecureChannelProcessor" class="org.springframework.security.securechannel.InsecureChannelProcessor"/&gt;
</programlisting></para>
<para>Like <literal>FilterSecurityInterceptor</literal>, Apache Ant
@ -126,10 +122,10 @@
<literal>REQUIRES_SECURE_CHANNEL</literal>, and that the
<literal>AuthenticationProcessingFilterEntryPoint.forceHttps</literal>
property is <literal>true</literal>.</para>
</sect1>
</section>
<sect1 id="channel-security-conclusion">
<title>Conclusion</title>
<section xml:id="channel-security-conclusion"><info><title>Conclusion</title></info>
<para>Once configured, using the channel security filter is very easy.
Simply request pages without regard to the protocol (ie HTTP or HTTPS)
@ -161,5 +157,5 @@
<literal>AccessDecisionVoter</literal> will ultimately result in an
<literal>AccessDeniedException</literal> (depending on the governing
<literal>AccessDecisionManager</literal>).</para>
</sect1>
</section>
</chapter>

66
src/docbkx/common-auth-services.xml
View File

@ -1,12 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="authentication-common-auth-services"><info><title>Common Authentication Services</title></info>
<chapter id="authentication-common-auth-services">
<title>Common Authentication Services</title>
<sect1 id="mechanisms-providers-entry-points">
<title>Mechanisms, Providers and Entry Points</title>
<section xml:id="mechanisms-providers-entry-points"><info><title>Mechanisms, Providers and Entry Points</title></info>
<para>If you're using Spring Security-provided authentication
approaches, you'll usually need to configure a web filter, together
@ -23,17 +19,17 @@
this:</para>
<para><programlisting>
<![CDATA[
<filter>
<filter-name>filterChainProxy</filter-name>
<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
&lt;filter&gt;
&lt;filter-name&gt;filterChainProxy&lt;/filter-name&gt;
&lt;filter-class&gt;org.springframework.web.filter.DelegatingFilterProxy&lt;/filter-class&gt;
&lt;/filter&gt;
<filter-mapping>
<filter-name>filterChainProxy</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
]]></programlisting></para>
&lt;filter-mapping&gt;
&lt;filter-name&gt;filterChainProxy&lt;/filter-name&gt;
&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;
</programlisting></para>
<para>The above declarations will cause every web request to be passed
through to the bean called <literal>filterChainProxy</literal>
@ -230,10 +226,10 @@
point to use for each authentication approach is discussed in the
authentication approach-specific chapters of this reference
guide.</para>
</sect1>
</section>
<sect1 id="userdetails-and-associated-types">
<title>UserDetails and Associated Types</title>
<section xml:id="userdetails-and-associated-types"><info><title>UserDetails and Associated Types</title></info>
<para>As mentioned in the first part of the reference guide, most
authentication providers take advantage of the
@ -277,8 +273,8 @@
that, Spring Security does include a couple of useful base
implementations, which we'll look at below.</para>
<sect2 id="in-memory-service">
<title>In-Memory Authentication</title>
<section xml:id="in-memory-service"><info><title>In-Memory Authentication</title></info>
<para>Whilst it is easy to use create a custom
<literal>UserDetailsService</literal> implementation that extracts
@ -329,10 +325,10 @@
useful for simple applications that have a larger number of users,
or deployment-time configuration changes, but do not wish to use a
full database for handling authentication details.</para>
</sect2>
</section>
<sect2 id="jdbc-service">
<title>JDBC Authentication</title>
<section xml:id="jdbc-service"><info><title>JDBC Authentication</title></info>
<para>Spring Security also includes a
<literal>UserDetailsService</literal> that can obtain authentication
@ -376,11 +372,11 @@
<literal>UserDetailsService</literal>. The base implementation
provided with Spring Security is intended for typical situations,
and does not offer infinite configuration flexibility.</para>
</sect2>
</sect1>
</section>
</section>
<sect1 id="concurrent-sessions">
<title>Concurrent Session Handling</title>
<section xml:id="concurrent-sessions"><info><title>Concurrent Session Handling</title></info>
<para>Spring Security is able to prevent a principal from concurrently
authenticating to the same application more than a specified number of
@ -433,10 +429,10 @@
&lt;/bean&gt;
&lt;bean id="sessionRegistry" class="org.springframework.security.concurrent.SessionRegistryImpl"/&gt;</programlisting></para>
</sect1>
</section>
<sect1 id="authentication-taglibs">
<title>Authentication Tag Libraries</title>
<section xml:id="authentication-taglibs"><info><title>Authentication Tag Libraries</title></info>
<para><literal>AuthenticationTag</literal> is used to simply output a
property of the current principal's
@ -453,5 +449,5 @@
<literal>UserDetails</literal> object, which is generally the case
when using the typical
<literal>DaoAuthenticationProvider</literal>.</para>
</sect1>
</chapter>
</section>
</chapter>

39
src/docbkx/community.xml
View File

@ -1,12 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="community"
xmlns:xlink="http://www.w3.org/1999/xlink" >
<info><title>Community Support</title></info>
<chapter id="community">
<title>Community Support</title>
<sect1 id="jira">
<title>Use JIRA for Issue Tracking</title>
<section xml:id="jira">
<info><title>Use JIRA for Issue Tracking</title></info>
<para>Spring Security uses JIRA to manage bug reports and enhancement
requests. If you find a bug, please log a report using JIRA. Do not
@ -21,12 +23,11 @@
if you include corresponding unit tests. This is necessary to ensure
project test coverage is adequately maintained.</para>
<para>You can access JIRA at <ulink
url="http://opensource.atlassian.com/projects/spring/secure/BrowseProject.jspa?id=10040"></ulink>.</para>
</sect1>
<para>You can access JIRA at <link xlink:href="http://jira.springframework.org/browse/SEC">http://jira.springframework.org/browse/SEC</link>.</para>
</section>
<sect1 id="becoming-involved">
<title>Becoming Involved</title>
<section xml:id="becoming-involved"><info><title>Becoming Involved</title></info>
<para>We welcome you to become involved in Spring Security project.
There are many ways of contributing, including reading the mailing
@ -38,21 +39,19 @@
Spring Security home page. This explains the path to become a
committer, and the administration approaches we use within the
project.</para>
</sect1>
</section>
<sect1 id="further-info">
<title>Further Information</title>
<section xml:id="further-info"><info><title>Further Information</title></info>
<para>Questions and comments on Spring Security are welcome. Please
use the Spring Community Forum web site at <ulink
url="http://forum.springframework.org"></ulink> for all support
use the Spring Community Forum web site at <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://forum.springframework.org">http://forum.springframework.org</uri> for all support
issues. Remember to use JIRA for bug reports, as explained above.
Everyone is also welcome to join the Acegisecurity-developer mailing
list and participate in design discussions. It's also a good way of
finding out what's happening with regard to release timing, and the
traffic volume is quite light. Finally, our project home page (where
you can obtain the latest release of the project and convenient links
to Subversion, JIRA, mailing lists, forums etc) is at <ulink
url="http://acegisecurity.org"></ulink>.</para>
</sect1>
to Subversion, JIRA, mailing lists, forums etc) is at <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://acegisecurity.org">http://acegisecurity.org</uri>.</para>
</section>
</chapter>

45
src/docbkx/container-adapters.xml
View File

@ -1,12 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ca"><info><title>Container Adapter Authentication</title></info>
<chapter id="ca">
<title>Container Adapter Authentication</title>
<sect1 id="ca-overview">
<title>Overview</title>
<section xml:id="ca-overview">
<info><title>Overview</title></info>
<para>Very early versions of Spring Security exclusively used
Container Adapters for interfacing authentication with end users.
@ -45,10 +42,10 @@
<para>Spring Security currently supports Jetty, Catalina (Tomcat),
JBoss and Resin. Additional container adapters can easily be
written</para>
</sect1>
</section>
<sect1 id="ca-adapter">
<title>Adapter Authentication Provider</title>
<section xml:id="ca-adapter"><info><title>Adapter Authentication Provider</title></info>
<para>As is always the case, the container adapter generated
<literal>Authentication</literal> object still needs to be
@ -103,10 +100,10 @@
<literal>DaoAuthenticationProvider</literal>, ensure you set its
<literal>forcePrincipalAsString</literal> property to
<literal>true</literal>.</para>
</sect1>
</section>
<sect1 id="ca-jetty">
<title>Jetty</title>
<section xml:id="ca-jetty"><info><title>Jetty</title></info>
<para>The following was tested with Jetty 4.2.18.</para>
@ -172,10 +169,10 @@
<literal>&lt;realm-name&gt;</literal> as your
<literal>jetty.xml</literal> (in the example above, "Spring Powered
Realm").</para>
</sect1>
</section>
<sect1 id="ca-jboss">
<title>JBoss</title>
<section xml:id="ca-jboss"><info><title>JBoss</title></info>
<para>The following was tested with JBoss 3.2.6.</para>
@ -302,10 +299,10 @@
<para>JBoss is a widely-used container adapter (mostly due to the need
to support legacy EJBs), so please let us know if you have any
difficulties.</para>
</sect1>
</section>
<sect1 id="ca-resin">
<title>Resin</title>
<section xml:id="ca-resin"><info><title>Resin</title></info>
<para>The following was tested with Resin 3.0.6.</para>
@ -377,10 +374,10 @@
indicated in your <literal>web.xml</literal> does not matter with
Resin, as the relevant authentication class is indicated by the
<literal>&lt;authenticator&gt;</literal> setting</para>
</sect1>
</section>
<sect1 id="ca-tomcat">
<title>Tomcat</title>
<section xml:id="ca-tomcat"><info><title>Tomcat</title></info>
<para>The following was tested with Jakarta Tomcat 4.1.30 and
5.0.19.</para>
@ -449,5 +446,5 @@ cd /
$CATALINA_HOME/bin/startup.sh</programlisting></para>
<para>Finally, restart Tomcat.</para>
</sect1>
</section>
</chapter>

18
src/docbkx/dao-auth-provider.xml
View File

@ -1,12 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dao-provider"><info><title>DAO Authentication Provider</title></info>
<chapter id="dao-provider">
<title>DAO Authentication Provider</title>
<sect1 id="dao-provider-overview">
<title>Overview</title>
<section xml:id="dao-provider-overview"><info><title>Overview</title></info>
<para>Spring Security includes a production-quality
<literal>AuthenticationProvider</literal> implementation called
@ -22,10 +18,10 @@
presented, and the provider will actually evaluate the validity or
otherwise of the password presented in an authentication request
object.</para>
</sect1>
</section>
<sect1 id="dao-provider-config">
<title>Configuration</title>
<section xml:id="dao-provider-config"><info><title>Configuration</title></info>
<para>Aside from adding DaoAuthenticationProvider to your
ProviderManager list (as discussed at the start of this part of the
@ -126,5 +122,5 @@
prior to Spring Security 0.6), you should set the
<literal>DaoAuthenticationProvider.forcePrincipalAsString</literal>
property to <literal>true</literal> in your application context</para>
</sect1>
</section>
</chapter>

20
src/docbkx/digest-authentication.xml
View File

@ -1,12 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="digest">
<title>Digest Authentication</title>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="digest"><info><title>Digest Authentication</title></info>
<sect1 id="digest-overview">
<title>Overview</title>
<section xml:id="digest-overview"><info><title>Overview</title></info>
<para>Spring Security provides a
<literal>DigestProcessingFilter</literal> which is capable of
@ -80,10 +76,10 @@
"<literal>nonce</literal>" token instead. In our testing, Spring
Security implementation works reliably with FireFox and Internet
Explorer, correctly handling nonce timeouts etc.</para>
</sect1>
</section>
<sect1 id="digest-config">
<title>Configuration</title>
<section xml:id="digest-config"><info><title>Configuration</title></info>
<para>Now that we've reviewed the theory, let's see how to use it. To
implement HTTP Digest Authentication, it is necessary to define
@ -141,5 +137,5 @@
if you wish to explore these features in more detail. As far as we are
aware, Spring Security's implementation does comply with the minimum
standards of this RFC.</para>
</sect1>
</section>
</chapter>

28
src/docbkx/domain-acls-old.xml
View File

@ -1,12 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="domain-acls-old">
<info><title>Domain Object Security (old ACL module)</title></info>
<chapter id="domain-acls-old">
<title>Domain Object Security (old ACL module)</title>
<section id="domain-acls-overview-old">
<title>Overview</title>
<section xml:id="domain-acls-overview-old"><info><title>Overview</title></info>
<para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
ACL module. The new ACL module is a significant rewrite of the
@ -35,7 +32,7 @@
more interesting, your customers can allow other users to see their
customer records, such as their "puppy preschool "mentor or president
of their local "Pony Club". Using Spring Security as the foundation,
you have several approaches that can be used:<orderedlist>
you have several approaches that can be used:<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>Write your business methods to enforce the security. You
could consult a collection within the
@ -95,8 +92,8 @@
about below.</para>
</section>
<section id="domain-acls-basic-old">
<title>Basic ACL Package</title>
<section xml:id="domain-acls-basic-old"><info><title>Basic ACL Package</title></info>
<para>Please note that our Basic ACL services are currently being
refactored. We expect release 1.1.0 will contain this new code.
@ -112,8 +109,7 @@
<para><mediaobject>
<imageobject role="html">
<imagedata align="center" fileref="images/ACLSecurity.gif"
format="GIF" />
<imagedata align="center" fileref="images/ACLSecurity.gif" format="GIF"/>
</imageobject>
<caption>
@ -171,8 +167,7 @@ public AclEntry[] getAcls(java.lang.Object domainInstance, Authentication authen
<para><mediaobject>
<imageobject role="html">
<imagedata align="center" fileref="images/BasicAclProvider.gif"
format="GIF" />
<imagedata align="center" fileref="images/BasicAclProvider.gif" format="GIF"/>
</imageobject>
<caption>
@ -463,8 +458,7 @@ END;
<mediaobject>
<imageobject role="html">
<imagedata align="center" fileref="images/Permissions.gif"
format="GIF" />
<imagedata align="center" fileref="images/Permissions.gif" format="GIF"/>
</imageobject>
<caption>

330
src/docbkx/domain-acls.xml
View File

@ -1,181 +1,179 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="domain-acls">
<title>Domain Object Security</title>
<section id="domain-acls-overview">
<title>Overview</title>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="domain-acls">
<para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
ACL module. The new ACL module is a significant rewrite of the
existing ACL module. The new module can be found under the
<literal>org.springframework.security.acls</literal> package, with the
old ACL module under
<literal>org.springframework.security.acl</literal>. We encourage
users to consider testing with the new ACL module and build
applications with it. The old ACL module should be considered
deprecated and may be removed from a future release.</para>
<info><title>Domain Object Security</title></info>
<para>Complex applications often will find the need to define access
permissions not simply at a web request or method invocation level.
Instead, security decisions need to comprise both who
(<literal>Authentication</literal>), where
(<literal>MethodInvocation</literal>) and what
(<literal>SomeDomainObject</literal>). In other words, authorization
decisions also need to consider the actual domain object instance
subject of a method invocation.</para>
<para>Imagine you're designing an application for a pet clinic. There
will be two main groups of users of your Spring-based application:
staff of the pet clinic, as well as the pet clinic's customers. The
staff will have access to all of the data, whilst your customers will
only be able to see their own customer records. To make it a little
more interesting, your customers can allow other users to see their
customer records, such as their "puppy preschool "mentor or president
of their local "Pony Club". Using Spring Security as the foundation,
you have several approaches that can be used:<orderedlist>
<section xml:id="domain-acls-overview"><info><title>Overview</title></info>
<para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
ACL module. The new ACL module is a significant rewrite of the
existing ACL module. The new module can be found under the
<literal>org.springframework.security.acls</literal> package, with the
old ACL module under
<literal>org.springframework.security.acl</literal>. We encourage
users to consider testing with the new ACL module and build
applications with it. The old ACL module should be considered
deprecated and may be removed from a future release.</para>
<para>Complex applications often will find the need to define access
permissions not simply at a web request or method invocation level.
Instead, security decisions need to comprise both who
(<literal>Authentication</literal>), where
(<literal>MethodInvocation</literal>) and what
(<literal>SomeDomainObject</literal>). In other words, authorization
decisions also need to consider the actual domain object instance
subject of a method invocation.</para>
<para>Imagine you're designing an application for a pet clinic. There
will be two main groups of users of your Spring-based application:
staff of the pet clinic, as well as the pet clinic's customers. The
staff will have access to all of the data, whilst your customers will
only be able to see their own customer records. To make it a little
more interesting, your customers can allow other users to see their
customer records, such as their "puppy preschool "mentor or president
of their local "Pony Club". Using Spring Security as the foundation,
you have several approaches that can be used:<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>Write your business methods to enforce the security. You
could consult a collection within the
<literal>Customer</literal> domain object instance to determine
which users have access. By using the
<literal>SecurityContextHolder.getContext().getAuthentication()</literal>,
you'll be able to access the <literal>Authentication</literal>
object.</para>
</listitem>
<listitem>
<para>Write an <literal>AccessDecisionVoter</literal> to enforce
the security from the <literal>GrantedAuthority[]</literal>s
stored in the <literal>Authentication</literal> object. This
would mean your <literal>AuthenticationManager</literal> would
need to populate the <literal>Authentication</literal> with
custom <literal>GrantedAuthority</literal>[]s representing each
of the <literal>Customer</literal> domain object instances the
principal has access to.</para>
</listitem>
<listitem>
<para>Write an <literal>AccessDecisionVoter</literal> to enforce
the security and open the target <literal>Customer</literal>
domain object directly. This would mean your voter needs access
to a DAO that allows it to retrieve the
<literal>Customer</literal> object. It would then access the
<literal>Customer</literal> object's collection of approved
users and make the appropriate decision.</para>
</listitem>
</orderedlist></para>
<para>Each one of these approaches is perfectly legitimate. However,
the first couples your authorization checking to your business code.
The main problems with this include the enhanced difficulty of unit
testing and the fact it would be more difficult to reuse the
<literal>Customer</literal> authorization logic elsewhere. Obtaining
the <literal>GrantedAuthority[]</literal>s from the
<literal>Authentication</literal> object is also fine, but will not
scale to large numbers of <literal>Customer</literal>s. If a user
might be able to access 5,000 <literal>Customer</literal>s (unlikely
in this case, but imagine if it were a popular vet for a large Pony
Club!) the amount of memory consumed and time required to construct
the <literal>Authentication</literal> object would be undesirable. The
final method, opening the <literal>Customer</literal> directly from
external code, is probably the best of the three. It achieves
separation of concerns, and doesn't misuse memory or CPU cycles, but
it is still inefficient in that both the
<literal>AccessDecisionVoter</literal> and the eventual business
method itself will perform a call to the DAO responsible for
retrieving the <literal>Customer</literal> object. Two accesses per
method invocation is clearly undesirable. In addition, with every
approach listed you'll need to write your own access control list
(ACL) persistence and business logic from scratch.</para>
<para>Fortunately, there is another alternative, which we'll talk
about below.</para>
</section>
<section xml:id="domain-acls-key-concepts"><info><title>Key Concepts</title></info>
<para>The org.springframework.security.acls package should be
consulted for its major interfaces. The key interfaces are:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Write your business methods to enforce the security. You
could consult a collection within the
<literal>Customer</literal> domain object instance to determine
which users have access. By using the
<literal>SecurityContextHolder.getContext().getAuthentication()</literal>,
you'll be able to access the <literal>Authentication</literal>
object.</para>
<para><literal>Acl</literal>: Every domain object has one and only
one <literal>Acl</literal> object, which internally holds the
<literal>AccessControlEntry</literal>s as well as knows the owner
of the <literal>Acl</literal>. An Acl does not refer directly to
the domain object, but instead to an
<literal>ObjectIdentity</literal>.</para>
</listitem>
<listitem>
<para>Write an <literal>AccessDecisionVoter</literal> to enforce
the security from the <literal>GrantedAuthority[]</literal>s
stored in the <literal>Authentication</literal> object. This
would mean your <literal>AuthenticationManager</literal> would
need to populate the <literal>Authentication</literal> with
custom <literal>GrantedAuthority</literal>[]s representing each
of the <literal>Customer</literal> domain object instances the
principal has access to.</para>
<para><literal>AccessControlEntry</literal>: An
Acl holds multiple <literal>AccessControlEntry</literal>s, which
are often abbreviated as ACEs in the framework. Each ACE refers to
a specific tuple of <literal>Permission</literal>,
<literal>Sid</literal> and <literal>Acl</literal>. An ACE can also
be granting or non-granting and contain audit settings.</para>
</listitem>
<listitem>
<para>Write an <literal>AccessDecisionVoter</literal> to enforce
the security and open the target <literal>Customer</literal>
domain object directly. This would mean your voter needs access
to a DAO that allows it to retrieve the
<literal>Customer</literal> object. It would then access the
<literal>Customer</literal> object's collection of approved
users and make the appropriate decision.</para>
<para><literal>Permission</literal>: A permission represents an
immutable particular bit mask, and offers convenience functions
for bit masking and outputting information.</para>
</listitem>
</orderedlist></para>
<para>Each one of these approaches is perfectly legitimate. However,
the first couples your authorization checking to your business code.
The main problems with this include the enhanced difficulty of unit
testing and the fact it would be more difficult to reuse the
<literal>Customer</literal> authorization logic elsewhere. Obtaining
the <literal>GrantedAuthority[]</literal>s from the
<literal>Authentication</literal> object is also fine, but will not
scale to large numbers of <literal>Customer</literal>s. If a user
might be able to access 5,000 <literal>Customer</literal>s (unlikely
in this case, but imagine if it were a popular vet for a large Pony
Club!) the amount of memory consumed and time required to construct
the <literal>Authentication</literal> object would be undesirable. The
final method, opening the <literal>Customer</literal> directly from
external code, is probably the best of the three. It achieves
separation of concerns, and doesn't misuse memory or CPU cycles, but
it is still inefficient in that both the
<literal>AccessDecisionVoter</literal> and the eventual business
method itself will perform a call to the DAO responsible for
retrieving the <literal>Customer</literal> object. Two accesses per
method invocation is clearly undesirable. In addition, with every
approach listed you'll need to write your own access control list
(ACL) persistence and business logic from scratch.</para>
<para>Fortunately, there is another alternative, which we'll talk
about below.</para>
</section>
<section id="domain-acls-key-concepts">
<title>Key Concepts</title>
<para>The org.springframework.security.acls package should be
consulted for its major interfaces. The key interfaces are:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal>Acl</literal>: Every domain object has one and only
one <literal>Acl</literal> object, which internally holds the
<literal>AccessControlEntry</literal>s as well as knows the owner
of the <literal>Acl</literal>. An Acl does not refer directly to
the domain object, but instead to an
<literal>ObjectIdentity</literal>.</para>
</listitem>
<listitem>
<para><literal>Sid</literal>: The ACL module needs to refer to
principals and <literal>GrantedAuthority[]</literal>s. A level of
indirection is provided by the <literal>Sid</literal> interface.
Common classes include <literal>PrincipalSid</literal> (to
represent the principal inside an
<literal>Authentication</literal> object) and
<literal>GrantedAuthoritySid</literal>.</para>
</listitem>
<listitem>
<para><literal>ObjectIdentity</literal>: Each domain object is
represented internally within the ACL module by an
<literal>ObjectIdentity</literal>.</para>
</listitem>
<listitem>
<para><literal>AclService</literal>: Retrieves the
<literal>Acl</literal> applicable for a given
<literal>ObjectIdentity</literal>.</para>
</listitem>
<listitem>
<para><literal>MutableAclService</literal>: Allows a modified
<literal>Acl</literal> to be presented for persistence. It is not
essential to use this interface if you do not wish.</para>
</listitem>
</itemizedlist>
<listitem>
<para><literal><literal>AccessControlEntry</literal></literal>: An
Acl holds multiple <literal>AccessControlEntry</literal>s, which
are often abbreviated as ACEs in the framework. Each ACE refers to
a specific tuple of <literal>Permission</literal>,
<literal>Sid</literal> and <literal>Acl</literal>. An ACE can also
be granting or non-granting and contain audit settings.</para>
</listitem>
<para>The ACL module was based on extensive feedback from the user
community following real-world use of the original ACL module. This
feedback resulted in a rearchitecture of the ACL module to offer
significantly enhanced performance (particularly in the area of
database retrieval), significantly better encapsulation, higher
cohesion, and enhanced customisation points.</para>
<listitem>
<para><literal>Permission</literal>: A permission represents an
immutable particular bit mask, and offers convenience functions
for bit masking and outputting information.</para>
</listitem>
<para>The Contacts Sample that ships with Acegi Security 1.0.3 offers
a demonstration of the new ACL module. Converting Contacts from using
the old module to the new module was relatively simple, and users of
the old ACL module will likely find their applications can be modified
with relatively little work.</para>
<listitem>
<para><literal>Sid</literal>: The ACL module needs to refer to
principals and <literal>GrantedAuthority[]</literal>s. A level of
indirection is provided by the <literal>Sid</literal> interface.
Common classes include <literal>PrincipalSid</literal> (to
represent the principal inside an
<literal>Authentication</literal> object) and
<literal>GrantedAuthoritySid</literal>.</para>
</listitem>
<listitem>
<para><literal>ObjectIdentity</literal>: Each domain object is
represented internally within the ACL module by an
<literal>ObjectIdentity</literal>.</para>
</listitem>
<listitem>
<para><literal>AclService</literal>: Retrieves the
<literal>Acl</literal> applicable for a given
<literal>ObjectIdentity</literal>.</para>
</listitem>
<listitem>
<para><literal>MutableAclService</literal>: Allows a modified
<literal>Acl</literal> to be presented for persistence. It is not
essential to use this interface if you do not wish.</para>
</listitem>
</itemizedlist>
<para>The ACL module was based on extensive feedback from the user
community following real-world use of the original ACL module. This
feedback resulted in a rearchitecture of the ACL module to offer
significantly enhanced performance (particularly in the area of
database retrieval), significantly better encapsulation, higher
cohesion, and enhanced customisation points.</para>
<para>The Contacts Sample that ships with Acegi Security 1.0.3 offers
a demonstration of the new ACL module. Converting Contacts from using
the old module to the new module was relatively simple, and users of
the old ACL module will likely find their applications can be modified
with relatively little work.</para>
<para>We will document the new ACL module more fully with a subsequent
release. Please note that the new ACL module should be considered a
preview only (ie do not use in production without proper prior
testing), and there is a small chance there may be changes between
1.0.3 and 1.1.0 when it will become final. Nevertheless,
compatibility-affecting changes are considered quite unlikely,
especially given the module is already based on several years of
feedback from users of the original ACL module.</para>
</section>
<para>We will document the new ACL module more fully with a subsequent
release. Please note that the new ACL module should be considered a
preview only (ie do not use in production without proper prior
testing), and there is a small chance there may be changes between
1.0.3 and 1.1.0 when it will become final. Nevertheless,
compatibility-affecting changes are considered quite unlikely,
especially given the module is already based on several years of
feedback from users of the original ACL module.</para>
</section>
</chapter>

37
src/docbkx/form-authentication.xml
View File

@ -1,36 +1,33 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="form">
<title>Form Authentication Mechanism</title>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="form"><info><title>Form Authentication Mechanism</title></info>
<sect1 id="form-overview">
<title>Overview</title>
<section xml:id="form-overview">
<info><title>Overview</title></info>
<para>HTTP Form Authentication involves using the
<literal>AuthenticationProcessingFilter</literal> to process a login
form. This is the most common way that application authenticate end
users. Form-based authentication is entirely compatible with the DAO
and JAAS authentication providers.</para>
</sect1>
</section>
<sect1 id="form-config">
<title>Configuration</title>
<section xml:id="form-config"><info><title>Configuration</title></info>
<para>The login form simply contains <literal>j_username</literal> and
<literal>j_password</literal> input fields, and posts to a URL that is
monitored by the filter (by default
<literal>j_spring_security_check</literal>). You should add an
<literal>AuthenticationProcessingFilter</literal> to you application context:
<programlisting><![CDATA[
<bean id="authenticationProcessingFilter"
class="org.springframework.security.ui.webapp.AuthenticationProcessingFilter">
<property name="authenticationManager" ref="authenticationManager"/>
<property name="authenticationFailureUrl" value="/acegilogin.jsp?login_error=1"/>
<property name="defaultTargetUrl" value="/"/>
<property name="filterProcessesUrl" value="/j_spring_security_check"/>
</bean> ]]>
<programlisting>
&lt;bean id="authenticationProcessingFilter"
class="org.springframework.security.ui.webapp.AuthenticationProcessingFilter"&gt;
&lt;property name="authenticationManager" ref="authenticationManager"/&gt;
&lt;property name="authenticationFailureUrl" value="/acegilogin.jsp?login_error=1"/&gt;
&lt;property name="defaultTargetUrl" value="/"/&gt;
&lt;property name="filterProcessesUrl" value="/j_spring_security_check"/&gt;
&lt;/bean&gt;
</programlisting></para>
<para>The configured <literal>AuthenticationManager</literal>
@ -58,5 +55,5 @@
If for some reason the <literal>HttpSession</literal> does not
indicate the target URL, the browser will be redirected to the
<literal>defaultTargetUrl</literal> property.</para>
</sect1>
</section>
</chapter>

16
src/docbkx/introduction.xml
View File

@ -1,12 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="introduction">
<chapter version="5.0" xml:id="introduction"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Introduction</title>
<sect1 id="what-is-acegi-security">
<sect1 xml:id="what-is-acegi-security">
<title>What is Spring Security?</title>
<para>Spring Security provides comprehensive security services for
@ -173,8 +173,8 @@
</listitem>
</itemizedlist>
<para>(* Denotes provided by a third party; check our <ulink
url="http://acegisecurity.org/powering.html">integration page</ulink>
<para>(* Denotes provided by a third party; check our <link
xlink:href="http://acegisecurity.org/powering.html">integration page</link>
for links to the latest details)</para>
<para>Many independent software vendors (ISVs) adopt Spring Security
@ -214,7 +214,7 @@
which we'll explore later in this reference guide.</para>
</sect1>
<sect1 id="history">
<sect1 xml:id="history">
<title>History</title>
<para>Spring Security began in late 2003 as "The Acegi Security System
@ -261,7 +261,7 @@
peers.</para>
</sect1>
<sect1 id="release-numbering">
<sect1 xml:id="release-numbering">
<title>Release Numbering</title>
<para>It is useful to understand how Spring Security release numbers

73
src/docbkx/jaas-auth-provider.xml
View File

@ -1,12 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="jaas">
<title>Java Authentication and Authorization Service (JAAS)
Provider</title>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="jaas"><info><title>Java Authentication and Authorization Service (JAAS)
Provider</title></info>
<sect1 id="jaas-overview">
<title>Overview</title>
<section xml:id="jaas-overview"><info><title>Overview</title></info>
<para>Spring Security provides a package able to delegate
authentication requests to the Java Authentication and Authorization
@ -17,10 +14,10 @@
reference documentation available from Sun Microsystems. We expect you
to have a basic understanding of JAAS and its login configuration file
syntax in order to understand this section.</para>
</sect1>
</section>
<sect1 id="jaas-config">
<title>Configuration</title>
<section xml:id="jaas-config"><info><title>Configuration</title></info>
<para>The <literal>JaasAuthenticationProvider</literal> attempts to
authenticate a user’s principal and credentials through JAAS.</para>
@ -39,34 +36,34 @@
above JAAS login configuration file:</para>
<para><programlisting>
<![CDATA[ &lt;bean id="jaasAuthenticationProvider"
class="org.springframework.security.providers.jaas.JaasAuthenticationProvider"&gt;
&lt;property name="loginConfig"&gt;
&lt;value&gt;/WEB-INF/login.conf&lt;/value&gt;
&lt;/property&gt;
&lt;property name="loginContextName"&gt;
&lt;value&gt;JAASTest&lt;/value&gt;
&lt;/property&gt;
&lt;property name="callbackHandlers"&gt;
&lt;list&gt;
&lt;bean class="org.springframework.security.providers.jaas.JaasNameCallbackHandler"/&gt;
&lt;bean class="org.springframework.security.providers.jaas.JaasPasswordCallbackHandler"/&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;property name="authorityGranters"&gt;
&lt;list&gt;
&lt;bean class="org.springframework.security.providers.jaas.TestAuthorityGranter"/&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;/bean&gt; ]]>
&amp;lt;bean id="jaasAuthenticationProvider"
class="org.springframework.security.providers.jaas.JaasAuthenticationProvider"&amp;gt;
&amp;lt;property name="loginConfig"&amp;gt;
&amp;lt;value&amp;gt;/WEB-INF/login.conf&amp;lt;/value&amp;gt;
&amp;lt;/property&amp;gt;
&amp;lt;property name="loginContextName"&amp;gt;
&amp;lt;value&amp;gt;JAASTest&amp;lt;/value&amp;gt;
&amp;lt;/property&amp;gt;
&amp;lt;property name="callbackHandlers"&amp;gt;
&amp;lt;list&amp;gt;
&amp;lt;bean class="org.springframework.security.providers.jaas.JaasNameCallbackHandler"/&amp;gt;
&amp;lt;bean class="org.springframework.security.providers.jaas.JaasPasswordCallbackHandler"/&amp;gt;
&amp;lt;/list&amp;gt;
&amp;lt;/property&amp;gt;
&amp;lt;property name="authorityGranters"&amp;gt;
&amp;lt;list&amp;gt;
&amp;lt;bean class="org.springframework.security.providers.jaas.TestAuthorityGranter"/&amp;gt;
&amp;lt;/list&amp;gt;
&amp;lt;/property&amp;gt;
&amp;lt;/bean&amp;gt;
</programlisting></para>
<para>The <literal>CallbackHandler</literal>s and
<literal>AuthorityGranter</literal>s are discussed below.</para>
<sect2 id="jaas-callbackhandler">
<title id="jaas-callback-handler">JAAS CallbackHandler</title>
<section xml:id="jaas-callbackhandler"><info><title xml:id="jaas-callback-handler">JAAS CallbackHandler</title></info>
<para>Most JAAS <literal>LoginModule</literal>s require a callback
of some sort. These callbacks are usually used to obtain the
@ -103,10 +100,10 @@
<literal>InternalCallbackHandler</literal>s, the callback is in-turn
passed to the <literal>JaasAuthenticationCallbackHandler</literal>s
being wrapped.</para>
</sect2>
</section>
<sect2 id="jaas-authoritygranter">
<title id="jaas-authority-granter">JAAS AuthorityGranter</title>
<section xml:id="jaas-authoritygranter"><info><title xml:id="jaas-authority-granter">JAAS AuthorityGranter</title></info>
<para>JAAS works with principals. Even "roles" are represented as
principals in JAAS. Spring Security, on the other hand, works with
@ -142,6 +139,6 @@
<literal>TestAuthorityGranter</literal> in the unit tests that
demonstrates a simple <literal>AuthorityGranter</literal>
implementation.</para>
</sect2>
</sect1>
</section>
</section>
</chapter>

234
src/docbkx/ldap-auth-provider.xml
View File

@ -1,10 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="ldap">
<title>LDAP Authentication</title>
<sect1 id="ldap-overview">
<title>Overview</title>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ldap"><info><title>LDAP Authentication</title></info>
<section xml:id="ldap-overview"><info><title>Overview</title></info>
<para>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.</para>
@ -14,17 +11,16 @@
configured to handle a wide range of situations.</para>
<para>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: <ulink
url="http://www.zytrax.com/books/ldap/"/>. Some familiarity with the JNDI APIs used
setting up a directory using the free LDAP server OpenLDAP: <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.zytrax.com/books/ldap/">http://www.zytrax.com/books/ldap/</uri>. 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.</para>
</sect1>
<sect1>
<title>Using LDAP with Spring Security</title>
</section>
<section><info><title>Using LDAP with Spring Security</title></info>
<para> LDAP authentication in Spring Security can be roughly divided into the following
stages. <orderedlist>
stages. <orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>Obtaining the unique LDAP <quote>Distinguished Name</quote>, or DN, from
the login name. This will often mean performing a search in the directory,
@ -45,57 +41,56 @@
<para> 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). </para>
</sect1>
<sect1>
<title>Configuring an LDAP Server</title>
</section>
<section><info><title>Configuring an LDAP Server</title></info>
<para> The first thing you need to do is configure the server against which authentication
should take place. This is done using the <literal>&lt;ldap-server&gt;</literal> element
from the security namespace. This can be configured to point at an external LDAP server,
using the <literal>url</literal> attribute: <programlisting><![CDATA[
<ldap-server url="ldap://springframework.org:389/dc=springframework,dc=org" />
]]></programlisting></para>
<sect2>
<title>Using an Embedded Test Server</title>
using the <literal>url</literal> attribute: <programlisting>
&lt;ldap-server url="ldap://springframework.org:389/dc=springframework,dc=org" /&gt;
</programlisting></para>
<section><info><title>Using an Embedded Test Server</title></info>
<para> The <literal>&lt;ldap-server&gt;</literal> 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 <literal>url</literal> attribute: <programlisting><![CDATA[
<ldap-server root="dc=springframework,dc=org"/>
]]></programlisting> Here we've specified that the root DIT of the directory should be
case you use it without the <literal>url</literal> attribute: <programlisting>
&lt;ldap-server root="dc=springframework,dc=org"/&gt;
</programlisting> Here we've specified that the root DIT of the directory should be
<quote>dc=springframework,dc=org</quote>, 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 <literal>ldif</literal> attribute, which defines
an LDIF resource to be loaded: <programlisting><![CDATA[
<ldap-server ldif="classpath:users.ldif" />
]]></programlisting> This makes it a lot easier to get up and running with LDAP, since it can be
an LDIF resource to be loaded: <programlisting>
&lt;ldap-server ldif="classpath:users.ldif" /&gt;
</programlisting> 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 <olink targetdoc="sample-apps"
targetptr="ldap">LDAP sample application</olink>. </para>
</sect2>
<sect2>
<title>Using Bind Authentication</title>
application to use. These can be obtained from the LDAP sample application. </para>
</section>
<section><info><title>Using Bind Authentication</title></info>
<para> This is the most common LDAP authentication scenario. <programlisting>
<![CDATA[
<ldap-authentication-provider user-dn-pattern="uid={0},ou=people"/>
]]></programlisting> This simple example would obtain the DN for the user by
&lt;ldap-authentication-provider user-dn-pattern="uid={0},ou=people"/&gt;
</programlisting> 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: <programlisting>
<![CDATA[
<ldap-authentication-provider user-search-filter="(uid={0})" user-search-base="ou=people"/>
]]></programlisting> If used with the server definition above, this would
&lt;ldap-authentication-provider user-search-filter="(uid={0})" user-search-base="ou=people"/&gt;
</programlisting> If used with the server definition above, this would
perform a search under the DN <literal>ou=people,dc=springframework,dc=org</literal>
using the value of the <literal>user-search-filter</literal> attribute as a filter.
Again the user login name is substituted for the parameter in the filter name. If
<literal>user-search-base</literal> isn't supplied, the search will be performed
from the root. </para>
</sect2>
<sect2>
<title>Loading Authorities</title>
</section>
<section><info><title>Loading Authorities</title></info>
<para> How authorities are loaded from groups in the LDAP directory is controlled by the
following attributes. <itemizedlist>
<listitem>
@ -109,27 +104,24 @@
</listitem>
<listitem>
<para><literal>group-search-filter</literal>. The filter which is used to
search for group membership. The default is <literal
>uniqueMember={0}</literal>, corresponding to the <literal
>groupOfUniqueMembers</literal> LDAP class. In this case, the
search for group membership. The default is <literal>uniqueMember={0}</literal>, corresponding to the <literal>groupOfUniqueMembers</literal> LDAP class. In this case, the
substituted parameter is the full distinguished name of the user. The
parameter <literal>{1}</literal> can be used if you want to filter on
the login name.</para>
</listitem>
</itemizedlist> So if we used the following configuration <programlisting>
<![CDATA[
<ldap-authentication-provider user-dn-pattern="uid={0},ou=people group-search-base="ou=groups" />
]]></programlisting> and authenticated successfully as user <quote>ben</quote>,
&lt;ldap-authentication-provider user-dn-pattern="uid={0},ou=people group-search-base="ou=groups" /&gt;
</programlisting> and authenticated successfully as user <quote>ben</quote>,
the subsequent loading of authorities would perform a search under the directory
entry <literal>ou=groups,dc=springframework,dc=org</literal>, looking for entries
which contain the attribute <literal>uniqueMember</literal> with value <literal
>uid=ben,ou=people,dc=springframework,dc=org</literal>. For more information on
which contain the attribute <literal>uniqueMember</literal> with value <literal>uid=ben,ou=people,dc=springframework,dc=org</literal>. For more information on
loading authorities, see the Javadoc for the
<classname>DefaultLdapAuthoritiesPopulator</classname> class. </para>
</sect2>
</sect1>
<sect1>
<title>Implementation Classes</title>
</section>
</section>
<section><info><title>Implementation Classes</title></info>
<para>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
@ -146,8 +138,8 @@
<interfacename>LdapAuthoritiesPopulator</interfacename> which are responsible for
authenticating the user and retrieving the user's set of
<interfacename>GrantedAuthority</interfacename>s respectively.</para>
<sect2 id="ldap-ldap-authenticators">
<title>LdapAuthenticator Implementations</title>
<section xml:id="ldap-ldap-authenticators"><info><title>LdapAuthenticator Implementations</title></info>
<para>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
@ -166,8 +158,8 @@
value is never retrieved.</para>
</listitem>
</itemizedlist></para>
<sect3 id="ldap-ldap-authenticators-common">
<title>Common Functionality</title>
<section xml:id="ldap-ldap-authenticators-common"><info><title>Common Functionality</title></info>
<para>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
@ -181,35 +173,34 @@
server</link> for more information on this). For example, if you are using an
LDAP server with the URL <literal>ldap://monkeymachine.co.uk/dc=springframework,dc=org</literal>, and have a
pattern <literal>uid={0},ou=greatapes</literal>, then a login name of "gorilla"
will map to a DN <literal
>uid=gorilla,ou=greatapes,dc=springframework,dc=org</literal>. Each configured
will map to a DN <literal>uid=gorilla,ou=greatapes,dc=springframework,dc=org</literal>. Each configured
DN pattern will be tried in turn until a match is found. For information on
using a search, see the section on <link linkend="ldap-searchobjects">search
objects</link> 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.</para>
</sect3>
<sect3 id="ldap-ldap-authenticators-bind">
<title>BindAuthenticator</title>
</section>
<section xml:id="ldap-ldap-authenticators-bind"><info><title>BindAuthenticator</title></info>
<para>The class
<classname>org.springframework.security.providers.ldap.authenticator.BindAuthenticator</classname>
implements the bind authentication strategy. It simply attempts to bind as the
user.</para>
</sect3>
<sect3 id="ldap-ldap-authenticators-password">
<title>PasswordComparisonAuthenticator</title>
</section>
<section xml:id="ldap-ldap-authenticators-password"><info><title>PasswordComparisonAuthenticator</title></info>
<para>The class
<classname>org.springframework.security.providers.ldap.authenticator.PasswordComparisonAuthenticator</classname>
implements the password comparison authentication strategy.</para>
</sect3>
<sect3 id="ldap-ldap-authenticators-active-directory">
<title>Active Directory Authentication</title>
</section>
<section xml:id="ldap-ldap-authenticators-active-directory"><info><title>Active Directory Authentication</title></info>
<para>In addition to standard LDAP authentication (binding with a DN), Active
Directory has its own non-standard syntax for user authentication.</para>
</sect3>
</sect2>
<sect2 id="ldap-context-source">
<title>Connecting to the LDAP Server</title>
</section>
</section>
<section xml:id="ldap-context-source"><info><title>Connecting to the LDAP Server</title></info>
<para>The beans discussed above have to be able to connect to the server. They both have
to be supplied with a <interfacename>SpringSecurityContextSource</interfacename>
which is an extension of Spring LDAP's <interfacename>ContextSource</interfacename>.
@ -220,59 +211,54 @@
server (instead of binding anonymously). For more information read the Javadoc for
this class and for Spring LDAP's <classname>AbstractContextSource</classname>.
</para>
</sect2>
<sect2 id="ldap-searchobjects">
<title>LDAP Search Objects</title>
</section>
<section xml:id="ldap-searchobjects"><info><title>LDAP Search Objects</title></info>
<para>Often more a more complicated strategy than simple DN-matching is required to
locate a user entry in the directory. This can be encapsulated in an
<interfacename>LdapUserSearch</interfacename> instance which can be supplied to
the authenticator implementations, for example, to allow them to locate a user. The
supplied implementation is <classname>FilterBasedLdapUserSearch</classname>.</para>
<sect3 id="ldap-searchobjects-filter">
<title id="ldap-searchobjects-filter-based"
><classname>FilterBasedLdapUserSearch</classname></title>
<section xml:id="ldap-searchobjects-filter"><info><title xml:id="ldap-searchobjects-filter-based"><classname>FilterBasedLdapUserSearch</classname></title></info>
<para>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
<ulink
url="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/directory/DirContext.html#search(javax.naming.Name,%20java.lang.String,%20java.lang.Object[],%20javax.naming.directory.SearchControls)"
>JDK DirContext class</ulink>. As explained there, the search filter can be
supplied with parameters. For this class, the only valid parameter is <parameter
>{0}</parameter> which will be replaced with the user's login name.</para>
</sect3>
</sect2>
<sect2 id="ldap-bean-config">
<title>Spring Bean Configuration</title>
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/directory/DirContext.html#search(javax.naming.Name,%20java.lang.String,%20java.lang.Object[],%20javax.naming.directory.SearchControls)">JDK DirContext class</link>. As explained there, the search filter can be
supplied with parameters. For this class, the only valid parameter is <parameter>{0}</parameter> which will be replaced with the user's login name.</para>
</section>
</section>
<section xml:id="ldap-bean-config"><info><title>Spring Bean Configuration</title></info>
<para>A typical configuration, using some of the beans we've discussed here, might look
like this: <programlisting>
<![CDATA[
<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>
&lt;bean id="contextSource"
class="org.springframework.security.ldap.DefaultSpringSecurityContextSource"&gt;
&lt;constructor-arg value="ldap://monkeymachine:389/dc=springframework,dc=org"/&gt;
&lt;property name="userDn" value="cn=manager,dc=springframework,dc=org"/&gt;
&lt;property name="password" value="password"/&gt;
&lt;/bean&gt;
<bean id="ldapAuthProvider"
class="org.springframework.security.providers.ldap.LdapAuthenticationProvider">
<constructor-arg>
<bean class="org.springframework.security.providers.ldap.authenticator.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.populator.DefaultLdapAuthoritiesPopulator">
<constructor-arg ref="contextSource"/>
<constructor-arg value="ou=groups"/>
<property name="groupRoleAttribute" value="ou"/>
</bean>
</constructor-arg>
</bean>
]]>
&lt;bean id="ldapAuthProvider"
class="org.springframework.security.providers.ldap.LdapAuthenticationProvider"&gt;
&lt;constructor-arg&gt;
&lt;bean class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator"&gt;
&lt;constructor-arg ref="contextSource"/&gt;
&lt;property name="userDnPatterns"&gt;&lt;list&gt;&lt;value&gt;uid={0},ou=people&lt;/value&gt;&lt;/list&gt;&lt;/property&gt;
&lt;/bean&gt;
&lt;/constructor-arg&gt;
&lt;constructor-arg&gt;
&lt;bean class="org.springframework.security.ldap.populator.DefaultLdapAuthoritiesPopulator"&gt;
&lt;constructor-arg ref="contextSource"/&gt;
&lt;constructor-arg value="ou=groups"/&gt;
&lt;property name="groupRoleAttribute" value="ou"/&gt;
&lt;/bean&gt;
&lt;/constructor-arg&gt;
&lt;/bean&gt;
</programlisting> This would set up the provider to access an LDAP server with URL
<literal>ldap://monkeymachine:389/dc=springframework,dc=org</literal>.
Authentication will be performed by attempting to bind with the DN <literal
>uid=&lt;user-login-name&gt;,ou=people,dc=springframework,dc=org</literal>. After
Authentication will be performed by attempting to bind with the DN <literal>uid=&lt;user-login-name&gt;,ou=people,dc=springframework,dc=org</literal>. After
successful authentication, roles will be assigned to the user by searching under the DN
<literal>ou=groups,dc=springframework,dc=org</literal> with the default filter
<literal>(member=&lt;user's-DN&gt;)</literal>. The role name will be taken from the
@ -280,18 +266,18 @@
<para>To configurae a user search object, which uses the filter
<literal>(uid=&lt;user-login-name&gt;)</literal> for use instead of the
DN-pattern (or in addition to it), you would configure the following bean
<programlisting><![CDATA[
<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" />
<property name="searchSubtree" value="true"/>
</bean> ]]>
<programlisting>
&lt;bean id="userSearch"
class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch"&gt;
&lt;constructor-arg index="0" value=""/&gt;
&lt;constructor-arg index="1" value="(uid={0})"/&gt;
&lt;constructor-arg index="2" ref="contextSource" /&gt;
&lt;property name="searchSubtree" value="true"/&gt;
&lt;/bean&gt;
</programlisting>
and use it by setting the authenticator's <property>userSearch</property> property. The authenticator
would then call the search object to obtain the correct user's DN before attempting to bind as this user.</para>
</sect2>
</sect1>
</section>
</section>
</chapter>
</chapter>

19
src/docbkx/remember-me-authentication.xml
View File

@ -1,12 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="remember-me"><info><title>Remember-Me Authentication</title></info>
<chapter id="remember-me">
<title>Remember-Me Authentication</title>
<sect1 id="remember-me-overview">
<title>Overview</title>
<section xml:id="remember-me-overview">
<info><title>Overview</title></info>
<para>Remember-me authentication refers to web sites being able to
remember the identity of a principal between sessions. This is
@ -16,10 +13,10 @@
that such operations can take place, along with providing a concrete
implementation that uses hashing to preserve the security of
cookie-based tokens.</para>
</sect1>
</section>
<sect1 id="remember-me-config">
<title>Configuration</title>
<section xml:id="remember-me-config"><info><title>Configuration</title></info>
<para>Remember-me authentication is not used with basic
authentication, given it is often not used with
@ -117,5 +114,5 @@
a call to <literal>RememberMeProcessingFilter</literal> into your
<literal>FilterChainProxy</literal> (typically immediately after your
<literal>AuthenticationProcessingFilter</literal>)</para>
</sect1>
</section>
</chapter>

20
src/docbkx/runas-auth-provider.xml
View File

@ -1,12 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="runas">
<title>Run-As Authentication Replacement</title>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="runas"><info><title>Run-As Authentication Replacement</title></info>
<sect1 id="runas-overview">
<title>Overview</title>
<section xml:id="runas-overview"><info><title>Overview</title></info>
<para>The <literal>AbstractSecurityInterceptor</literal> is able to
temporarily replace the <literal>Authentication</literal> object in
@ -30,10 +26,10 @@
remoting protocols based on the contents of the
<literal>SecurityContextHolder</literal>, these run-as replacements
are particularly useful when calling remote web services</para>
</sect1>
</section>
<sect1 id="runas-config">
<title>Configuration</title>
<section xml:id="runas-config"><info><title>Configuration</title></info>
<para>A <literal>RunAsManager</literal> interface is provided by Acegi
Security:</para>
@ -107,5 +103,5 @@
<literal>RunAsManagerImpl</literal>. The
<literal>RunAsUserToken</literal> is immutable after creation for
security reasons</para>
</sect1>
</section>
</chapter>

44
src/docbkx/samples.xml
View File

@ -1,12 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sample-apps">
<info><title xml:id="samples">Sample Applications</title></info>
<chapter id="sample-apps">
<title id="samples">Sample Applications</title>
<sect1 id="contacts-sample">
<title id="contacts">Contacts</title>
<section xml:id="contacts-sample">
<info><title xml:id="contacts">Contacts</title></info>
<para>Included with Spring Security is a very simple application that
can demonstrate the basic security facilities provided by the system
@ -22,7 +21,7 @@
<literal>spring-security-sample-contacts-cas.war</literal> is designed
to work with a JA-SIG CAS server. If you're just wanting to see how
the sample application works, please use
<literal><literal>spring-security-sample-contacts-filter.war</literal></literal>
<literal>spring-security-sample-contacts-filter.war</literal>
as it does not require special configuration of your container. This
is also the artifact included in official release ZIPs.</para>
@ -82,7 +81,7 @@
<literal>MethodSecurityInterceptor</literal> is securing the business
objects. If you're using or
<literal>spring-security-sample-contacts-cas.war</literal>, the
<literal><literal>spring-security-sample-contacts-filter.war</literal></literal>
<literal>spring-security-sample-contacts-filter.war</literal>
<literal>FilterSecurityInterceptor</literal> is also securing the HTTP
requests. If using either of these WARs, be sure to try visiting
<literal>http://localhost:8080/contacts/secure/super</literal>, which
@ -104,10 +103,10 @@
and the password to use. Note that you may need to edit
<literal>client.properties</literal> to use a different target
URL.</para>
</sect1>
</section>
<sect1 id="tutorial-sample">
<title>Tutorial Sample</title>
<section xml:id="tutorial-sample"><info><title>Tutorial Sample</title></info>
<para>Whilst the <link linkend="contacts-sample">Contacts
Sample</link> is quite advanced in that it illustrates the more
@ -117,36 +116,33 @@
<para>The compiled tutorial is included in the distribution ZIP file,
ready to be deployed into your web container. Authentication is
handled by the <link linkend="dao-provider">DaoAuthenticationProvider</link>, using the
<link linkend="in-memory-service">in-memory</link>
handled by the <link xlink:href="dao-auth-provider.xml">DaoAuthenticationProvider</link>, using the
<link xlink:href="in-memory-service">in-memory</link>
<literal>UserDetailsService</literal> that sources information from
the <literal>users.properties</literal> file located in the WAR's
<literal>/WEB-INF</literal> directory. The <link linkend="form">form-based</link>
<literal>/WEB-INF</literal> directory. The <link xlink:href="form-authentication.xml">form-based</link>
authentication mechanism is used, with the commonly-used
<link linkend="remember-me">remember-me</link>
<link xlink:href="#remember-me">remember-me</link>
authentication provider used to automatically remember the login using
cookies.</para>
<para>In terms of authorization, to keep things simple we've
configured the tutorial to only perform some basic <link
linkend="filter-invocation-authorization">web filter
authorization</link>. We've wired two common <link
linkend="pre-invocation">pre-invocation access decision voters</link>,
configured the tutorial to only perform some basic <link xlink:href="#filter-invocation-authorization">web filter
authorization</link>. We've wired two common <link xlink:href="#pre-invocation">pre-invocation access decision voters</link>,
being the <literal>RoleVoter</literal> and
<literal>AuthenticatedVoter</literal>, such that
<literal>ROLE_*</literal> configuration attributes and
<literal>IS_AUTHENTICATED_*</literal> configuration attributes may be
used. Of course, it's extremely easy to add in other providers, with
most users probably starting with some services-layer security using
<link linkend="aop-alliance">MethodSecurityInterceptor</link>.</para>
<link xlink:href="#aop-alliance">MethodSecurityInterceptor</link>.</para>
<para>We recommend you start with the tutorial sample, as the XML is
minimal and easy to follow. All of the needed <link
linkend="filters">filters</link> are configured properly, and using
minimal and easy to follow. All of the needed <link xlink:href="#supporting-infrastructure">filters</link> are configured properly, and using
best practise. Most importantly, you can easily this one XML file (and
its corresponding <literal>web.xml</literal> entries) to your existing
application. Only when this basic integration is achieved do we
suggest you attempt adding in method authorization or domain object
security.</para>
</sect1>
</section>
</chapter>

70
src/docbkx/secured-objects.xml
View File

@ -1,12 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="secure-object-impls"><info><title>Secure Object Implementations</title></info>
<chapter id="secure-object-impls">
<title>Secure Object Implementations</title>
<sect1 id="aop-alliance">
<title>AOP Alliance (MethodInvocation) Security Interceptor</title>
<section xml:id="aop-alliance"><info><title>AOP Alliance (MethodInvocation) Security Interceptor</title></info>
<para>To secure <literal>MethodInvocation</literal>s, developers
simply add a properly configured
@ -215,10 +211,10 @@ public float getBalance(int id);
&lt;/property&gt;
&lt;property name="proxyTargetClass" value="true"/&gt;
&lt;/bean&gt; </programlisting>
</sect1>
</section>
<sect1 id="aspectj">
<title>AspectJ (JoinPoint) Security Interceptor</title>
<section xml:id="aspectj"><info><title>AspectJ (JoinPoint) Security Interceptor</title></info>
<para>The AspectJ security interceptor is very similar to the AOP
Alliance security interceptor discussed in the previous section.
@ -338,10 +334,10 @@ if (this.securityInterceptor == null)
your application, using whatever means you think fit (eg <literal>new
Person();</literal>) and they will have the security interceptor
applied.</para>
</sect1>
</section>
<sect1 id="filter-invocation-authorization">
<title>FilterInvocation Security Interceptor</title>
<section xml:id="filter-invocation-authorization"><info><title>FilterInvocation Security Interceptor</title></info>
<para>To secure <classname>FilterInvocation</classname>s, developers need
to add a <literal>FilterSecurityInterceptor</literal> to their filter chain.
@ -350,30 +346,30 @@ if (this.securityInterceptor == null)
<para>In the application context you will need to configure three
beans:</para>
<programlisting><![CDATA[
<bean id="exceptionTranslationFilter"
class="org.springframework.security.ui.ExceptionTranslationFilter">
<property name="authenticationEntryPoint"><ref local="authenticationEntryPoint"/></property>
</bean>
<programlisting>
&lt;bean id="exceptionTranslationFilter"
class="org.springframework.security.ui.ExceptionTranslationFilter"&gt;
&lt;property name="authenticationEntryPoint"&gt;&lt;ref local="authenticationEntryPoint"/&gt;&lt;/property&gt;
&lt;/bean&gt;
<bean id="authenticationEntryPoint"
class="org.springframework.security.ui.webapp.AuthenticationProcessingFilterEntryPoint">
<property name="loginFormUrl"><value>/acegilogin.jsp</value></property>
<property name="forceHttps"><value>false</value></property>
</bean>
&lt;bean id="authenticationEntryPoint"
class="org.springframework.security.ui.webapp.AuthenticationProcessingFilterEntryPoint"&gt;
&lt;property name="loginFormUrl"&gt;&lt;value&gt;/acegilogin.jsp&lt;/value&gt;&lt;/property&gt;
&lt;property name="forceHttps"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
&lt;/bean&gt;
<bean id="filterSecurityInterceptor"
class="org.springframework.security.intercept.web.FilterSecurityInterceptor">
<property name="authenticationManager"><ref bean="authenticationManager"/></property>
<property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property>
<property name="objectDefinitionSource">
<property name="filterInvocationDefinitionSource">
<security:filter-invocation-definition-source path-type="regex">
<security:intercept-url pattern="\A/secure/super/.*\Z" access="ROLE_WE_DONT_HAVE"/>
<security:intercept-url pattern="\A/secure/.*\" access="ROLE_SUPERVISOR,ROLE_TELLER"/>
</security:filter-invocation-definition-source>
</property>
</bean> ]]> </programlisting>
&lt;bean id="filterSecurityInterceptor"
class="org.springframework.security.intercept.web.FilterSecurityInterceptor"&gt;
&lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
&lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
&lt;property name="objectDefinitionSource"&gt;
&lt;property name="filterInvocationDefinitionSource"&gt;
&lt;security:filter-invocation-definition-source path-type="regex"&gt;
&lt;security:intercept-url pattern="\A/secure/super/.*\Z" access="ROLE_WE_DONT_HAVE"/&gt;
&lt;security:intercept-url pattern="\A/secure/.*\" access="ROLE_SUPERVISOR,ROLE_TELLER"/&gt;
&lt;/security:filter-invocation-definition-source&gt;
&lt;/property&gt;
&lt;/bean&gt; </programlisting>
<para>The <classname>ExceptionTranslationFilter</classname> provides
the bridge between Java exceptions and HTTP responses. It is solely
@ -496,5 +492,5 @@ if (this.securityInterceptor == null)
<literal>AccessDecisionManager</literal> or the
<literal>RunAsManager</literal>. If neither of these can process a
given configuration attribute, an exception is thrown.</para>
</sect1>
</section>
</chapter>

18
src/docbkx/siteminder-auth-provider.xml
View File

@ -1,12 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="siteminder"><info><title>Siteminder Authentication Mechanism</title></info>
<chapter id="siteminder">
<title>Siteminder Authentication Mechanism</title>
<sect1 id="siteminder-overview">
<title>Overview</title>
<section xml:id="siteminder-overview"><info><title>Overview</title></info>
<para>Siteminder is a commercial single sign on solution by Computer
Associates.</para>
@ -29,10 +25,10 @@
identifies the authenticated principal (please refer to your
organization's "single sign-on" group for header details in your
particular configuration).</para>
</sect1>
</section>
<sect1 id="siteminder-config">
<title>Configuration</title>
<section xml:id="siteminder-config"><info><title>Configuration</title></info>
<para>The first step in setting up Spring Security's Siteminder
support is to define the authentication mechanism that will inspect
@ -80,5 +76,5 @@
support form-based authentication in your development environment
(where Siteminder is typically not installed), specify the form's
username parameter as well. Just don't do this in production!</para>
</sect1>
</section>
</chapter>

54
src/docbkx/springsecurity.xml
View File

@ -1,25 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<bookinfo>
<title>Spring Security</title>
<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>
<author>
<personname>Ben Alex</personname>
</author>
<releaseinfo>2.0-SNAPSHOT</releaseinfo>
</info>
<toc/>
<subtitle>Reference Documentation</subtitle>
<releaseinfo>2.0-SNAPSHOT</releaseinfo>
<authorgroup>
<author>
<firstname>Ben</firstname>
<surname>Alex</surname>
</author>
</authorgroup>
</bookinfo>
<toc></toc>
<preface id="preface">
<preface xml:id="preface">
<title>Preface</title>
<para>Spring Security provides a comprehensive security solution for
@ -76,13 +75,13 @@
basis.</para>
<para>We hope that you find this reference guide useful, and we welcome
your feedback and <link linkend="jira">suggestions</link>.</para>
your feedback and <link xlink:href="#jira">suggestions</link>.</para>
<para>Finally, welcome to the Spring Security <link linkend="community" >community</link>.
<para>Finally, welcome to the Spring Security <link xlink:href="#community" >community</link>.
</para>
</preface>
<part id="overall-architecture">
<part xml:id="overall-architecture">
<title>Overall Architecture</title>
<partintro>
@ -103,10 +102,9 @@
<xi:include href="channel-security.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="taglibs.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</part>
<part id="authentication">
<part xml:id="authentication">
<title>Authentication</title>
<partintro>
@ -122,8 +120,6 @@
<xi:include href="dao-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="jaas-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="siteminder-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="runas-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
@ -147,7 +143,7 @@
</part>
<part id="authorization">
<part xml:id="authorization">
<title>Authorization</title>
<partintro>
@ -175,7 +171,7 @@
</part>
<part id="resources">
<part xml:id="resources">
<title>Other Resources</title>
<partintro>

58
src/docbkx/supporting-infrastructure.xml
View File

@ -1,17 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="supporting-infrastructure">
<title>Supporting Infrastructure</title>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="supporting-infrastructure"><info><title>Supporting Infrastructure</title></info>
<para>This chapter introduces some of the supplementary and supporting
infrastructure used by Spring Security. If a capability is not directly
related to security, yet included in the Spring Security project, we
will discuss it in this chapter.</para>
<sect1 id="localization">
<title>Localization</title>
<section xml:id="localization"><info><title>Localization</title></info>
<para>Spring Security supports localization of exception messages that
end users are likely to see. If your application is designed for
@ -75,10 +71,10 @@
<literal>CookieLocaleResolver</literal>,
<literal>FixedLocaleResolver</literal>,
<literal>SessionLocaleResolver</literal> etc)</para>
</sect1>
</section>
<sect1 id="filters">
<title>Filters</title>
<section xml:id="filters"><info><title>Filters</title></info>
<para>Spring Security uses many filters, as referred to throughout the
remainder of this reference guide. You have a choice in how these
@ -90,17 +86,17 @@
something like this in the web.xml file:
<programlisting>
<![CDATA[
<filter>
<filter-name>myFilter</filter-name>
<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
&lt;filter&gt;
&lt;filter-name&gt;myFilter&lt;/filter-name&gt;
&lt;filter-class&gt;org.springframework.web.filter.DelegatingFilterProxy&lt;/filter-class&gt;
&lt;/filter&gt;
<filter-mapping>
<filter-name>myFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
]]>
&lt;filter-mapping&gt;
&lt;filter-name&gt;myFilter&lt;/filter-name&gt;
&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;
</programlisting>
Notice that the filter is actually a <literal>DelegatingFilterProxy</literal>,
@ -149,13 +145,13 @@
The filter chain is then declared in the application context, using
code such as this:</para>
<para><programlisting><![CDATA[
<bean id="filterChainProxy" class="org.springframework.security.util.FilterChainProxy">
<sec:filter-chain-map path-type="ant">
<sec:filter-chain pattern="/webServices/**" filters="httpSessionContextIntegrationFilterWithASCFalse,basicProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor"/>
<sec:filter-chain pattern="/**" filters="httpSessionContextIntegrationFilterWithASCTrue,authenticationProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor"/>
</sec:filter-chain-map>
</bean> ]]> </programlisting></para>
<para><programlisting>
&lt;bean id="filterChainProxy" class="org.springframework.security.util.FilterChainProxy"&gt;
&lt;sec:filter-chain-map path-type="ant"&gt;
&lt;sec:filter-chain pattern="/webServices/**" filters="httpSessionContextIntegrationFilterWithASCFalse,basicProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor"/&gt;
&lt;sec:filter-chain pattern="/**" filters="httpSessionContextIntegrationFilterWithASCTrue,authenticationProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor"/&gt;
&lt;/sec:filter-chain-map&gt;
&lt;/bean&gt; </programlisting></para>
<para>You may notice similarities with the way
<literal>FilterSecurityInterceptor</literal> is declared. Both regular
@ -228,7 +224,7 @@
using, the order of the <literal>&lt;filter-mapping&gt;</literal>s
should be as follows:</para>
<orderedlist>
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para><literal>ChannelProcessingFilter</literal>, because it might
need to redirect to a different protocol</para>
@ -276,7 +272,7 @@
<literal>SecurityContextHolder</literal>, and the request presents
a cookie that enables remember-me services to take place, a
suitable remembered
<literal><literal>Authentication</literal></literal> object will
<literal>Authentication</literal> object will
be put there</para>
</listitem>
@ -312,5 +308,5 @@
before the SiteMesh filters are called. This enables the
<literal>SecurityContextHolder</literal> to be populated in time for
use by SiteMesh decorators</para>
</sect1>
</section>
</chapter>

23
src/docbkx/taglibs.xml
View File

@ -1,16 +1,17 @@
<chapter id="taglib">
<title>Tag Libraries</title>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="taglib">
<info><title>Tag Libraries</title></info>
<sect1 id="taglib-overview">
<title>Overview</title>
<section xml:id="taglib-overview"><info><title>Overview</title></info>
<para>Spring Security comes bundled with several JSP tag libraries
that eases JSP writing. The tag libraries provide a range of different
services.</para>
</sect1>
</section>
<sect1 id="taglib-config">
<title>Configuration</title>
<section xml:id="taglib-config"><info><title>Configuration</title></info>
<para>All taglib classes are included in the core
<literal>spring-security-xx.jar</literal> file, with the
@ -28,10 +29,10 @@
&lt;taglib-uri&gt;http://www.springframework.org/security/tags&lt;/taglib-uri&gt;
&lt;taglib-location&gt;/WEB-INF/security.tld&lt;/taglib-location&gt;
&lt;/taglib&gt; </programlisting></para>
</sect1>
</section>
<sect1 id="taglib-usage">
<title>Usage</title>
<section xml:id="taglib-usage"><info><title>Usage</title></info>
<para>Now that you've configured the tag libraries, refer to the
individual reference guide sections for details on how to use them.
@ -40,5 +41,5 @@
&lt;%@ taglib prefix='security' uri='http://www.springframework.org/security/tags' %&gt;
</programlisting></para>
</sect1>
</section>
</chapter>

48
src/docbkx/technical-overview.xml
View File

@ -1,12 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="technical-overview"><info><title>Technical Overview</title></info>
<chapter id="technical-overview">
<title>Technical Overview</title>
<sect1 id="runtime-environment">
<title>Runtime Environment</title>
<section xml:id="runtime-environment"><info><title>Runtime Environment</title></info>
<para>Spring Security is written to execute within a standard Java 1.4
Runtime Environment. It also supports Java 5.0, although the Java
@ -25,10 +21,10 @@
<para>This above design offers maximum deployment time flexibility, as
you can simply copy your target artifact (be it a JAR, WAR or EAR)
from one system to another and it will immediately work.</para>
</sect1>
</section>
<sect1 id="shared-components">
<title>Shared Components</title>
<section xml:id="shared-components"><info><title>Shared Components</title></info>
<para>Let's explore some of the most important shared components in
Spring Security. Components are considered "shared" if they are
@ -223,10 +219,10 @@ String username = obj.toString();
<para>Now that you've gained an understanding of these repeatedly-used
components, let's take a closer look at the process of
authentication.</para>
</sect1>
</section>
<sect1 id="common-authentication">
<title>Authentication</title>
<section xml:id="common-authentication"><info><title>Authentication</title></info>
<para>As mentioned in the beginning of this reference guide, Spring
Security can participate in many different authentication
@ -241,7 +237,7 @@ String username = obj.toString();
<para>Consider a typical web application's authentication
process:</para>
<orderedlist>
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>You visit the home page, and click on a link.</para>
</listitem>
@ -385,10 +381,10 @@ String username = obj.toString();
from a location, build a Spring Security-specific Authentication
object, and put it onto the SecurityContextHolder. It's quite easy to
do this, and it is a fully-supported integration approach.</para>
</sect1>
</section>
<sect1 id="secure-objects">
<title>Secure Objects</title>
<section xml:id="secure-objects"><info><title>Secure Objects</title></info>
<para>If you're familiar with AOP, you'd be aware there are different
types of advice available: before, after, throws and around. An around
@ -479,15 +475,11 @@ String username = obj.toString();
<para><mediaobject>
<imageobject role="html">
<imagedata align="center"
fileref="images/SecurityInterception.gif"
format="GIF" />
<imagedata align="center" fileref="images/SecurityInterception.gif" format="GIF"/>
</imageobject>
<imageobject role="fo">
<imagedata align="center"
fileref="images/SecurityInterception.gif"
format="GIF" />
<imagedata align="center" fileref="images/SecurityInterception.gif" format="GIF"/>
</imageobject>
<caption>
@ -507,10 +499,10 @@ String username = obj.toString();
<literal>JoinPoint</literal> and web request
<literal>FilterInterceptor</literal>) with complete
transparency.</para>
</sect1>
</section>
<sect1 id="common-conclusion">
<title>Conclusion</title>
<section xml:id="common-conclusion"><info><title>Conclusion</title></info>
<para>Congratulations! You have enough of a high-level picture of
Spring Security to embark on your project. We've explored the shared
@ -518,5 +510,5 @@ String username = obj.toString();
authorization concept of a "secure object". Everything that follows in
this reference guide may or may not apply to your particular needs,
and can be read in any order.</para>
</sect1>
</section>
</chapter>

48
src/docbkx/x509-auth-provider.xml
View File

@ -1,10 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="x509">
<title>X.509 Authentication</title>
<sect1 id="x509-overview">
<title>Overview</title>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="x509"><info><title>X.509 Authentication</title></info>
<section xml:id="x509-overview"><info><title>Overview</title></info>
<para>The most common use of X.509 certificate authentication is in verifying the identity
of a server when using SSL, most commonly when using HTTPS from a browser. The browser
will automatically check that the certificate presented by a server has been issued (ie
@ -22,25 +19,22 @@
<para>You should be familiar with using certificates and setting up client authentication
for your servlet container before attempting to use it with Spring Security. Most of the
work is in creating and installing suitable certificates and keys. For example, if
you're using Tomcat then read the instructions here <ulink
url="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html"/>. It's important that
you're using Tomcat then read the instructions here <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html">http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html</uri>. It's important that
you get this working before trying it out with Spring Security</para>
</sect1>
<sect1>
<title>Adding X.509 Authentication to Your Web Application</title>
<para> Enabling X.509 client authentication is very straightforward. Just add the <literal
>&lt;x509/&gt;</literal> element to your http security namespace configuration. <programlisting><![CDATA[
<http>
</section>
<section><info><title>Adding X.509 Authentication to Your Web Application</title></info>
<para> Enabling X.509 client authentication is very straightforward. Just add the <literal>&lt;x509/&gt;</literal> element to your http security namespace configuration. <programlisting>
&lt;http&gt;
...
<x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/>
&lt;x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/&gt;
...
</http>]]>
&lt;/http&gt;
</programlisting> The element has two optional attributes: <itemizedlist>
<listitem>
<para><literal>subject-principal-regex</literal>. The regular expression used to
extract a username from the certificate's subject name. The default value is
shown above. This is the username which will be passed to the <literal
>UserDetailsService</literal> to load the authorities for the
shown above. This is the username which will be passed to the <literal>UserDetailsService</literal> to load the authorities for the
user.</para>
</listitem>
<listitem>
@ -59,9 +53,9 @@
security context. If no certificate is found, or no corresponding user could be found
then the security context will remain empty. This means that you can easily use X.509
authentication with other options such as a form-based login. </para>
</sect1>
<sect1 id="x509-ssl-config">
<title>Setting up SSL in Tomcat</title>
</section>
<section xml:id="x509-ssl-config"><info><title>Setting up SSL in Tomcat</title></info>
<para>There are some pre-generated certificates in the
<filename>samples/certificate</filename> directory in the Spring Security project.
You can use these to enable SSL for testing if you don't want to generate your own. The file
@ -74,19 +68,19 @@
To run tomcat with SSL support, drop the <filename>server.jks</filename> file into the
tomcat <filename>conf</filename> directory and add the following connector to the
<filename>server.xml</filename> file
<programlisting><![CDATA[
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true"
<programlisting>
&lt;Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true"
clientAuth="true" sslProtocol="TLS"
keystoreFile="${catalina.home}/conf/server.jks"
keystoreType="JKS" keystorePass="password"
truststoreFile="${catalina.home}/conf/server.jks"
truststoreType="JKS" truststorePass="password"
/> ]]>
/&gt;
</programlisting>
<parameter>clientAuth</parameter> can also be set to <parameter>want</parameter> if you still
want SSL connections to succeed even if the client doesn't provide a certificate.
Clients which don't present a certificate won't be able to access any objects secured by
Spring Security unless you use a non-X.509 authentication mechanism, such as form authentication.
</para>
</sect1>
</chapter>
</section>
</chapter>

148
src/docbkx/xml-auth-provider.xml
View File

@ -1,148 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="x509">
<title>X509 Authentication</title>
<sect1 id="x509-overview">
<title>Overview</title>
<para>The most common use of X509 certificate authentication is in
verifying the identity of a server when using SSL, most commonly when
using HTTPS from a browser. The browser will automatically check that
the certificate presented by a server has been issued (ie digitally
signed) by one of a list of trusted certificate authorities which it
maintains.</para>
<para>You can also use SSL with <quote>mutual authentication</quote>;
the server will then request a valid certificate from the client as
part of the SSL handshake. The server will authenticate the client by
checking that it's certificate is signed by an acceptable authority.
If a valid certificate has been provided, it can be obtained through
the servlet API in an application. Spring Security X509 module
extracts the certificate using a filter and passes it to the
configured X509 authentication provider to allow any additional
application-specific checks to be applied. It also maps the
certificate to an application user and loads that user's set of
granted authorities for use with the standard Spring Security
infrastructure.</para>
<para>You should be familiar with using certificates and setting up
client authentication for your servlet container before attempting to
use it with Spring Security. Most of the work is in creating and
installing suitable certificates and keys. For example, if you're
using Tomcat then read the instructions here <ulink
url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html"></ulink>.
It's important that you get this working before trying it out with
Spring Security</para>
</sect1>
<sect1 id="x509-with-acegi">
<title>Using X509 with Spring Security</title>
<para>With X509 authentication, there is no explicit login procedure
so the implementation is relatively simple; there is no need to
redirect requests in order to interact with the user. As a result,
some of the classes behave slightly differently from their equivalents
in other packages. For example, the default <quote>entry point</quote>
class, which is normally responsible for starting the authentication
process, is only invoked if the certificate is rejected and it always
returns an error to the user. With a suitable bean configuration, the
normal sequence of events is as follows <orderedlist>
<listitem>
<para>The <classname>X509ProcessingFilter</classname> extracts
the certificate from the request and uses it as the credentials
for an authentication request. The generated authentication
request is an <classname>X509AuthenticationToken</classname>.
The request is passed to the authentication manager.</para>
</listitem>
<listitem>
<para>The <classname>X509AuthenticationProvider</classname>
receives the token. Its main concern is to obtain the user
information (in particular the user's granted authorities) that
matches the certificate. It delegates this responsibility to an
<interfacename>X509AuthoritiesPopulator</interfacename>.</para>
</listitem>
<listitem>
<para>The populator's single method,
<methodname>getUserDetails(X509Certificate
userCertificate)</methodname> is invoked. Implementations should
return a <classname>UserDetails</classname> instance containing
the array of <classname>GrantedAuthority</classname> objects for
the user. This method can also choose to reject the certificate
(for example if it doesn't contain a matching user name). In
such cases it should throw a
<exceptionname>BadCredentialsException</exceptionname>. A
DAO-based implementation,
<classname>DaoX509AuthoritiesPopulator</classname>, is provided
which extracts the user's name from the subject <quote>common
name</quote> (CN) in the certificate. It also allows you to set
your own regular expression to match a different part of the
subject's distinguished name. A UserDetailsService is used to
load the user information.<!-- TODO: Give email matching as an example --></para>
</listitem>
<listitem>
<para>If everything has gone smoothly then there should be a
valid <classname>Authentication</classname> object in the secure
context and the invocation will procede as normal. If no
certificate was found, or the certificate was rejected, then the
<classname>ExceptionTranslationFilter</classname> will invoke
the <classname>X509ProcessingFilterEntryPoint</classname> which
returns a 403 error (forbidden) to the user.</para>
</listitem>
</orderedlist></para>
</sect1>
<sect1 id="x509-config">
<title>Configuration</title>
<para>There is a version of the <link
linkend="contacts-sample">Contacts Sample Application</link> which
uses X509. Copy the beans and filter setup from this as a starting
point for configuring your own application. A set of example
certificates is also included which you can use to configure your
server. These are <itemizedlist>
<listitem>
<para><filename>user.p12</filename>: A PKCS12 format file
containing the client key and certificate. These should be
installed in your browser. It maps to a use in the
application.</para>
</listitem>
<listitem>
<para><filename>server.p12</filename>: The server certificate
and key for HTTPS connections.</para>
</listitem>
<listitem>
<para><filename>ca.jks</filename>: A Java keystore containing
the certificate for the authority which issued the user's
certificate. This will be used by the container to validate
client certificates.</para>
</listitem>
</itemizedlist> For JBoss 3.2.7 (with Tomcat 5.0), the SSL
configuration in the <filename>server.xml</filename> file looks like
this <programlisting>
&lt;!-- SSL/TLS Connector configuration --&gt;
&lt;Connector port="8443" address="${jboss.bind.address}"
maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
scheme="https" secure="true"
sslProtocol = "TLS"
clientAuth="true" keystoreFile="${jboss.server.home.dir}/conf/server.p12"
keystoreType="PKCS12" keystorePass="password"
truststoreFile="${jboss.server.home.dir}/conf/ca.jks"
truststoreType="JKS" truststorePass="password"
/&gt;
</programlisting><parameter>clientAuth</parameter> can also be set to
<parameter>want</parameter> if you still want SSL connections to
succeed even if the client doesn't provide a certificate. Obviously
these clients won't be able to access any objects secured by Spring
Security (unless you use a non-X509 authentication mechanism, such as
BASIC authentication, to authenticate the user)</para>
</sect1>
</chapter>