diff --git a/docs/src/main/asciidoc/security-authentication-mechanisms-concept.adoc b/docs/src/main/asciidoc/security-authentication-mechanisms-concept.adoc new file mode 100644 index 00000000000000..0e2ee27d7d06c3 --- /dev/null +++ b/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 <> 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 +|=== + diff --git a/docs/src/main/asciidoc/security-overview-concept.adoc b/docs/src/main/asciidoc/security-overview-concept.adoc index 198574e1dc111e..8f445fa0fb2048 100644 --- a/docs/src/main/asciidoc/security-overview-concept.adoc +++ b/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