Skip to content

Commit

Permalink
Add keystore and truststore default format change
Browse files Browse the repository at this point in the history
  • Loading branch information
@rolfedh
rolfedh committed Aug 19, 2024
1 parent 66429bd commit fa17c3c
Showing 1 changed file with 32 additions and 15 deletions.
47 changes: 32 additions & 15 deletions docs/src/main/asciidoc/security-authentication-mechanisms.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Check warning on line 230 in docs/src/main/asciidoc/security-authentication-mechanisms.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 230, "column": 331}}}, "severity": "INFO"}

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
Expand All @@ -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]
Expand Down Expand Up @@ -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`.

Check warning on line 322 in docs/src/main/asciidoc/security-authentication-mechanisms.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'and so on' rather than 'etc' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'and so on' rather than 'etc' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 322, "column": 154}}}, "severity": "WARNING"}
<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`.

Check warning on line 325 in docs/src/main/asciidoc/security-authentication-mechanisms.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'preceeding'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'preceeding'?", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 325, "column": 11}}}, "severity": "WARNING"}
Expand Down Expand Up @@ -675,7 +692,7 @@ NOTE: For consistency with various Jakarta EE specifications, it is recommended
==== How to combine it with HTTP Security Policy

Check warning on line 692 in docs/src/main/asciidoc/security-authentication-mechanisms.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'How to combine it with HTTP Security Policy'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'How to combine it with HTTP Security Policy'.", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 692, "column": 6}}}, "severity": "INFO"}

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]
----
Expand Down

0 comments on commit fa17c3c

Please sign in to comment.