spring-security/src/docbkx/samples.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="tutorial-sample">
    <info><title>Tutorial Sample</title></info>
    
    <para> The tutorial sample is a nice basic example to get you started. It uses
        simple namespace configuration throughout.
    </para>
    <para>The compiled tutorial is included in the distribution ZIP file,
        ready to be deployed into your web container. 
        The <link xlink:href="#form">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>We recommend you start with the tutorial sample, as the XML is
        minimal and easy to follow. Most importantly, you can easily add 
        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>

<section xml:id="contacts-sample">
    <title xml:id="contacts">Contacts</title>
    
    <para>
        The Contacts Sample is quite an advanced example in that it 
        illustrates the more powerful features of domain object access control lists
        in addition to basic application security.
    </para>
    
    <para>To deploy, simply copy the WAR file from Spring
        Security distribution into your container’s <literal>webapps</literal>
        directory. The war should be called <filename>spring-security-samples-contacts-2.0.0.war</filename>
        (the appended version number will vary depending on what release you are using).
    </para>
    
    <para>After starting your container, check the application can load.
        Visit
        <literal>http://localhost:8080/contacts</literal>
        (or whichever URL is appropriate for your web container and the WAR
        you deployed). </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:
    <literallayout>
        Authentication object is of type: org.springframework.security.providers.UsernamePasswordAuthenticationToken
        
        Authentication object as a String: 
          org.springframework.security.providers.UsernamePasswordAuthenticationToken@1f127853: 
          Principal: org.springframework.security.userdetails.User@b07ed00: 
          Username: rod; Password: [PROTECTED]; Enabled: true; AccountNonExpired: true; 
          credentialsNonExpired: true; AccountNonLocked: true; 
          Granted Authorities: ROLE_SUPERVISOR, ROLE_USER; Password: [PROTECTED]; Authenticated: true; 
          Details: org.springframework.security.ui.WebAuthenticationDetails@0: 
          RemoteIpAddress: 127.0.0.1; SessionId: k5qypsawgpwb; 
          Granted Authorities: ROLE_SUPERVISOR, ROLE_USER
        
        Authentication object holds the following granted authorities:
        
        ROLE_SUPERVISOR (getAuthority(): ROLE_SUPERVISOR)
        ROLE_USER (getAuthority(): ROLE_USER)
        
        SUCCESS! Your web filters appear to be properly configured!        
    </literallayout>
    </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. </para>
         <para>The application allows 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 application context XML files.</para>
<!--
    TODO: Reintroduce standalone client example.
    <para>The Contacts sample application also includes 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>


</chapter>