diff --git a/doc/docbook/acegi.xml b/doc/docbook/acegi.xml index b1550f069f..e9e15b2711 100644 --- a/doc/docbook/acegi.xml +++ b/doc/docbook/acegi.xml @@ -26,7 +26,7 @@ Reference Documentation - 0.8.0 + 0.8.1 @@ -2679,7 +2679,7 @@ key: A private key to prevent modification of the nonce token login to take place. Acegi Security provides the necessary hooks so that such operations can take place, along with providing a concrete implementation that uses hashing to preserve the security of - cookie-based tokens. + cookie-based tokens. Remember-me authentication is not used with digest or basic authentication, given they are often not used with @@ -3812,106 +3812,158 @@ $CATALINA_HOME/bin/startup.sh - X.509 Authentication - - Overview - 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 (i.e. digitally - signed) by one of a list of trusted certificate authorities which - it maintains. - - You can also use SSL with mutual authentication; - 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. - The Acegi X.509 module extracts the certificate using a filter and passes it to the - configured X.509 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 Acegi infrastructure. - - You should be familiar with using certificates and setting up client authentication for your - servlet container before attempting to use it with Acegi. 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 . - It's important that you get this working before trying it out with Acegi. - - - - X.509 with Acegi Security - With X.509 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 entry point 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 - - The X509ProcessingFilter extracts the certificate - from the request and uses it as the credentials for an authentication request. The - request is an X509AuthenticationToken. The request is passed to - the authentication manager. - The X509AuthenticationProvider receives - the token. It's main concern is to obtain the user information (in particular the user's - granted authorities) which match the certificate. It delegates this responsibility - to an X509AuthoritiesPopulator.. - The populator's single method, - getUserDetails(X509Certificate userCertificate) is invoked. - Implementations should return a UserDetails instance containing - the set of GrantedAuthority objects for the user. This method can - also choose to reject the certificate (for example if it doesn't contain a matching user name). - It should then throw a BadCredentialsException. A dao-based - implementation DaoX509AuthoritiesPopulator is provided which extracts - the user's name from the subject common name in the certificate. It also allows - you to set your own regular expression to match a different part of the subject distinguished - name. It uses an AuthenticationDao to load the user information. - - - If everything has gone smoothly then there should be a valid - Authentication object in the secure context and the invocation will procede - as normal. If no certificate was found, or the certificate was rejected, then the - SecurityEnforcementFilter will invoke the - X509ProcessingFilterEntryPoint which returns a 403 error to the - user. - - - - - Configuring the X.509 Provider - There is a version of the contacts sample application which uses X.509. - 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 + X509 Authentication - - marissa.p12 A PKCS12 format file containing the client key and certificate. These should - be installed in your browser. It maps to the user marissa in the application. - server.p12 The server certificate and key for HTTPS connections. - ca.jks A Java keystore containing the certificate for the authority which issued marissa's - certificate. This will be used by the container to validate client certificates. - - - For JBoss 3.2.7 (with Tomcat 5.0), the SSL configuration in the server.xml file looks like this - - <!-- SSL/TLS Connector configuration --> - <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" - /> - - clientAuth can also be set to want 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 Acegi-secured - objects. - - - + + Overview + + 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. + + You can also use SSL with mutual authentication; + 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. The Acegi 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 Acegi Security + infrastructure. + + You should be familiar with using certificates and setting up + client authentication for your servlet container before attempting to + use it with Acegi 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 . + It's important that you get this working before trying it out with + Acegi Security. + + + + X509 with Acegi Security + + 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 entry point + 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 + + + + The X509ProcessingFilter extracts + the certificate from the request and uses it as the credentials + for an authentication request. The generated authentication + request is an X509AuthenticationToken. + The request is passed to the authentication manager. + + + + + + The X509AuthenticationProvider + 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 + X509AuthoritiesPopulator. + + + . + + + The populator's single method, + getUserDetails(X509Certificate + userCertificate) is invoked. Implementations should + return a UserDetails instance containing + the array of GrantedAuthority 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 + BadCredentialsException. A + DAO-based implementation, + DaoX509AuthoritiesPopulator, is provided + which extracts the user's name from the subject common + name (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. An + AuthenticationDao is used to load the + user information. + + + + + + If everything has gone smoothly then there should be a + valid Authentication object in the secure + context and the invocation will procede as normal. If no + certificate was found, or the certificate was rejected, then the + SecurityEnforcementFilter will invoke the + X509ProcessingFilterEntryPoint which + returns a 403 error (forbidden) to the user. + + + + + + + + Configuring the X509 Provider + + There is a version of the contacts sample application 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 + + marissa.p12: A PKCS12 format file + containing the client key and certificate. These should be + installed in your browser. It maps to the user + marissa in the application. + + + + server.p12: The server certificate + and key for HTTPS connections. + + + + ca.jks: A Java keystore containing + the certificate for the authority which issued marissa's + certificate. This will be used by the container to validate + client certificates. + + For JBoss 3.2.7 (with Tomcat 5.0), the SSL + configuration in the server.xml file looks like + this <!-- SSL/TLS Connector configuration --> +<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" +/>clientAuth can also be set to + want 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 Acegi + Security (unless you use a non-X509 authentication mechanism, such as + BASIC authentication, to authenticate the user). + - + Channel Security