Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add keystore and truststore default format change #42572

Merged
merged 1 commit into from
Aug 19, 2024
Merged

Add keystore and truststore default format change #42572

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 32 additions & 15 deletions docs/src/main/asciidoc/security-authentication-mechanisms.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,29 +227,45 @@
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"}

sberyozkin marked this conversation as resolved.
Show resolved Hide resolved
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 @@
----

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,10 +319,10 @@
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"}

==== Using certificate attributes to augment SecurityIdentity

Expand Down Expand Up @@ -672,10 +689,10 @@

NOTE: For consistency with various Jakarta EE specifications, it is recommended to always repeat annotations instead of relying on annotation inheritance.

==== 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