From e437198e9dce9cd281fdddfeca12e814148252a2 Mon Sep 17 00:00:00 2001
From: Pedro Igor <pigor.craveiro@gmail.com>
Date: Mon, 22 Jun 2020 17:42:16 -0300
Subject: [PATCH] [fixes #8508] - mTLS documentation

---
 docs/src/main/asciidoc/security.adoc | 58 ++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/docs/src/main/asciidoc/security.adoc b/docs/src/main/asciidoc/security.adoc
index e7a144339d278..0e7975910a642 100644
--- a/docs/src/main/asciidoc/security.adoc
+++ b/docs/src/main/asciidoc/security.adoc
@@ -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