Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 1 commit into from
Apr 3, 2024
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
37 changes: 34 additions & 3 deletions docs/src/main/asciidoc/security-authentication-mechanisms.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,10 +269,41 @@
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"}
sberyozkin marked this conversation as resolved.
Show resolved Hide resolved
<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