diff --git a/doc/docbook/acegi.xml b/doc/docbook/acegi.xml index 33e94b4bbe..23129cfc0b 100644 --- a/doc/docbook/acegi.xml +++ b/doc/docbook/acegi.xml @@ -982,7 +982,7 @@ public aspect DomainObjectInstanceSecurityAspect implements InitializingBean { for commencing a form-based authentication, BasicProcessingFilterEntryPoint for commencing a HTTP Basic authentication process, and - CasProcessingFilterEntryPoint for commencing a Yale + CasProcessingFilterEntryPoint for commencing a JA-SIG Central Authentication Service (CAS) login. The AuthenticationProcessingFilterEntryPoint and CasProcessingFilterEntryPoint have optional @@ -1147,7 +1147,7 @@ public aspect DomainObjectInstanceSecurityAspect implements InitializingBean { CasAuthenticationToken is used to - represent a successful Yale Central Authentication Service (CAS) + represent a successful JA-SIG Central Authentication Service (CAS) authentication. This is discussed further in the CAS section. @@ -1311,7 +1311,7 @@ public aspect DomainObjectInstanceSecurityAspect implements InitializingBean { CasAuthenticationProvider is able to - authenticate Yale Central Authentication Service (CAS) tickets. + authenticate JA-SIG Central Authentication Service (CAS) tickets. This is discussed further in the CAS Single Sign On section. @@ -2616,7 +2616,7 @@ public boolean supports(Class clazz); Another approach (commonly use with web services) is HTTP Basic Authentication, which allows clients to use HTTP headers to present authentication information to the Acegi Security System for Spring. - Alternatively, you can also use Yale Central Authentication Service + Alternatively, you can also use JA-SIG Central Authentication Service (CAS) for enterprise-wide single sign on. The final (and generally unrecommended) approach is via Container Adapters, which allow supported web containers to perform the authentication themselves. @@ -3560,13 +3560,13 @@ $CATALINA_HOME/bin/startup.sh - Yale Central Authentication Service (CAS) Single Sign On + JA-SIG Central Authentication Service (CAS) Single Sign On Overview - Yale University produces an enterprise-wide single sign on - system known as CAS. Unlike other initiatives, Yale's Central + JA-SIG produces an enterprise-wide single sign on + system known as CAS. Unlike other initiatives, JA-SIG's Central Authentication Service is open source, widely used, simple to understand, platform independent, and supports proxy capabilities. The Acegi Security System for Spring fully supports CAS, and provides an @@ -3575,7 +3575,7 @@ $CATALINA_HOME/bin/startup.sh enterprise-wide CAS server. You can learn more about CAS at - http://www.yale.edu/tp/auth/. You will need to + http://www.ja-sig.org/products/cas/. You will need to visit this URL to download the CAS Server files. Whilst the Acegi Security System for Spring includes two CAS libraries in the "-with-dependencies" ZIP file, you will still need the CAS Java Server @@ -3589,22 +3589,25 @@ $CATALINA_HOME/bin/startup.sh Whilst the CAS web site above contains two documents that detail the architecture of CAS, we present the general overview again here within the context of the Acegi Security System for Spring. The - following refers to CAS 2.0, being the version of CAS that Acegi - Security System for Spring supports. + following refers to both CAS 2.0 (produced by Yale) and CAS 3.0 + (produced by JA-SIG), being the versions of CAS that Acegi Security + System for Spring supports. Somewhere in your enterprise you will need to setup a CAS server. The CAS server is simply a standard WAR file, so there isn't anything difficult about setting up your server. Inside the WAR file you will customise the login and other single sign on pages displayed - to users. You will also need to specify in the web.xml a - PasswordHandler. The + to users. + + If you are deploying CAS 2.0, you will also need to specify in + the web.xml a PasswordHandler. The PasswordHandler has a simple method that returns a boolean as to whether a given username and password is valid. Your PasswordHandler implementation will need to link into some type of backend authentication repository, such as an LDAP server or database. - If you are already running an existing CAS server instance, you + If you are already running an existing CAS 2.0 server instance, you will have already established a PasswordHandler. If you do not already have a PasswordHandler, you might prefer to use the Acegi Security System for Spring @@ -3617,6 +3620,32 @@ $CATALINA_HOME/bin/startup.sh will function as a CAS client successfully irrespective of the PasswordHandler you've chosen for your CAS server. + + If you are deploying CAS 3.0, you will also need to specify an + AuthenticationHandler in the + deployerConfigContext.xml included with CAS. The + AuthenticationHandler has a simple method that + returns a boolean as to whether a given set of Credentials is valid. + Your AuthenticationHandler implementation will need + to link into some type of backend authentication repository, such as an + LDAP server or database. CAS itself includes numerous + AuthenticationHandlers out of the box to assist with + this. + + If you are already running an existing CAS 3.0 server instance, + you will have already established an + AuthenticationHandler. If you do not already have an + AuthenticationHandler, you might prefer to use the + Acegi Security System for Spring + CasAuthenticationHandler class. This class delegates + through to the standard Acegi Security + AuthenticationManager, enabling you to use a security + configuration you might already have in place. You do not need to use + the CasAuthenticationHandler class on your CAS server + if you do not wish. The Acegi Security System for Spring will function + as a CAS client successfully irrespective of the + AuthenticationHandler you've chosen for your CAS + server. Apart from the CAS server itself, the other key player is of course the secure web applications deployed throughout your @@ -3626,7 +3655,7 @@ $CATALINA_HOME/bin/startup.sh the user. This will be explained more fully later. Services can be developed in a large variety of languages, due - to CAS 2.0's very light XML-based protocol. The Yale CAS home page + to CAS 2.0's very light XML-based protocol. The JA-SIG CAS home page contains a clients archive which demonstrates CAS clients in Java, Active Server Pages, Perl, Python and others. Naturally, Java support is very strong given the CAS server is written in Java. You do not @@ -3675,8 +3704,10 @@ $CATALINA_HOME/bin/startup.sh session cookie which indicates they've previously logged on, they will not be prompted to login again (there is an exception to this procedure, which we'll cover later). CAS will use the - PasswordHandler discussed above to decide - whether the username and password is valid. + PasswordHandler (or + AuthenticationHandler if using CAS 3.0) + discussed above to decide whether the username and password is + valid. @@ -3833,12 +3864,12 @@ $CATALINA_HOME/bin/startup.sh configured. - - CAS Server Installation (Optional) + + CAS 2.0 Server Installation (Optional) As mentioned above, the Acegi Security System for Spring includes a PasswordHandler that bridges your - existing AuthenticationManager into CAS. You do not + existing AuthenticationManager into CAS 2.0. You do not need to use this PasswordHandler to use Acegi Security on the client side (any CAS PasswordHandler will do). @@ -3924,6 +3955,94 @@ $CATALINA_HOME/bin/startup.sh additional help or a test certificate you might like to check the samples/contacts/etc/ssl directory. + + + CAS 3.0 Server Installation (Optional) + As mentioned above, the Acegi Security System for Spring + includes an AuthenticationHandler that bridges your + existing AuthenticationManager into CAS 3.0. You do not + need to use this AuthenticationHandler to use Acegi + Security on the client side (any CAS + AuthenticationHandler will do). + + To install, you will need to download and extract the CAS server + archive. We used version 3.0.4. There will be a + /webapp directory in the root of the deployment. Edit the + an deployerConfigContext.xml so that it contains your + AuthenticationManager as well as the + CasAuthenticationHandler. A sample + applicationContext.xml is included below: + + + + + + + + + + + + + + + + + + + + + + + + + + + marissa=koala,ROLES_IGNORED_BY_CAS + dianne=emu,ROLES_IGNORED_BY_CAS + scott=wombat,ROLES_IGNORED_BY_CAS + peter=opal,disabled,ROLES_IGNORED_BY_CAS + + + + + + + + + + + + + + + + + ]]> + + Note the granted authorities are ignored by CAS because it has + no way of communicating the granted authorities to calling + applications. CAS is only concerned with username and passwords (and + the enabled/disabled status). + + Copy the acegi-security.jar file into + /localPlugins/lib. Now use the ant + war task in the build.xml in the /localPlugins + directory. This will create + /localPlugins/target/cas.war, which is ready for deployment to your + servlet container. + + Note CAS heavily relies on HTTPS. You can't even test the system + without a HTTPS certificate. Whilst you should refer to your web + container's documentation on setting up HTTPS, if you need some + additional help or a test certificate you might like to check the + CAS documentation on setting up SSL: + http://www.ja-sig.org/products/cas/server/ssl/index.html + + CAS Acegi Security System Client Installation @@ -5439,7 +5558,7 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); acegi-security-sample-contacts-ca.war is configured to use a Container Adapter. Finally, acegi-security-sample-contacts-cas.war is designed to - work with a Yale CAS server. If you're just wanting to see how the + work with a JA-SIG CAS server. If you're just wanting to see how the sample application works, please use acegi-security-sample-contacts-filter.war as it does not require special configuration of your container. This is