Moved 'Authentication mechanisms' to a new topic

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

@@ -0,0 +1,212 @@
+////
+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
+include::_attributes.adoc[]
+:categories: security
+
+The Quarkus Security framework supports multiple authentication mechanisms, which you can use to secure your applications.
+
+== Basic and Form HTTP authentication
+
+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.
+
+== 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].
+
+== Mutual TLS (mTLS) 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
+
+OpenID Connect (OIDC) i== 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`
+* `password`
+* `refresh_token`
+
+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.
+
+[IMPORTANT]
+====
+In this scenario, you do not need to protect your Quarkus endpoint by using the Quarkus OpenID Connect adapter.
+====
+
+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.
+
+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.
+
+[NOTE]
+====
+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
+
+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]
+|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]
+|Configuring Keycloak programmatically|xref:security-keycloak-admin-client.adoc[Using the Keycloak admin client]
+|====
+
+[NOTE]
+====
+* If you need to enable the Quarkus OIDC extension at runtime, set `quarkus.oidc.tenant-enabled=false` at build time and then re-enable it at runtime by using a system property.
+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
+
+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`
+
+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.
+
+[IMPORTANT]
+====
+In this scenario, you do not need to protect your Quarkus endpoint by using the Quarkus OpenID Connect adapter.
+====
+
+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.
+
+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
+
+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`.
+
+`quarkus-smallrye-jwt` is an alternative to the `quarkus-oidc` Bearer Token authentication mechanism, and verifies only `JWT` tokens by using either PEM keys or the refreshable `JWK` key set.
+`quarkus-smallrye-jwt` also provides the JWT generation API, which you can use to easily create `signed`, `inner-signed`, and `encrypted` `JWT` tokens.
+
+For more information, see xref:security-jwt.adoc[Using SmallRye JWT role-based access control].
+
+== 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:
+
+* `quarkus-oidc` requires an OpenID Connect provider such as Keycloak, which can be used to verify the Bearer tokens or authenticate the end users with the Authorization Code flow.
+In both cases, `quarkus-oidc` requires a connection to the specified OpenID Connect provider.
+
+* If the user authentication requires Authorization Code flow or you need to support multiple tenants, use `quarkus-oidc`.
+`quarkus-oidc` can also request user information by using both Authorization Code Flow and Bearer access tokens.
+
+* If your Bearer tokens must be verified, use `quarkus-oidc`, `quarkus-smallrye-jwt`, or `quarkus-elytron-security-oauth2`.
+
+* If your Bearer tokens are in a JWT format, you can use either of the three extensions. Both `quarkus-oidc` and `quarkus-smallrye-jwt` support refreshing the JsonWebKey (JWK) set when the OpenID Connect provider rotates the keys.
+Therefore, if remote token introspection must be avoided or is unsupported by the providers, use `quarkus-oidc` or `quarkus-smallrye-jwt` for verifying JWT tokens.
+
+* If you need to introspect the JWT tokens remotely, you can use either `quarkus-oidc` or `quarkus-elytron-security-oauth2` because they support the verification of the opaque or binary tokens by using remote introspection.
+`quarkus-smallrye-jwt` does not support the remote introspection of both opaque or JWT tokens but instead relies on the locally available keys that are usually retrieved from the OpenID Connect provider.
+
+* `quarkus-oidc` and `quarkus-smallrye-jwt` support the injecting of JWT and opaque tokens into the endpoint code.
+Injected JWT tokens provide more information about the user. All extensions can have the tokens injected as `Principal`.
+
+* `quarkus-smallrye-jwt` supports more key formats than `quarkus-oidc`. `quarkus-oidc` uses only the JWK-formatted keys that are part of a JWK set, whereas `quarkus-smallrye-jwt` supports PEM keys.
+
+* `quarkus-smallrye-jwt` handles locally signed, inner-signed-and-encrypted, and encrypted tokens.
+While `quarkus-oidc` and `quarkus-elytron-security-oauth2` can also verify such tokens but treats them as opaque tokens and verifies them through remote introspection.
+
+* If you need a lightweight library for the remote introspection of opaque or JWT tokens, use `quarkus-elytron-security-oauth2`.
+
+[NOTE]
+====
+Your decision to choose whether to use opaque or JWT token format will be driven by architectural considerations.
+Opaque tokens tend to be much shorter than JWT tokens but need most of the token-associated state to be maintained in the provider database.
+Opaque tokens are effectively database pointers.
+JWT tokens are significantly longer than the opaque tokens but the providers are effectively delegating storing most of the token-associated state to the client by storing it as the token claims and either signing or encrypting them.
+====
+
+The following table provides a summary of the options for each authentication mechanism:
+
+|===
+| | quarkus-oidc| quarkus-smallrye-jwt | quarkus-elytron-security-oauth2
+
+|Requires Bearer JWT verification
+|Local verification or introspection
+|Local verification
+|Introspection
+|Requires Bearer opaque token verification
+|Introspection
+|No
+|Introspection
+|Refreshing `JsonWebKey` set for verifying JWT tokens
+|Yes
+|Yes
+|No
+|Represent token as `Principal`
+|Yes
+|Yes
+|Yes
+|Inject JWT as MP JSON Web Token (JWT)
+|Yes
+|Yes
+|No
+|Authorization Code Flow
+|Yes
+|No
+|No
+|Multi-tenancy
+|Yes
+|No
+|No
+|User info support
+|Yes
+|No
+|No
+|PEM key format support
+|No
+|Yes
+|No
+|SecretKey support
+|No
+|In JSON Web Key (JWK) format
+|No
+|Inner-signed and encrypted or encrypted tokens
+|Introspection
+|Local verification
+|Introspection
+|Custom token verification
+|No
+|With injected JWT parser
+|No
+|Accept JWT as a cookie
+|No
+|Yes
+|No
+|===
+

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

@@ -2,7 +2,7 @@
 = Quarkus Security overview
 include::_attributes.adoc[]
 :categories: security
-
+ 
 Quarkus Security is a framework that provides the architecture, multiple authentication and authorization mechanisms, and other tools for you to build secure and production-quality Java applications.
 
 == Getting started with Quarkus Security