Merge pull request #32611 from michelle-purcell/security-architecture…

…-docs

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

docs/src/main/asciidoc/security-architecture-concept.adoc

@@ -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
+* The HTTP request authorization fails and and the requester's access to the Quarkus applicaton is denied
+
+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.
@@ -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.
+
+
 == 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`