mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-10-31 14:48:54 +00:00
63 lines
4.0 KiB
Plaintext
63 lines
4.0 KiB
Plaintext
[[servlet-x509]]
|
|
= X.509 Authentication
|
|
|
|
[[x509-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 automatically checks that the certificate presented by a server has been issued (digitally signed) by one of a list of trusted certificate authorities that it maintains.
|
|
|
|
You can also use SSL with "`mutual authentication`". The server then requests a valid certificate from the client as part of the SSL handshake.
|
|
The server authenticates 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.
|
|
For example, if you use Tomcat, you should read the https://tomcat.apache.org/tomcat-10.1-doc/ssl-howto.html[Tomcat SSL instructions].
|
|
You should get this working before trying it out with Spring Security.
|
|
|
|
The Spring Security X.509 module extracts the certificate by 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.
|
|
|
|
[[servlet-x509-config]]
|
|
== Adding X.509 Authentication to Your Web Application
|
|
|
|
Similar to xref:reactive/authentication/x509.adoc[Reactive X.509 authentication], the servlet x509 authentication filter allows extracting an authentication token from a certificate provided by a client.
|
|
|
|
The following example shows a reactive x509 security configuration:
|
|
|
|
include-code::./DefaultX509Configuration[tag=springSecurity,indent=0]
|
|
|
|
In the preceding configuration, when neither `principalExtractor` nor `authenticationManager` is provided, defaults are used.
|
|
The default principal extractor is `SubjectX500PrincipalExtractor`, which extracts the CN (common name) field from a certificate provided by a client.
|
|
The default authentication manager is `ReactivePreAuthenticatedAuthenticationManager`, which performs user account validation, checking that a user account with a name extracted by `principalExtractor` exists and that it is not locked, disabled, or expired.
|
|
|
|
The following example demonstrates how these defaults can be overridden:
|
|
|
|
include-code::./CustomX509Configuration[tag=springSecurity,indent=0]
|
|
|
|
In the previous example, a username is extracted from the `emailAddress` field of a client certificate instead of CN, and account lookup uses a custom `ReactiveAuthenticationManager` instance.
|
|
|
|
For an example of configuring Netty and `WebClient` or `curl` command-line tool to use mutual TLS and enable X.509 authentication, see https://github.com/spring-projects/spring-security-samples/tree/main/servlet/java-configuration/authentication/x509.
|
|
|
|
|
|
[[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 do not want to generate your own.
|
|
The `server.jks` file contains the server certificate, the private key, and the issuing 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 does not provide a certificate.
|
|
Clients that do not present a certificate cannot access any objects secured by Spring Security unless you use a non-X.509 authentication mechanism, such as form authentication.
|
|
|