You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
78 lines
4.4 KiB
78 lines
4.4 KiB
[[servlet-x509]] |
|
= X.509 Authentication |
|
|
|
|
|
[[x509-overview]] |
|
== 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 its 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. |
|
It 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 https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html[https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html]. |
|
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. |
|
|
|
[source,xml] |
|
---- |
|
<http> |
|
... |
|
<x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/>; |
|
</http> |
|
---- |
|
|
|
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. |
|
|
|
[[x509-ssl-config]] |
|
== Setting up SSL in Tomcat |
|
There are some pre-generated certificates in the {gh-samples-url}/servlet/java-configuration/authentication/x509/server[Spring Security Samples repository]. |
|
You can use these to enable SSL for testing if you don't want to generate your own. |
|
The file `server.jks` contains the server certificate, private key and the issuing certificate authority certificate. |
|
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 run tomcat with SSL support, drop the `server.jks` file into the tomcat `conf` directory and add the following connector to the `server.xml` file |
|
|
|
[source,xml] |
|
---- |
|
|
|
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true" |
|
clientAuth="true" sslProtocol="TLS" |
|
keystoreFile="${catalina.home}/conf/server.jks" |
|
keystoreType="JKS" keystorePass="password" |
|
truststoreFile="${catalina.home}/conf/server.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. |
|
Clients which don't present a certificate won't be able to access any objects secured by Spring Security unless you use a non-X.509 authentication mechanism, such as form authentication. |
|
|
|
|