Skip to content

Commit

Permalink
Merge pull request quarkusio#10172 from pedroigor/issue-8508-doc
Browse files Browse the repository at this point in the history
[fixes quarkusio#8508] - mTLS documentation
  • Loading branch information
geoand authored Jun 23, 2020
2 parents 00af4be + e437198 commit 114013f
Showing 1 changed file with 58 additions and 0 deletions.
58 changes: 58 additions & 0 deletions docs/src/main/asciidoc/security.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,64 @@ The following properties can be used to configure form based auth:

include::{generated-dir}/config/quarkus-vertx-http-config-group-form-auth-config.adoc[opts=optional, leveloffset=+1]

=== Mutual TLS Authentication

Quarkus provides mTLS authentication so that you can authenticate users based on their X.509 certificates.

To use this authentication method, you should first enable SSL to your application. For more details, check the link:http-reference[Supporting secure connections with SSL] guide.

Once your application is accepting secure connections, the next step is to configure a `quarkus.http.ssl.certificate.trust-store-file`
holding all the certificates that your application should trust as well as how your application should ask for certificates when
a client (e.g.: browser or another service) tries to access one of its protected resources.

[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-password=the_trust_store_secret
quarkus.http.ssl.client-auth=required <3>
quarkus.http.auth.permission.default.paths=/* <4>
quarkus.http.auth.permission.default.policy=authenticated
----
<1> Configures a key store where the server's private key is located.

<2> Configures a trust store from where the trusted certificates are going to be loaded from.

<3> Defines that the server should *always* ask certificates from clients. You can relax this behavior by using `REQUEST` so
that the server should still accept requests without a certificate. Useful when you are also supporting authentication methods other than
mTLS.

<4> Defines a policy where only authenticated users should have access to resources from your application.

Once the incoming request matches a valid certificate in the truststore, your application should be able to obtain the subject by
just injecting a `SecurityIdentity` as follows:

[#x509-subject-example]
.Obtaining the subject
[source,java]
----
@Inject
SecurityIdentity identity;
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
return String.format("Hello, %s", identity.getPrincipal().getName());
}
----

You should also be able to get the certificate as follows:

[#x509-credential-example]
.Obtaining the certificate
[source,java]
----
CertificateCredential credential = identity.getCredential(CertificateCredential.class);
X509Certificate certificate = credential.getCertificate();
----

=== Proactive Authentication

By default Quarkus does what we call proactive authentication. This means that if an incoming request has a
Expand Down

0 comments on commit 114013f

Please sign in to comment.