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.

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

Add new security architecture diagram and process description to Security Architecture content #32611

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Diagram looks great. Just a small question, does each of the red broken arrow lines mean "Access denied"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. Red is for a negative outcome. The contrast ratio between the blue and red meets accessibility guidelines and it has text on the main arrow to clarify. It would be too much to put access denied on all of the red arrows. Let me know if you think otherwise. Thanks 👍

Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
30 changes: 27 additions & 3 deletions docs/src/main/asciidoc/security-architecture-concept.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,28 @@ include::_attributes.adoc[]

The Quarkus Security architecture provides several built-in authentication mechanisms. The `HttpAuthenticationMechanism` interface is the main entry mechanism for securing HTTP applications in Quarkus. Quarkus Security is also highly customizable.

== Core components of Quarkus Security
== Overview of the Quarkus Security architecture

When a client sends an HTTP request, Quarkus Security orchestrates security authentication and authorization by interacting with several built-in core components including `HttpAuthenticationMechanism`, `IdentityProvider`, and `SecurityIdentityAugmentor`.

The sequential security validation process results in one of three outcomes:

* The HTTP request is authenticated and authorized and access to the Quarkus application is granted
* The HTTP request authentication fails and the requester receives a challenge
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I couldn't find explanation of challenge in this guide or in any other. IMO sentence requester receives a challenge is only going to confuse incomers. security-customization.adoc is dealing challenge, maybe you can point there for practical example of what you mean?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be nice if docs said WHY requester receives challenge and what it means.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

speaking of what, "Creates authentication challenge" goes back to the client, maybe you can add note under the image with example (e.g. for oidc with code flow redirect URL)

* The HTTP request authorization fails and and the requester's access to the Quarkus applicaton is denied
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

re Line 21
Typo: Extra "and" in sentence "....authorization fails and and the....."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops... Thanks for catching! 🙈


The following diagram steps through the detailed process flow of the Quarkus Security architecture:

.The Quarkus Security architecture and process flow
image::security-architecture-overview.png[alt=Quarkus Security architecture process flow, width="60%", align=center]

== Core components of the Quarkus Security architecture

=== `HttpAuthenticationMechanism`
Quarkus Security uses `HttpAuthenticationMechanism` to extract the authentication credentials from the HTTP request and delegates them to `IdentityProvider` to convert the credentials to `SecurityIdentity`.
For example, the credentials can come from the `Authorization` header, client HTTPS certificates, or cookies.

=== `IdentityProvider`
`IdentityProvider` verifies the authentication credentials and maps them to `SecurityIdentity`, which has the username, roles, original authentication credentials, and other attributes.

You can inject a `SecurityIdentity` instance for every authenticated resource to get the authenticated identity information.
Expand All @@ -23,19 +40,26 @@ In other contexts, it is possible to have other parallel representations of the

For more information, see xref:security-identity-providers-concept.adoc[Identity providers].

=== `SecurityIdentityAugmentor`
Because Quarkus Security is customizable, for example, you can add authorization roles to `SecurityIdentity`, you can register and prioritize one or more custom security augmentors.

Registered instances of `SecurityIdentityAugmentor` are invoked during the final stage of the security authentication process.
For more information see the xref:security-customization.adoc#security-identity-customization[Security Identity Customization] section of the "Security Tips and Tricks" guide.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re line 47:
Small typo: missing comma after "For more information....."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch.

Thanks for reviewing Sheila. As this is merged, I'll submit a fix asap!



== Supported authentication mechanisms

To learn more about security authentication in Quarkus and the supported mechanisms and protocols, see xref:security-authentication-mechanisms-concept.adoc[Authentication mechanisms in Quarkus].

== Proactive authentication

Proactive authentication is enabled in Quarkus by default.
Proactive authentication is enabled in Quarkus by default.
The request is always authenticated if an incoming request has a credential, even if the target page does not require authentication
For more information, see xref:security-proactive-authentication-concept.adoc[Proactive authentication].

== Quarkus Security customization

Quarkus Security is also highly customizable.
Quarkus Security is also highly customizable.
You can customize the following core security components of Quarkus:

* `HttpAuthenticationMechanism`
Expand Down