From 0c565d475e1b998a1154c5407c363ffa5d24693f Mon Sep 17 00:00:00 2001 From: Rolfe Dlugy-Hegwer Date: Thu, 15 Aug 2024 10:16:55 -0400 Subject: [PATCH] Add keystore and truststore default format change --- .../security-authentication-mechanisms.adoc | 47 +++++++++++++------ 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/docs/src/main/asciidoc/security-authentication-mechanisms.adoc b/docs/src/main/asciidoc/security-authentication-mechanisms.adoc index 704e7d3d3359d..4ff538208f223 100644 --- a/docs/src/main/asciidoc/security-authentication-mechanisms.adoc +++ b/docs/src/main/asciidoc/security-authentication-mechanisms.adoc @@ -227,29 +227,45 @@ Quarkus provides mutual TLS (mTLS) authentication so that you can authenticate u To use this authentication method, you must first enable SSL/TLS for your application. For more information, see the xref:http-reference.adoc#ssl[Supporting secure connections with SSL/TLS] section of the Quarkus "HTTP reference" guide. -After your application accepts secure connections, the next step is to configure the `quarkus.http.ssl.certificate.trust-store-file` property with the name of that file that holds all the certificates your application trusts. The specified file also includes information about how your application asks for certificates when a client, such as a browser or other service, tries to access one of its protected resources. +After your application accepts secure connections, the next step is to configure the `quarkus.http.ssl.certificate.trust-store-file` property with the name of the file that holds all the certificates your application trusts. This file also includes information about how your application requests certificates when a client, such as a browser or another service, tries to access one of its protected resources. + +Because JKS is no longer the default keystore and truststore format in Quarkus, the framework makes an educated guess based on the file extension: + +* `.pem`, `.crt`, and `.key` are read as PEM certificates and keys. +* `.jks`, `.keystore`, and `.truststore` are read as JKS keystores and truststores. +* `.p12`, `.pkcs12`, and `.pfx` are read as PKCS12 keystores and truststores. + +If your file does not use one of these extensions, you must set the format by using the following properties: [source,properties] ---- -quarkus.http.ssl.certificate.key-store-file=server-keystore.jks <1> +quarkus.http.ssl.certificate.key-store-file-type=JKS # or P12 or PEM +quarkus.http.ssl.certificate.trust-store-file-type=JKS # or P12 or PEM +---- + +JKS is becoming less commonly used. Since Java 9, the default keystore format in Java is PKCS12. The most significant difference between JKS and PKCS12 is that JKS is a format specific to Java. In contrast, PKCS12 is a standardized, language-neutral way of storing encrypted private keys and certificates. + +Here is an example configuration for enabling mTLS: + +[source,properties] +---- +quarkus.http.ssl.certificate.key-store-file=server-keystore.jks <1> quarkus.http.ssl.certificate.key-store-password=the_key_store_secret -quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks <2> +quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks <2> quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret -quarkus.http.ssl.client-auth=required <3> -quarkus.http.auth.permission.default.paths=/* <4> +quarkus.http.ssl.client-auth=required <3> +quarkus.http.auth.permission.default.paths=/* <4> quarkus.http.auth.permission.default.policy=authenticated -quarkus.http.insecure-requests=disabled <5> +quarkus.http.insecure-requests=disabled <5> ---- + <1> The keystore where the server's private key is located. <2> The truststore from which the trusted certificates are loaded. -<3> With the value set to `required`, the server demands client certificates. -Set the value to `REQUEST` to allow the server to accept requests without a certificate. -This setting is beneficial when supporting authentication methods besides mTLS. -<4> Defines a policy where only authenticated users should have access to resources from your application. -<5> You can explicitly disable the plain HTTP protocol, thus requiring all requests to use HTTPS. -When you set `quarkus.http.ssl.client-auth` to `required`, the system automatically sets `quarkus.http.insecure-requests` to `disabled`. +<3> Setting `quarkus.http.ssl.client-auth` to `required` makes the server demand client certificates. You can set it to `REQUEST` if the server should accept requests without a certificate. This setting is useful when supporting multiple authentication methods besides mTLS. +<4> Defines a policy where only authenticated users can access resources from your application. +<5> Disables the plain HTTP protocol, requiring all requests to use HTTPS. When you set `quarkus.http.ssl.client-auth` to `required`, `quarkus.http.insecure-requests` is automatically disabled. -When the incoming request matches a valid certificate in the truststore, your application can obtain the subject by injecting a `SecurityIdentity` as follows: +When an incoming request matches a valid certificate in the truststore, your application can obtain the subject by injecting a `SecurityIdentity` as follows: [[x509-subject-example]] .Obtaining the subject @@ -266,6 +282,7 @@ public String hello() { ---- You can also get the certificate by using the code outlined in the following example: + [[x509-credential-example]] .Obtaining the certificate [source,java] @@ -302,7 +319,7 @@ quarkus.http.auth.permission.certauthenticated.paths=/* <2> quarkus.http.auth.permission.certauthenticated.policy=role-policy-cert <2> quarkus.http.auth.policy.role-policy-cert.roles-allowed=user,admin <2> ---- -<1> The `cert-role-mappings.properties` classpath resource contains a map of certificate's CN values to roles in the form `CN=role` or `CN=role1,role2`, etc. Let's assume it contains three entries: `alice=user,admin`, `bob=user` and `jdoe=tester`. +<1> The `cert-role-mappings.properties` classpath resource contains a map of certificate's CN values to roles in the form `CN=role` or `CN=role1,role2`, etc. Let us assume it contains three entries: `alice=user,admin`, `bob=user` and `jdoe=tester`. <2> Use HTTP security policy to require that `SecurityIdentity` must have either `user` or `admin` roles for the requests to be authorized. Given the preceeding configuration, the request is authorized if the client certificate's CN attribute is equal to `alice` or `bob` and forbidden if it is equal to `jdoe`. @@ -675,7 +692,7 @@ NOTE: For consistency with various Jakarta EE specifications, it is recommended ==== How to combine it with HTTP Security Policy The easiest way to define roles that are allowed to access individual resources is the `@RolesAllowed` annotation. -Nevertheless, it's also possible to use the HTTP Security Policy like in the example below: +Nevertheless, it is also possible to use the HTTP Security Policy like in the example below: [source,properties] ----