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

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-authentication-mechanisms-concept.adoc

@@ -3,52 +3,143 @@ 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-authentication-mechanisms-concept"]
-= Supported authentication mechanisms in Quarkus
+= Authentication mechanisms in Quarkus
 include::_attributes.adoc[]
-:categories: security
+:categories: security,web
 
-The Quarkus Security framework supports multiple authentication mechanisms, which you can use to secure your applications.
+The Quarkus Security framework supports multiple authentication mechanisms, which you can use to secure your applications. 
+Some of the supported authentication mechanisms are built into Quarkus and some require you to add an extension.
+You can also combine authentication mechanisms. 
 
-== Basic and Form HTTP authentication
+Before you choose an authentication mechanism for securing your Quarkus applications, review the information provided.
 
-xref:security-basic-authentication-concept.adoc[Basic HTTP Authentication] and xref:security-built-in-authentication-support-concept.adoc#form-auth[Form HTTP authentication] are the core authentication mechanisms supported in Quarkus.
+== Built-in authentication support
 
-== WebAuthn authentication
+Quarkus Security provides the following built-in authentication mechanisms:
 
-https://webauthn.guide/[WebAuthn] is an authentication mechanism that replaces passwords.
-When you write a service for registering new users, or logging them in, instead of asking for a password, you can use WebAuthn, which replaces the password.
-For more information, see xref:security-webauthn.adoc[Secure a Quarkus application by using the WebAuthn authentication mechanism].
+* xref:security-basic-authentication-concept.adoc[Basic authentication]
+* <<Form-based authentication>>
+* <<mutual TLS authentication>> 
+
+[[form-auth]]
+=== Form-based authentication
+
+Quarkus provides form-based authentication that works in a similar manner to traditional Servlet form-based auth.
+Unlike traditional form authentication, the authenticated user is not stored in an HTTP session, as Quarkus does not provide clustered HTTP session support.
+Instead, the authentication information is stored in an encrypted cookie, which can be read by all members of the cluster (provided they all share the same encryption key).
+
+The encryption key can be set using the `quarkus.http.auth.session.encryption-key` property, and it must be at least 16 characters
+long. This key is hashed using SHA-256 and the resulting digest is used as a key for AES-256 encryption of the cookie
+value. This cookie contains an expiry time as part of the encrypted value, so all nodes in the cluster must have their
+clocks synchronized. At one-minute intervals, a new cookie will be generated with an updated expiry time if the session
+is in use.
+
+Single Page Application (SPA) typically wants to avoid redirects, this can be done by removing default page paths:
 
-== Mutual TLS (mTLS) authentication
+[source,properties]
+----
+# do not redirect, respond with HTTP 200 OK
+quarkus.http.auth.form.landing-page=
+
+# do not redirect, respond with HTTP 401 Unauthorized
+quarkus.http.auth.form.login-page=
+quarkus.http.auth.form.error-page=
+----
+
+The following properties can be used to configure form based auth:
+
+include::{generated-dir}/config/quarkus-vertx-http-config-group-form-auth-config.adoc[opts=optional, leveloffset=+1]
+
+[[mutual-tls]]
+== mutual TLS authentication
 
 Quarkus provides mutual TLS (mTLS) authentication so that you can authenticate users based on their X.509 certificates.
-For more information, see xref:security-built-in-authentication-support-concept.adoc#mutual-tls[mutual TLS authentication].
 
-== OpenID Connect authentication
+To use this authentication method, you should first enable SSL for your application. For more details, check the xref:http-reference.adoc#ssl[Supporting secure connections with SSL] guide.
 
-OpenID Connect (OIDC) i== OpenID Connect client and filters
+Once your application is accepting secure connections, the next step is to configure a `quarkus.http.ssl.certificate.trust-store-file`
+holding all the certificates that your application should trust as well as how your application should ask for certificates when
+a client (e.g.: browser or another service) tries to access one of its protected resources.
 
-The `quarkus-oidc-client` extension provides `OidcClient` for acquiring and refreshing access tokens from OpenID Connect and OAuth2 providers that support the following token grants:
-* `client-credentials`
-* `password`
-* `refresh_token`
+[source,properties]
+----
+quarkus.http.ssl.certificate.key-store-file=server-keystore.jks            <1>
+quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
+quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks        <2>
+quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
+quarkus.http.ssl.client-auth=required                                      <3>
 
-The `quarkus-oidc-client-filter` extension requires the `quarkus-oidc-client` extension and provides JAX-RS `OidcClientRequestFilter`, which sets the access token acquired by `OidcClient` as the `Bearer` scheme value of the HTTP `Authorization` header.
-This filter can be registered with MP RestClient implementations injected into the current Quarkus endpoint, but it is not related to the authentication requirements of this service endpoint.
-For example, it can be a public endpoint, or it can be protected with mTLS.
+quarkus.http.auth.permission.default.paths=/*                              <4>
+quarkus.http.auth.permission.default.policy=authenticated
+----
+<1> Configures a key store where the server's private key is located.
+<2> Configures a trust store from where the trusted certificates are going to be loaded from.
+<3> Defines that the server should *always* ask certificates from clients. You can relax this behavior by using `REQUEST` so
+that the server should still accept requests without a certificate. Useful when you are also supporting authentication methods other than
+mTLS.
+<4> Defines a policy where only authenticated users should have access to resources from your application.
 
-[IMPORTANT]
-====
-In this scenario, you do not need to protect your Quarkus endpoint by using the Quarkus OpenID Connect adapter.
-====
+Once the incoming request matches a valid certificate in the truststore, your application should be able to obtain the subject by
+just injecting a `SecurityIdentity` as follows:
 
-The `quarkus-oidc-token-propagation` extension requires the `quarkus-oidc` extension and provides JAX-RS `TokenCredentialRequestFilter`, which sets the OpenID Connect Bearer or Authorization Code Flow access token as the `Bearer` scheme value of the HTTP `Authorization` header.
-This filter can be registered with MP RestClient implementations injected into the current Quarkus endpoint, which in turn must be protected by using the Quarkus OpenID Connect adapter.
-This filter can be used to propagate the access token to the downstream services.
+[#x509-subject-example]
+.Obtaining the subject
+[source,java]
+----
+@Inject
+SecurityIdentity identity;
+
+@GET
+@Produces(MediaType.TEXT_PLAIN)
+public String hello() {
+    return String.format("Hello, %s", identity.getPrincipal().getName());
+}
+----
+
+You should also be able to get the certificate as follows:
+
+[#x509-credential-example]
+.Obtaining the certificate
+[source,java]
+----
+import java.security.cert.X509Certificate;
+import io.quarkus.security.credential.CertificateCredential;
+
+CertificateCredential credential = identity.getCredential(CertificateCredential.class);
+X509Certificate certificate = credential.getCertificate();
+----
+
+==== Authorization
+
+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 Quarkus `SecurityIdentity`, see xref:security-customization.adoc#security-identity-customization[SecurityIdentity customization] in the "Security customization" topic.
+
+== Other supported authentication mechanisms
+
+Quarkus Security also supports the following authentication mechanisms through extensions:
+
+* <<WebAuthn authentication>>
+* <<OpenID Connect authentication>>
+* <<SmallRye JWT authentication>>
+* <<OAuth2 authentication>>
+
+=== WebAuthn authentication
+
+https://webauthn.guide/[WebAuthn] is an authentication mechanism that replaces passwords.
+When you write a service for registering new users, or logging them in, instead of asking for a password, you can use WebAuthn, which replaces the password.
+For more information, see xref:security-webauthn.adoc[Secure a Quarkus application by using the WebAuthn authentication mechanism].
+
+
+=== OpenID Connect authentication
+
+OpenID Connect (OIDC) is an identity layer that works on top of the OAuth 2.0 protocol. OIDC enables client applications to verify the identity of a user based on the authentication performed by the OIDC provider and to retrieve basic information about that user.
+
+The Quarkus `quarkus-oidc` extension provides a reactive, interoperable, multitenant-enabled OIDC adapter that supports Bearer Token and Authorization Code Flow authentication mechanisms.
+The Bearer Token mechanism extracts the token from the HTTP Authorization header.
+The Authorization Code Flow mechanism redirects the user to an OIDC provider to authenticate the identity of the user.
+After the user is redirected back to Quarkus, the mechanism completes the authentication process by exchanging the provided code that was granted for the ID, access, and refresh tokens.
 
-For more information, see the xref:security-openid-connect-client.adoc[OpenID Connect client and token propagation quickstart] and xref:security-openid-connect-client-reference.adoc[OpenID Connect (OIDC) and OAuth2 client and filters reference] guides.
 You can verify ID and access JWT tokens by using the refreshable JSON Web Key (JWK) set or you can introspect them remotely.
 However, opaque (binary) tokens can only be introspected remotely.
 
@@ -57,14 +148,14 @@ However, opaque (binary) tokens can only be introspected remotely.
 Using the Quarkus OIDC extension, both Bearer Token and Authorization Code Flow mechanisms use <<smallrye-jwt, SmallRye JWT>> to represent JWT tokens as MicroProfile JWT `org.eclipse.microprofile.jwt.JsonWebToken`.
 ====
 
-=== Additional Quarkus resources for OIDC authentication
+==== Additional Quarkus resources for OIDC authentication
 
 For more information about OIDC authentication and authorization methods you can use to secure your Quarkus applications, see the following detailed resources:
 
 [options="header"]
 |====
 |OIDC topic |Quarkus information resource
-|Bearer Token authentication mechanism|xref:security-openid-connect.adoc[Using OpenID Connect (OIDC) to protect service applications using Bearer Token authorization]
+|Bearer Token authentication mechanism|xref:security-oidc-bearer-authentication-concept.adoc[OIDC Bearer authentication]
 |Authorization Code Flow authentication mechanism|xref:security-openid-connect-web-authentication.adoc[OpenID Connect (OIDC) authorization code flow mechanism]
 |Multiple tenants that can support Bearer Token or Authorization Code Flow mechanisms|xref:security-openid-connect-multitenancy.adoc[Using OpenID Connect (OIDC) multi-tenancy]
 |Using Keycloak to centralize authorization|xref:security-keycloak-authorization.adoc[Using OpenID Connect (OIDC) and Keycloak to centralize authorization]
@@ -77,7 +168,7 @@ For more information about OIDC authentication and authorization methods you can
 For more information about managing the individual tenant configurations in multitenant OIDC deployments, see the _Disabling tenant configurations_ section in the xref:security-openid-connect-multitenancy.adoc#disable-tenant[Using OpenID Connect (OIDC) multi-tenancy] guide.
 ====
 
-== OpenID Connect client and filters
+==== OpenID Connect client and filters
 
 The `quarkus-oidc-client` extension provides `OidcClient` for acquiring and refreshing access tokens from OpenID Connect and OAuth2 providers that support the following token grants:
 * `client-credentials`
@@ -100,7 +191,7 @@ This filter can be used to propagate the access token to the downstream services
 For more information, see the xref:security-openid-connect-client.adoc[OpenID Connect client and token propagation quickstart] and xref:security-openid-connect-client-reference.adoc[OpenID Connect (OIDC) and OAuth2 client and filters reference] guides.
 
 [[smallrye-jwt]]
-== SmallRye JWT authentication
+=== SmallRye JWT authentication
 
 The `quarkus-smallrye-jwt` extension provides a MicroProfile JSON Web Token (JWT) 1.2.1 implementation and multiple options to verify signed and encrypted `JWT` tokens and represents them as `org.eclipse.microprofile.jwt.JsonWebToken`.
 
@@ -109,12 +200,13 @@ The `quarkus-smallrye-jwt` extension provides a MicroProfile JSON Web Token (JWT
 
 For more information, see xref:security-jwt.adoc[Using SmallRye JWT role-based access control].
 
-== OAuth2 authentication
+=== OAuth2 authentication
 
 `quarkus-elytron-security-oauth2` provides an alternative to the `quarkus-oidc` Bearer Token authentication mechanism. `quarkus-elytron-security-oauth2` is based on `Elytron` and is primarily intended for introspecting opaque tokens remotely.
 For more information, see xref:security-oauth2.adoc[Using OAuth2].
 
 [[oidc-jwt-oauth2-comparison]]
+
 == Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms
 
 Use the following information to help you to decide which authentication mechanism to use to secure your Quarkus applications:
@@ -210,3 +302,37 @@ The following table provides a summary of the options for each authentication me
 |No
 |===
 
+== Combining authentication mechanisms
+
+If the user credentials are provided by different sources, you can combine  authentication mechanisms.
+For example, you can combine built-in `Basic` and `quarkus-oidc` `Bearer` authentication mechanisms.
+
+[IMPORTANT]
+====
+You cannot combine the `quarkus-oidc` `Bearer` and `smallrye-jwt` authentication mechanisms because both mechanisms attempt to verify the token extracted from the HTTP `Authorization Bearer` scheme.
+====
+
+=== Path-specific authentication mechanisms
+
+The following configuration example demonstrates how you can enforce a single selectable authentication mechanism for a given request path:
+
+[source,properties]
+----
+quarkus.http.auth.permission.basic-or-bearer.paths=/service
+quarkus.http.auth.permission.basic-or-bearer.policy=authenticated
+
+quarkus.http.auth.permission.basic.paths=/basic-only
+quarkus.http.auth.permission.basic.policy=authenticated
+quarkus.http.auth.permission.basic.auth-mechanism=basic
+
+quarkus.http.auth.permission.bearer.paths=/bearer-only
+quarkus.http.auth.permission.bearer.policy=authenticated
+quarkus.http.auth.permission.bearer.auth-mechanism=bearer
+----
+
+Ensure that the value of the `auth-mechanism` property matches the authentication scheme supported by `HttpAuthenticationMechanism`, for example, `basic`, `bearer`, or `form`.
+
+== 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].

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