Skip to content

Commit

Permalink
Explain in the docs how to map the X509 CN attribute to roles
Browse files Browse the repository at this point in the history
  • Loading branch information
sberyozkin committed Apr 1, 2024
1 parent eb56608 commit 7fceeeb
Showing 1 changed file with 34 additions and 3 deletions.
37 changes: 34 additions & 3 deletions docs/src/main/asciidoc/security-authentication-mechanisms.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Check warning on line 280 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 ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 280, "column": 64}}}, "severity": "INFO"}

[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`.

Check warning on line 297 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": 297, "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 300 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": 300, "column": 11}}}, "severity": "WARNING"}

==== 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]]
Expand Down

0 comments on commit 7fceeeb

Please sign in to comment.