From 77d7107115f8ac53915e966f8c9c21c6c6cf8af8 Mon Sep 17 00:00:00 2001 From: Rolfe Dlugy-Hegwer Date: Wed, 10 Apr 2024 18:58:07 -0400 Subject: [PATCH] Conditionalize content in upstream Quarkus repository for the 3.8.next product release #39954 --- .../security-authentication-mechanisms.adoc | 83 ++++++++++++++----- ...-bearer-token-authentication-tutorial.adoc | 7 +- ...rity-oidc-bearer-token-authentication.adoc | 2 + ...idc-code-flow-authentication-tutorial.adoc | 2 + ...ecurity-oidc-code-flow-authentication.adoc | 12 ++- ...dc-configuration-properties-reference.adoc | 6 -- ...urity-openid-connect-client-reference.adoc | 4 +- .../asciidoc/smallrye-graphql-client.adoc | 5 +- 8 files changed, 84 insertions(+), 37 deletions(-) diff --git a/docs/src/main/asciidoc/security-authentication-mechanisms.adoc b/docs/src/main/asciidoc/security-authentication-mechanisms.adoc index f7fea7001febd6..25ea1a9d90ce97 100644 --- a/docs/src/main/asciidoc/security-authentication-mechanisms.adoc +++ b/docs/src/main/asciidoc/security-authentication-mechanisms.adoc @@ -35,7 +35,10 @@ The following table maps specific authentication requirements to a supported mec |Username and password |xref:security-basic-authentication.adoc[Basic], <> -|Bearer access token |xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication], xref:security-jwt.adoc[JWT], xref:security-oauth2.adoc[OAuth2] +|Bearer access token |xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication], xref:security-jwt.adoc[JWT] +ifndef::quarkus-elytron-security-oauth2[] +, xref:security-oauth2.adoc[OAuth2] +endif::quarkus-elytron-security-oauth2[] |Single sign-on (SSO) |xref:security-oidc-code-flow-authentication.adoc[OIDC Code Flow], <> @@ -96,7 +99,7 @@ quarkus.http.auth.form.error-page= # Define testing user quarkus.security.users.embedded.enabled=true quarkus.security.users.embedded.plain-text=true -quarkus.security.users.embedded.users.alice=alice +quarkus.security.users.embedded.users.alice=alice quarkus.security.users.embedded.roles.alice=user ---- @@ -315,7 +318,9 @@ Quarkus Security also supports the following authentication mechanisms through e * <> * <> * <> +ifndef::quarkus-elytron-security-oauth2[] * <> +endif::quarkus-elytron-security-oauth2[] [[webauthn-authentication]] === WebAuthn authentication @@ -357,7 +362,9 @@ For more information about OIDC authentication and authorization methods that yo |Multiple tenants that can support the Bearer token authentication or Authorization Code Flow mechanisms|xref:security-openid-connect-multitenancy.adoc[Using OpenID Connect (OIDC) multi-tenancy] |Securing Quarkus with commonly used OpenID Connect providers|xref:security-openid-connect-providers.adoc[Configuring well-known OpenID Connect providers] |Using Keycloak to centralize authorization |xref:security-keycloak-authorization.adoc[Using OpenID Connect (OIDC) and Keycloak to centralize authorization] +ifndef::quarkus-keycloak-admin-client[] |Configuring Keycloak programmatically |xref:security-keycloak-admin-client.adoc[Using the Keycloak admin client] +endif::quarkus-keycloak-admin-client[] |==== [NOTE] @@ -404,6 +411,7 @@ It represents them as `org.eclipse.microprofile.jwt.JsonWebToken`. For more information, see the xref:security-jwt.adoc[Using JWT RBAC] guide. +ifndef::quarkus-elytron-security-oauth2[] [[oauth2-authentication]] === OAuth2 authentication @@ -411,6 +419,7 @@ For more information, see the xref:security-jwt.adoc[Using JWT RBAC] guide. `quarkus-elytron-security-oauth2` is based on `Elytron` and is primarily intended for introspecting opaque tokens remotely. For more information, see the Quarkus xref:security-oauth2.adoc[Using OAuth2] guide. +endif::quarkus-elytron-security-oauth2[] [[oidc-jwt-oauth2-comparison]] == Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms @@ -425,13 +434,17 @@ In both cases, `quarkus-oidc` requires a connection to the specified OpenID Conn * 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 must be verified, use `quarkus-oidc`, +ifndef::quarkus-elytron-security-oauth2[`quarkus-elytron-security-oauth2`, ] +or `quarkus-smallrye-jwt`. * If your bearer tokens are in a JSON web token (JWT) format, you can use any extensions in the preceding list. 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` to verify JWT tokens. -* To introspect the JWT tokens remotely, you can use either `quarkus-oidc` or `quarkus-elytron-security-oauth2` because they support verifying the opaque or binary tokens by using remote introspection. +* To introspect the JWT tokens remotely, you can use `quarkus-oidc` +ifndef::quarkus-elytron-security-oauth2[or `quarkus-elytron-security-oauth2`] +for verifying 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 JWT and opaque token injection into the endpoint code. @@ -442,9 +455,10 @@ All extensions can have the tokens injected as `Principal`. `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. -In contrast, although `quarkus-oidc` and `quarkus-elytron-security-oauth2` can also verify such tokens, they treat them as opaque tokens and verify them through remote introspection. +ifndef::quarkus-elytron-security-oauth2[In contrast, although `quarkus-oidc` and `quarkus-elytron-security-oauth2` can also verify such tokens, they treat them as opaque tokens and verify them through remote introspection.] +ifdef::quarkus-elytron-security-oauth2[In contrast, although `quarkus-oidc` can also verify such tokens, it 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`. +ifndef::quarkus-elytron-security-oauth2[* If you need a lightweight library for the remote introspection of opaque or JWT tokens, use `quarkus-elytron-security-oauth2`.] [NOTE] ==== @@ -457,30 +471,53 @@ Nonetheless, the providers effectively delegate most of the token-associated sta ==== [[table]] -.Token authentication mechanism comparison +.Comparison of features by token authentication mechanism or extension |=== -^|Feature required 3+^| Authentication mechanism +ifndef::quarkus-elytron-security-oauth2[ ^|Feature required 3+^| Authentication mechanism] +ifdef::quarkus-elytron-security-oauth2[ ^|Feature required 2+^| Authentication mechanism] -^| ^s|`quarkus-oidc` ^s|`quarkus-smallrye-jwt` ^s| `quarkus-elytron-security-oauth2` +^| ^s|`quarkus-oidc` ^s|`quarkus-smallrye-jwt` +ifndef::quarkus-elytron-security-oauth2[ ^s|`quarkus-elytron-security-oauth2`] -s|Bearer JWT verification ^|Local verification or introspection ^|Local verification ^|Introspection +s|Bearer JWT verification ^|Local verification or introspection ^|Local verification +ifndef::quarkus-elytron-security-oauth2[ ^|Introspection] -s|Bearer opaque token verification ^|Introspection ^|No ^|Introspection -s|Refreshing `JsonWebKey` set to verify JWT tokens ^|Yes ^|Yes ^|No -s|Represent token as `Principal` ^|Yes ^|Yes ^|Yes -s|Inject JWT as MP JWT ^|Yes ^|Yes ^|No +s|Bearer opaque token verification ^|Introspection ^|No +ifndef::quarkus-elytron-security-oauth2[ ^|Introspection] -s|Authorization code flow ^| Yes ^|No ^|No -s|Multi-tenancy ^| Yes ^|No ^|No -s|User information support ^| Yes ^|No ^|No -s|PEM key format support ^|No ^|Yes ^|No +s|Refreshing `JsonWebKey` set to verify JWT tokens ^|Yes ^|Yes +ifndef::quarkus-elytron-security-oauth2[ ^|No] -s|SecretKey support ^|No ^|In JSON Web Key (JWK) format ^|No -s|Inner-signed and encrypted or encrypted tokens ^|Introspection ^|Local verification ^|Introspection -s|Custom token verification ^|No ^|With injected JWT parser ^|No -s|JWT as a cookie support ^|No ^|Yes ^|Yes -|=== +s|Represent token as `Principal` ^|Yes ^|Yes +ifndef::quarkus-elytron-security-oauth2[ ^|Yes] + +s|Inject JWT as MP JWT ^|Yes ^|Yes +ifndef::quarkus-elytron-security-oauth2[ ^|No] + +s|Authorization code flow ^| Yes ^|No +ifndef::quarkus-elytron-security-oauth2[ ^|No] + +s|Multi-tenancy ^| Yes ^|No +ifndef::quarkus-elytron-security-oauth2[ ^|No] + +s|User information support ^| Yes ^|No +ifndef::quarkus-elytron-security-oauth2[ ^|No] +s|PEM key format support ^|No ^|Yes +ifndef::quarkus-elytron-security-oauth2[ ^|No] + +s|SecretKey support ^|No ^|In JSON Web Key (JWK) format +ifndef::quarkus-elytron-security-oauth2[ ^|No] + +s|Inner-signed and encrypted or encrypted tokens ^|Introspection ^|Local verification +ifndef::quarkus-elytron-security-oauth2[ ^|Introspection] + +s|Custom token verification ^|No ^|With injected JWT parser +ifndef::quarkus-elytron-security-oauth2[ ^|No] + +s|JWT as a cookie support ^|No ^|Yes +ifndef::quarkus-elytron-security-oauth2[ ^|Yes] +|=== == Combining authentication mechanisms diff --git a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc index 6b2f9b06a891a2..4e114bdb9d595f 100644 --- a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc +++ b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc @@ -228,13 +228,14 @@ docker run --name keycloak -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=ad For more information, see the Keycloak documentation about link:https://www.keycloak.org/docs/latest/server_admin/index.html#configuring-realms[creating and configuring a new realm]. - +ifndef::quarkus-keycloak-admin-client[] [NOTE] ==== If you want to use the Keycloak Admin Client to configure your server from your application, you need to include either the `quarkus-keycloak-admin-rest-client` or the `quarkus-keycloak-admin-resteasy-client` (if the application uses `quarkus-rest-client`) extension. For more information, see the xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] guide. - ==== +endif::quarkus-keycloak-admin-client[] + [[keycloak-dev-mode]] @@ -367,4 +368,6 @@ For information about writing integration tests that depend on `Dev Services for * xref:security-jwt-build.adoc[Sign and encrypt JWT tokens with SmallRye JWT Build] * xref:security-authentication-mechanisms.adoc#combining-authentication-mechanisms[Combining authentication mechanisms] * xref:security-overview.adoc[Quarkus Security overview] +ifndef::quarkus-keycloak-admin-client[] * xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] +endif::quarkus-keycloak-admin-client[] diff --git a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc index 2a02b3292ca038..efdc8d6ea4e2cb 100644 --- a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc +++ b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc @@ -1290,5 +1290,7 @@ For more information, see xref:security-oidc-code-flow-authentication#oidc-reque * xref:security-authentication-mechanisms.adoc#oidc-jwt-oauth2-comparison[Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms] * xref:security-authentication-mechanisms.adoc#combining-authentication-mechanisms[Combining authentication mechanisms] * xref:security-overview.adoc[Quarkus Security overview] +ifndef::quarkus-keycloak-admin-client[] * xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] +endif::quarkus-keycloak-admin-client[] * xref:security-openid-connect-multitenancy.adoc[Using OpenID Connect Multi-Tenancy] diff --git a/docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc b/docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc index 4ccd40e661a684..10f6aff5282fd7 100644 --- a/docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc +++ b/docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc @@ -278,7 +278,9 @@ After you have completed this tutorial, explore xref:security-oidc-bearer-token- * xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] * xref:security-jwt-build.adoc[Sign and encrypt JWT tokens with SmallRye JWT Build] * xref:security-authentication-mechanisms.adoc#oidc-jwt-oauth2-comparison[Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms] +ifndef::quarkus-keycloak-admin-client[] * xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] +endif::quarkus-keycloak-admin-client[] * https://www.keycloak.org/documentation.html[Keycloak Documentation] * xref:security-oidc-auth0-tutorial.adoc[Protect Quarkus web application by using Auth0 OpenID Connect provider] * https://openid.net/connect/[OpenID Connect] diff --git a/docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc b/docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc index 299c83c7321fbe..fadfece149b930 100644 --- a/docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc +++ b/docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc @@ -631,8 +631,11 @@ OIDC `CodeAuthenticationMechanism` uses the default `io.quarkus.oidc.TokenStateM It makes Quarkus OIDC endpoints completely stateless and it is recommended to follow this strategy to achieve the best scalability results. -See the <> and <> sections of this guide for alternative approaches to storing tokens. -For example, storing tokens in the database or other server-side storage, if you prefer and have good reasons for storing the token state on the server. +ifndef::quarkus-oidc-db-token-state-manager[] +Refer to the <> section of this guide for information on storing tokens in the database or other server-side storage solutions. This approach is suitable if you prefer and have compelling reasons to store the token state on the server. +endif::quarkus-oidc-db-token-state-manager[] + +See the <> section for alternative methods of token storage. This is ideal for those seeking customized solutions for token state management, especially when standard server-side storage does not meet your specific requirements. You can configure the default `TokenStateManager` to avoid saving an access token in the session cookie and to only keep ID and refresh tokens or a single ID token only. @@ -658,8 +661,10 @@ In such cases, use the `quarkus.oidc.token-state-manager.strategy` property to c If your chosen session cookie strategy combines tokens and generates a large session cookie value that is greater than 4KB, some browsers might not be able to handle such cookie sizes. This can occur when the ID, access, and refresh tokens are JWT tokens and the selected strategy is `keep-all-tokens` or with ID and refresh tokens when the strategy is `id-refresh-token`. To work around this issue, you can set `quarkus.oidc.token-state-manager.split-tokens=true` to create a unique session token for each token. +ifndef::quarkus-oidc-db-token-state-manager[] An alternative solution is to have the tokens saved in the database. For more information, see <>. +endif::quarkus-oidc-db-token-state-manager[] The default `TokenStateManager` encrypts the tokens before storing them in the session cookie. The following example shows how you configure it to split the tokens and encrypt them: @@ -751,6 +756,7 @@ public class CustomTokenStateManager implements TokenStateManager { For information about the default `TokenStateManager` storing tokens in an encrypted session cookie, see <>. +ifndef::quarkus-oidc-db-token-state-manager[] For information about the custom Quarkus `TokenStateManager` implementation storing tokens in a database, see <>. [[db-token-state-manager]] @@ -852,6 +858,7 @@ public class OidcDbTokenStateManagerEntity { <1> The Hibernate ORM extension will only create this table for you when the database schema is generated. For more information, refer to the xref:hibernate-orm.adoc[Hibernate ORM] guide. <2> You can choose a column length depending on the length of your tokens. +endif::quarkus-oidc-db-token-state-manager[] ==== Logout and expiration @@ -1751,4 +1758,3 @@ From the `quarkus dev` console, type `j` to change the application global log le * https://www.keycloak.org/documentation.html[Keycloak documentation] * https://openid.net/connect/[OpenID Connect] * https://tools.ietf.org/html/rfc7519[JSON Web Token] - diff --git a/docs/src/main/asciidoc/security-oidc-configuration-properties-reference.adoc b/docs/src/main/asciidoc/security-oidc-configuration-properties-reference.adoc index 438a9f72a3ec4d..e76df52eb6375f 100644 --- a/docs/src/main/asciidoc/security-oidc-configuration-properties-reference.adoc +++ b/docs/src/main/asciidoc/security-oidc-configuration-properties-reference.adoc @@ -19,14 +19,8 @@ include::{generated-dir}/config/quarkus-oidc.adoc[opts=optional, leveloffset=+1] * xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication] * xref:security-oidc-bearer-token-authentication-tutorial.adoc[Protect a service application by using OpenID Connect (OIDC) Bearer token authentication] -// * https://www.keycloak.org/documentation.html[Keycloak Documentation] * https://openid.net/connect/[OpenID Connect] -// * https://tools.ietf.org/html/rfc7519[JSON Web Token] * xref:security-openid-connect-client-reference.adoc[OpenID Connect and OAuth2 Client and Filters Reference Guide] -// * xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] -// * xref:security-jwt-build.adoc[Sign and encrypt JWT tokens with SmallRye JWT Build] * xref:security-authentication-mechanisms.adoc#oidc-jwt-oauth2-comparison[Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms] * xref:security-authentication-mechanisms.adoc#combining-authentication-mechanisms[Combining authentication mechanisms] * xref:security-overview.adoc[Quarkus Security] -// * xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] -// TASK - Select some references and eliminate the rest. diff --git a/docs/src/main/asciidoc/security-openid-connect-client-reference.adoc b/docs/src/main/asciidoc/security-openid-connect-client-reference.adoc index 48a482d4b20916..80e36256e8cf85 100644 --- a/docs/src/main/asciidoc/security-openid-connect-client-reference.adoc +++ b/docs/src/main/asciidoc/security-openid-connect-client-reference.adoc @@ -1337,7 +1337,8 @@ The `quarkus-rest-client-resteasy-client-oidc-token-propagation` extension provi The `quarkus-rest-client-resteasy-client-oidc-token-propagation` extension (as opposed to the non-reactive `quarkus-resteasy-client-oidc-token-propagation` extension) does not currently support the exchanging or resigning of the tokens before the propagation. However, these features might be added in the future. -[[oidc-client-graphql-client]] +ifndef::quarkus-oidc-client-graphql[] +[[quarkus-oidc-client-graphql]] == GraphQL client integration The `quarkus-oidc-client-graphql` extension provides a way to integrate an OIDC client into xref:smallrye-graphql-client.adoc[GraphQL clients] paralleling the approach used with REST clients. @@ -1392,6 +1393,7 @@ Uni tokenUni = oidcClients.getClient("OIDC_CLIENT_NAME") builder.dynamicHeader("Authorization", tokenUni); VertxDynamicGraphQLClient client = builder.build(); ---- +endif::quarkus-oidc-client-graphql[] [[configuration-reference]] == Configuration reference diff --git a/docs/src/main/asciidoc/smallrye-graphql-client.adoc b/docs/src/main/asciidoc/smallrye-graphql-client.adoc index de25e13e8ff090..85331d865db735 100644 --- a/docs/src/main/asciidoc/smallrye-graphql-client.adoc +++ b/docs/src/main/asciidoc/smallrye-graphql-client.adoc @@ -350,7 +350,8 @@ This example showed how to use both the dynamic and typesafe GraphQL clients to GraphQL service and explained the difference between the client types. == References +ifndef::quarkus-oidc-client-graphql[] +* xref:security-openid-connect-client-reference.adoc#quarkus-oidc-client-graphql[Integrating OIDC clients into GraphQL clients] +endif::quarkus-oidc-client-graphql[] -* xref:security-openid-connect-client-reference.adoc#oidc-client-graphql-client[Integrating OIDC clients into GraphQL clients] * https://smallrye.io/smallrye-graphql/latest/[Upstream SmallRye GraphQL Client documentation] -