Recomposing security overview content to diataxis

Recomposing security overview content to diataxis

Addressed Sergey's review comments

Further enhancements

fix typos grammar

Fixed broken links after recomposing to diataxis

Fixed headings

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

@@ -0,0 +1,42 @@
+////
+This document is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+[id="security-architecture-concept"]
+= Quarkus Security architecture
+include::_attributes.adoc[]
+:categories: security
+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
+
+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` verifies the authentication credentials and maps them to `SecurityIdentity`, which has the username, roles, original authentication credentials, and other attributes.
+
+For every authenticated resource, you can inject a `SecurityIdentity` instance to get the authenticated identity information.
+
+In other contexts, it is possible to have other parallel representations of the same information or parts of it, for example, `SecurityContext` for JAX-RS or `JsonWebToken` for JSON Web Tokens (JWT).
+
+For more information, see xref:security-identity-providers-concept.adoc[Identity providers].
+
+== 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. This means that if an incoming request has a credential then that request will always be authenticated, 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. You can customize the following core security components of Quarkus:
+
+* `HttpAuthenticationMechanism`
+* `IdentityProvider`
+* `SecurityidentityAugmentor`
+
+For more information about customizing Quarkus Security including reactive security and how to register a security provider, see xref:security-customization.adoc[Security customization].

docs/src/main/asciidoc/security-authorization-of-web-endpoints-reference.adoc

@@ -301,7 +301,7 @@ public class SubjectExposingResource {
 <4> The call to obtain the user principal returns null if the caller is unauthenticated and non-null if the caller is authenticated.
 <5> The `/subject/denied` endpoint declares the `@DenyAll` annotation, thus disallowing all direct access to it as a REST method, regardless of the user calling it. The method is still invokable internally by other methods in this class.
 
-CAUTION: Please refer to the xref:security-built-in-authentication-support-concept.adoc#proactive-authentication[Proactive Authentication] section of the Built-In Authentication Support guide if you plan to use standard security annotations on the IO thread.
+CAUTION: If you plan to use standard security annotations on the IO thread, see xref:security-proactive-authentication-concept.adoc[Proactive Authentication].
 
 The `@RolesAllowed` annotation value supports <<config-reference#property-expressions,Property Expressions>> including default values and nested Property Expressions.
 Configuration properties used with the annotation are resolved at runtime.

docs/src/main/asciidoc/security-basic-authentication-concept.adoc

@@ -1,5 +1,5 @@
 [id="security-basic-authentication-concept"]
-= Basic Authentication
+= Basic authentication
 include::_attributes.adoc[]
 :categories: security,web
 

docs/src/main/asciidoc/security-basic-authentication-tutorial.adoc

@@ -1,9 +1,9 @@
 [id="security-basic-authentication-tutorial"]
 = Secure a Quarkus application with Basic authentication
 include::_attributes.adoc[]
-:categories: security, getting-started
+:categories: security,getting-started
 
-Secure your Quarkus application endpoints by combining xref:security-built-in-authentication-support-concept.adoc#basic-auth[Quarkus built-in basic HTTP authentication] with the JPA identity provider to enable role-based access control (RBAC).
+Secure your Quarkus application endpoints by combining the built-in Quarkus xref:security-basic-authentication-concept.adoc[Basic authentication] with the JPA identity provider to enable role-based access control (RBAC).
 The JPA `IdentityProvider` creates a `SecurityIdentity` instance, which is used during user authentication to verify and authorize access requests making your Quarkus application secure.
 
 This tutorial prepares you for implementing more advanced security mechanisms in Quarkus, for example, how to use the OpenID Connect (OIDC) authentication mechanism.
@@ -211,14 +211,14 @@ The `security-jpa` extension initializes only if there is a single entity annota
 
 === Configure the application
 
-. Enable xref:security-built-in-authentication-support-concept.adoc#basic-auth[Quarkus built-in basic HTTP authentication] by setting the `quarkus.http.auth.basic` property to `true`:
+. Enable the built-in Quarkus xref:security-basic-authentication-concept.adoc[Basic authentication] by setting the `quarkus.http.auth.basic` property to `true`:
 +
 `quarkus.http.auth.basic`=true`
 +
 [NOTE]
 ====
-When secure access is required and no other authentication mechanisms are enabled, xref:security-built-in-authentication-support-concept.adoc#basic-auth[Quarkus built-in basic HTTP authentication] is the fallback authentication mechanism.
-Therefore, in this tutorial, you do not need to set the property `quarkus.http.auth.basic=true`.
+When secure access is required and no other authentication mechanisms are enabled, the built-in xref:security-basic-authentication-concept.adoc[Basic authentication] of Quarkus is the fallback authentication mechanism.
+Therefore, in this tutorial, you do not need to set the property `quarkus.http.auth.basic` to `true`.
 ====
 +
 . Configure at least one data source so that the `security-jpa` extension can access your database.
@@ -583,7 +583,7 @@ For applications running in production, do not store passwords in plain text.
 == What's next
 
 Congratulations!
-You have learned how to create and test a secure Quarkus application by combining the xref:security-built-in-authentication-support-concept.adoc#basic-auth[Quarkus built-in basic HTTP authentication] with the JPA identity provider.
+You have learned how to create and test a secure Quarkus application by combining the built-in xref:security-basic-authentication-concept.adoc[Basic authentication] in Quarkus with the JPA identity provider.
 
 After you have completed this tutorial, explore some of the more advanced security mechanisms in Quarkus.
 Use the following information to learn how you can securely use `OpenID Connect` to provide secure single sign-on access to your Quarkus endpoints:

docs/src/main/asciidoc/security-customization.adoc

@@ -32,7 +32,7 @@ implementation("io.quarkus:quarkus-security")
 == HttpAuthenticationMechanism Customization
 
 One can customize `HttpAuthenticationMechanism` by registering a CDI implementation bean.
-In the example below the custom authenticator delegates to `JWTAuthMechanism` provided by `quarkus-smallrye-jwt`: 
+In the example below the custom authenticator delegates to `JWTAuthMechanism` provided by `quarkus-smallrye-jwt`:
 
 [source,java]
 ----
@@ -48,7 +48,7 @@ public class CustomAwareJWTAuthMechanism implements HttpAuthenticationMechanism
 
 	@Override
 	public Uni<SecurityIdentity> authenticate(RoutingContext context, IdentityProviderManager identityProviderManager) {
-	    // do some custom action and delegate	
+	    // do some custom action and delegate
             return delegate.authenticate(context, identityProviderManager);
 	}
 
@@ -175,7 +175,7 @@ public class RolesAugmentor implements SecurityIdentityAugmentor {
 }
 ----
 
-Here is another example showing how to use the client certificate available in the current xref:security-built-in-authentication-support-concept.adoc#mutual-tls[Mutual TLS] request to add more roles:
+Here is another example showing how to use the client certificate available in the current xref:security-authentication-mechanisms-concept.adoc#mutual-TLS-authentication[mutual TLS (mTLS) authentication] request to add more roles:
 
 [source,java]
 ----