Merge pull request quarkusio#39807 from sberyozkin/certificate_role_m…

…apping_docs

Explain in the docs how to map the X509 CN attribute to roles

docs/src/main/asciidoc/security-authentication-mechanisms.adoc

@@ -269,10 +269,41 @@ CertificateCredential credential = identity.getCredential(CertificateCredential.
 X509Certificate certificate = credential.getCertificate();
 ----
 
-==== Authorization
+[[map-certificate-attributes-to-roles]]
+==== Mapping certificate attributes to roles
+
+The information from the client certificate can be used to add roles to Quarkus `SecurityIdentity`.
+
+You can add new roles to `SecurityIdentity` after checking a client certificate's common name (CN) attribute.
+The easiest way to add new roles is to use a certificate attribute to role mapping feature.
+
+For example, you can update the properties shown in the section which introduces <<mutual-tls>> as follows:
+
+[source,properties]
+----
+quarkus.http.ssl.certificate.key-store-file=server-keystore.jks
+quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
+quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks
+quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
+quarkus.http.ssl.client-auth=required
+quarkus.http.insecure-requests=disabled
+
+quarkus.http.auth.certificate-role-properties=cert-role-mappings.properties <1>
+
+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`.
+<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`.
+
+==== Using certificate attributes to augment SecurityIdentity
+
+You can always register `SecurityIdentityAugmentor` if the automatic <<map-certificate-attributes-to-roles>> option does not suit.
+Custom `SecurityIdentityAugmentor` can check the values of different client certificate attributes and augment the `SecurityIdentity` accordingly.
 
-The information from the client certificate can be used to enhance Quarkus `SecurityIdentity`.
-For example, you can add new roles after checking a client certificate subject name, and so on.
 For more information about customizing `SecurityIdentity`, see the xref:security-customization.adoc#security-identity-customization[Security identity customization] section in the Quarkus "Security tips and tricks" guide.
 
 [[other-supported-authentication-mechanisms]]