diff --git a/src/docbkx/x509-auth-provider.xml b/src/docbkx/x509-auth-provider.xml index 1760c99181..f990db033a 100644 --- a/src/docbkx/x509-auth-provider.xml +++ b/src/docbkx/x509-auth-provider.xml @@ -1,134 +1,78 @@ - -X509 Authentication - - - 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. Spring 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 Spring Security - infrastructure. - - You should be familiar with using certificates and setting up - client authentication for your servlet container before attempting to - use it with Spring 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 - Spring Security - - - - Using X509 with Spring 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. A UserDetailsService 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 - ExceptionTranslationFilter will invoke - the X509ProcessingFilterEntryPoint which - returns a 403 error (forbidden) to the user. - - - - - - Configuration - - 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 - - user.p12: A PKCS12 format file - containing the client key and certificate. These should be - installed in your browser. It maps to a use 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 the user'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}" + 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 (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. Spring Security 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 Spring Security infrastructure. + You should be familiar with using certificates and setting up client authentication + for your servlet container before attempting to use it with Spring 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 Spring Security + + + Adding X.509 Authentication to Your Web Application + Enabling X.509 client authentication is very straightforward. Just add the <x509/> element to your http security namespace configuration. + ... + + ... + ]]> + The element has two optional attributes: + + subject-principal-regex. The regular expression used to + extract a username from the certificate's subject name. The default value is + shown above. This is the username which will be passed to the UserDetailsService to load the authorities for the + user. + + + user-service-ref. This is the bean Id of the + UserDetailsService to be used with X.509. + It isn't needed if there is only one defined in your application + context. + + The subject-principal-regex should contain a single + group. For example the default expression "CN=(.*?)," matches the common name field. So + if the subject name in the certificate is "CN=Jimi Hendrix, OU=...", this will give a + user name of "Jimi Hendrix". The matches are case insensitive. So "emailAddress=(.?)," + will match "EMAILADDRESS=jimi@hendrix.org,CN=..." giving a user name "jimi@hendrix.org". + If the client presents a certificate and a valid username is successfully extracted, + then there should be a valid Authentication object in the + security context. If no certificate is found, or no corresponding user could be found + then the security context will remain empty. This means that you can easily use X.509 + authentication with other options such as a form-based login. + + + Configuring Tomcat + There are some pre-generated certificates in the Spring Security + samples/certificate directory which you can use to enable SSL. The file + server.jks contains the server certificate, private key and the + issuing certificate authority. There are also some client certificate files for the users from the + sample applications. You can install these in your browser to enable SSL client authentication. + + + To enable SSL in tomcat server.xml file looks like this + + 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 Spring - Security (unless you use a non-X509 authentication mechanism, such as - BASIC authentication, to authenticate the user) - - \ No newline at end of file + /> ]]> + + 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 Spring Security + (unless you use a non-X509 authentication mechanism, such as BASIC authentication, to + authenticate the user) + +