Luke Taylor
148 lines
8.1 KiB
XML
148 lines
8.1 KiB
XML
<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>
|
||
|
||
|
||
<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
|
||
(and confirm your Container Adapter is properly configured if you're
|
||
using one).</para>
|
||
|
||
<para>If you build from Subversion, the Contacts sample application
|
||
includes three deployable versions:
|
||
<literal>spring-security-sample-contacts-filter.war</literal> is
|
||
configured with the HTTP Session Authentication approach.
|
||
<literal>spring-security-sample-contacts-ca.war</literal> is
|
||
configured to use a Container Adapter. Finally,
|
||
<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>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>
|
||
|
||
<para>To deploy, simply copy the relevant WAR file from Spring
|
||
Security distribution into your container’s <literal>webapps</literal>
|
||
directory.</para>
|
||
|
||
<para>After starting your container, check the application can load.
|
||
Visit
|
||
<literal>http://localhost:8080/spring-security-sample-contacts-filter</literal>
|
||
(or whichever URL is appropriate for your web container and the WAR
|
||
you deployed). A random contact should be displayed. Click "Refresh"
|
||
several times and you will see different contacts. The business method
|
||
that provides this random contact is not secured.</para>
|
||
|
||
<para>Next, click "Debug". You will be prompted to authenticate, and a
|
||
series of usernames and passwords are suggested on that page. Simply
|
||
authenticate with any of these and view the resulting page. It should
|
||
contain a success message similar to the following:</para>
|
||
|
||
<blockquote>
|
||
<para>Context on SecurityContextHolder is of type:
|
||
org.springframework.security.context.SecurityContextImpl</para>
|
||
|
||
<para>The Context implements SecurityContext.</para>
|
||
|
||
<para>Authentication object is of type:
|
||
org.springframework.security.adapters.PrincipalSpringSecurityUserToken</para>
|
||
|
||
<para>Authentication object as a String:
|
||
org.springframework.security.adapters.PrincipalSpringSecurityUserToken@e9a7c2:
|
||
Username: rod; Password: [PROTECTED]; Authenticated: true; Granted
|
||
Authorities: ROLE_TELLER, ROLE_SUPERVISOR</para>
|
||
|
||
<para>Authentication object holds the following granted
|
||
authorities:</para>
|
||
|
||
<para>ROLE_TELLER (getAuthority(): ROLE_TELLER)</para>
|
||
|
||
<para>ROLE_SUPERVISOR (getAuthority(): ROLE_SUPERVISOR)</para>
|
||
|
||
<para>SUCCESS! Your [container adapter|web filter] appears to be
|
||
properly configured!</para>
|
||
</blockquote>
|
||
|
||
<para>If you receive a different message, and deployed
|
||
<literal>spring-security-sample-contacts-ca.war</literal>, check you
|
||
have properly configured your Container Adapter as described elsewhere
|
||
in this reference guide.</para>
|
||
|
||
<para>Once you successfully receive the above message, return to the
|
||
sample application's home page and click "Manage". You can then try
|
||
out the application. Notice that only the contacts available to the
|
||
currently logged on user are displayed, and only users with
|
||
<literal>ROLE_SUPERVISOR</literal> are granted access to delete their
|
||
contacts. Behind the scenes, the
|
||
<literal>MethodSecurityInterceptor</literal> is securing the business
|
||
objects. If you're using or
|
||
<literal>spring-security-sample-contacts-cas.war</literal>, the
|
||
<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
|
||
will demonstrate access being denied by the
|
||
<literal>FilterSecurityInterceptor</literal>. Note the sample
|
||
application enables you to modify the access control lists associated
|
||
with different contacts. Be sure to give this a try and understand how
|
||
it works by reviewing the sample application's application context XML
|
||
files.</para>
|
||
|
||
<para>The Contacts sample application also include a
|
||
<literal>client</literal> directory. Inside you will find a small
|
||
application that queries the backend business objects using several
|
||
web services protocols. This demonstrates how to use Spring Security
|
||
for authentication with Spring remoting protocols. To try this client,
|
||
ensure your servlet container is still running the Contacts sample
|
||
application, and then execute <literal>client rod koala</literal>. The
|
||
command-line parameters respectively represent the username to use,
|
||
and the password to use. Note that you may need to edit
|
||
<literal>client.properties</literal> to use a different target
|
||
URL.</para>
|
||
</section>
|
||
|
||
<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
|
||
powerful features of domain object access control lists and so on,
|
||
sometimes you just want to start with a nice basic example. The
|
||
tutorial sample is intended to provide this for you.</para>
|
||
|
||
<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 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 xlink:href="form-authentication.xml">form-based</link>
|
||
authentication mechanism is used, with the commonly-used
|
||
<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 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 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 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>
|
||
</section>
|
||
</chapter> |