From a7d296b7a7f28f18160ce5c55bcb45dd2cd3796a Mon Sep 17 00:00:00 2001 From: Sergey Beryozkin Date: Sun, 31 Mar 2024 23:20:27 +0100 Subject: [PATCH] Explain in the docs how to map the X509 CN attribute to roles --- .../security-authentication-mechanisms.adoc | 37 +++++++++++++++++-- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/docs/src/main/asciidoc/security-authentication-mechanisms.adoc b/docs/src/main/asciidoc/security-authentication-mechanisms.adoc index 9584b86abb792..caf601b1cec70 100644 --- a/docs/src/main/asciidoc/security-authentication-mechanisms.adoc +++ b/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 <> 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 <> 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]]