

[[sample-apps]]
== Sample Applications
There are several sample web applications that are available with the project.
To avoid an overly large download, only the "tutorial" and "contacts" samples are included in the distribution zip file.
The others can be built directly from the source which you can obtain as described in <<get-source,the introduction>>.
It's easy to build the project yourself and there's more information on the project web site at http://spring.io/spring-security/[http://spring.io/spring-security/].
All paths referred to in this chapter are relative to the project source directory.


[[tutorial-sample]]
=== Tutorial Sample
The tutorial sample is a nice basic example to get you started.
It uses simple namespace configuration throughout.
The compiled application is included in the distribution zip file, ready to be deployed into your web container (`spring-security-samples-tutorial-3.1.x.war`).
The <<ns-form-and-basic,form-based>> authentication mechanism is used in combination with the commonly-used <<remember-me,remember-me>> authentication provider to automatically remember the login using cookies.

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 `web.xml` 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.


[[contacts-sample]]
=== Contacts
The Contacts Sample is an advanced example in that it illustrates the more powerful features of domain object access control lists (ACLs) in addition to basic application security.
The application provides an interface with which the users are able to administer a simple database of contacts (the domain objects).

To deploy, simply copy the WAR file from Spring Security distribution into your container's `webapps` directory.
The war should be called `spring-security-samples-contacts-3.1.x.war` (the appended version number will vary depending on what release you are using).

After starting your container, check the application can load.
Visit http://localhost:8080/contacts (or whichever URL is appropriate for your web container and the WAR you deployed).

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:
----

Security Debug Information

Authentication object is of type:
org.springframework.security.authentication.UsernamePasswordAuthenticationToken

Authentication object as a String:

org.springframework.security.authentication.UsernamePasswordAuthenticationToken@1f127853:
Principal: org.springframework.security.core.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.web.authentication.WebAuthenticationDetails@0: \
RemoteIpAddress: 127.0.0.1; SessionId: 8fkp8t83ohar; \
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!

----


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 `ROLE_SUPERVISOR` are granted access to delete their contacts.
Behind the scenes, the `MethodSecurityInterceptor` is securing the business objects.

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.


[[ldap-sample]]
=== LDAP Sample
The LDAP sample application provides a basic configuration and sets up both a namespace configuration and an equivalent configuration using traditional beans, both in the same application context file.
This means there are actually two identical authentication providers configured in this application.


[[openid-sample]]
=== OpenID Sample
The OpenID sample demonstrates how to use the namespace to configure OpenID and how to set up http://openid.net/specs/openid-attribute-exchange-1_0.html[attribute exchange] configurations for Google, Yahoo and MyOpenID identity providers (you can experiment with adding others if you wish).
It uses the JQuery-based http://code.google.com/p/openid-selector/[openid-selector] project to provide a user-friendly login page which allows the user to easily select a provider, rather than typing in the full OpenID identifier.

The application differs from normal authentication scenarios in that it allows any user to access the site (provided their OpenID authentication is successful).
The first time you login, you will get a "Welcome [your name]"" message.
If you logout and log back in (with the same OpenID identity) then this should change to "Welcome Back".
This is achieved by using a custom `UserDetailsService` which assigns a standard role to any user and stores the identities internally in a map.
Obviously a real application would use a database instead.
Have a look at the source form more information.
This class also takes into account the fact that different attributes may be returned from different providers and builds the name with which it addresses the user accordingly.


[[cas-sample]]
=== CAS Sample
The CAS sample requires that you run both a CAS server and CAS client.
It isn't included in the distribution so you should check out the project code as described in <<get-source,the introduction>>.
You'll find the relevant files under the `sample/cas` directory.
There's also a `Readme.txt` file in there which explains how to run both the server and the client directly from the source tree, complete with SSL support.


[[jaas-sample]]
=== JAAS Sample
The JAAS sample is very simple example of how to use a JAAS LoginModule with Spring Security.
The provided LoginModule will successfully authenticate a user if the username equals the password otherwise a LoginException is thrown.
The AuthorityGranter used in this example always grants the role ROLE_USER.
The sample application also demonstrates how to run as the JAAS Subject returned by the LoginModule by setting <<nsa-http-jaas-api-provision,jaas-api-provision>> equal to "true".


[[preauth-sample]]
=== Pre-Authentication Sample
This sample application demonstrates how to wire up beans from the <<preauth,pre-authentication>> framework to make use of login information from a Java EE container.
The user name and roles are those setup by the container.

The code is in `samples/preauth`.

