Recompose security overview and built-in auth content to diataxis tem…

…plates 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 More link fixes Fix mTLS case Update docs/src/main/asciidoc/security-architecture-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Update docs/src/main/asciidoc/security-architecture-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Update docs/src/main/asciidoc/security-identity-providers-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Update docs/src/main/asciidoc/security-architecture-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Update docs/src/main/asciidoc/security-identity-providers-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Update docs/src/main/asciidoc/security-proactive-authentication-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Update docs/src/main/asciidoc/security-proactive-authentication-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Update docs/src/main/asciidoc/security-proactive-authentication-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Update docs/src/main/asciidoc/security-proactive-authentication-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Update docs/src/main/asciidoc/security-proactive-authentication-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Some style enhancements Update docs/src/main/asciidoc/security-proactive-authentication-concept.adoc Co-authored-by: Mickey Maler <mmaler@redhat.com> Style enhancement: reduce wordiness tweak Fixed further comments asciidocfix and added link Fixed some typos Fixed build error 2023-01-24T11:15:40.1095928Z [ERROR] asciidoctor: WARN: security-proactive-authentication-concept.adoc: line 86: section title out of sequence: expected level 1, got level 2
quarkusio · Jan 24, 2023 · bbc05e0 · bbc05e0
1 parent 3c1d04c
commit bbc05e0
Show file tree

Hide file tree

Showing 18 changed files with 630 additions and 572 deletions.
diff --git a/docs/src/main/asciidoc/security-architecture-concept.adoc b/docs/src/main/asciidoc/security-architecture-concept.adoc
@@ -0,0 +1,46 @@
+////
+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.
+
+You can inject a `SecurityIdentity` instance for every authenticated resource 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. 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. 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].
+
+== References
+
+* xref:security-authorize-web-endpoints-reference.adoc[Authorization of web endpoints]
diff --git a/docs/src/main/asciidoc/security-authentication-mechanisms-concept.adoc b/docs/src/main/asciidoc/security-authentication-mechanisms-concept.adoc
diff --git a/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc b/docs/src/main/asciidoc/security-authorize-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, review the information in 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.

diff --git a/docs/src/main/asciidoc/security-basic-authentication-concept.adoc b/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
 

diff --git a/docs/src/main/asciidoc/security-basic-authentication-howto.adoc b/docs/src/main/asciidoc/security-basic-authentication-howto.adoc
@@ -4,9 +4,9 @@ include::_attributes.adoc[]
 :categories: security
 
 Enable Basic authentication for your Quarkus project and allow users to authenticate with a username and password.
- 
+
 == Prerequisites
- 
+
 * You have installed at least one extension that provides an `IdentityProvider` based on username and password, such as xref:security-jdbc.adoc[Elytron JDBC].
 
 == Procedure
@@ -17,7 +17,7 @@ Enable Basic authentication for your Quarkus project and allow users to authenti
 ----
 quarkus.http.auth.basic=true
 ----
- 
+
 An easy way to configure the required user credentials for Basic authentication to work is to configure the user name, secret, and roles directly in the `application.properties` file.
 
 .Example of Basic authentication properties
@@ -42,9 +42,9 @@ Configuring user names, secrets, and roles in the `application.properties` file
 ====
 
 To walk through how to configure Basic authentication together with JPA for storing user credentials in a database, see the xref:security-basic-authentication-tutorial.adoc[Secure a Quarkus application with Basic authentication] tutorial.
- 
-== Additional resources
+
+== References
 
 * xref:security-overview-concept.adoc[Quarkus Security overview]
-* xref:security-overview-concept.adoc#identity-providers[Security Identity Providers]
+* xref:security-identity-providers.adoc[Identity Providers]
 * xref:security-testing.adoc#configuring-user-information[Configuring User Information in application.properties]
diff --git a/docs/src/main/asciidoc/security-basic-authentication-tutorial.adoc b/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:

diff --git a/docs/src/main/asciidoc/security-built-in-authentication-support-concept.adoc b/docs/src/main/asciidoc/security-built-in-authentication-support-concept.adoc