From dce3d582c3173199276f61d0038bc8b917552df2 Mon Sep 17 00:00:00 2001 From: Rolfe Dlugy-Hegwer Date: Wed, 17 Apr 2024 10:58:14 -0400 Subject: [PATCH] Conditionalize content in upstream Quarkus repository for the 3.8.next product release #39954 --- docs/src/main/asciidoc/datasource.adoc | 10 ++ .../security-authentication-mechanisms.adoc | 127 ++++++++++++++---- .../security-basic-authentication-howto.adoc | 7 +- .../security-getting-started-tutorial.adoc | 37 +++-- docs/src/main/asciidoc/security-jpa.adoc | 4 +- .../security-oidc-auth0-tutorial.adoc | 2 + ...-bearer-token-authentication-tutorial.adoc | 7 +- ...rity-oidc-bearer-token-authentication.adoc | 10 ++ ...idc-code-flow-authentication-tutorial.adoc | 2 + ...ecurity-oidc-code-flow-authentication.adoc | 16 ++- ...dc-configuration-properties-reference.adoc | 6 - ...urity-openid-connect-client-reference.adoc | 4 +- .../security-openid-connect-multitenancy.adoc | 2 + .../asciidoc/smallrye-graphql-client.adoc | 5 +- .../src/main/asciidoc/writing-extensions.adoc | 2 +- 15 files changed, 185 insertions(+), 56 deletions(-) diff --git a/docs/src/main/asciidoc/datasource.adoc b/docs/src/main/asciidoc/datasource.adoc index e4f00654893147..e2c3beabca857b 100644 --- a/docs/src/main/asciidoc/datasource.adoc +++ b/docs/src/main/asciidoc/datasource.adoc @@ -101,7 +101,9 @@ For more information about pool size adjustment properties, see the <> -|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::no-quarkus-elytron-security-oauth2[] +, xref:security-oauth2.adoc[OAuth2] +endif::no-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::no-quarkus-elytron-security-oauth2[] * <> +endif::no-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::no-quarkus-keycloak-admin-client[] |Configuring Keycloak programmatically |xref:security-keycloak-admin-client.adoc[Using the Keycloak admin client] +endif::no-quarkus-keycloak-admin-client[] |==== [NOTE] @@ -386,12 +393,15 @@ For example, it can be a public endpoint or be protected with mTLS. In this scenario, you do not need to protect your Quarkus endpoint by using the Quarkus OpenID Connect adapter. ==== +ifndef::no-quarkus-oidc-token-propagation[] The `quarkus-resteasy-client-oidc-token-propagation` extension requires the `quarkus-oidc` extension. It provides Jakarta REST `TokenCredentialRequestFilter`, which sets the OpenID Connect Bearer token or Authorization Code Flow access token as the `Bearer` scheme value of the HTTP `Authorization` header. This filter can be registered with MicroProfile REST client implementations injected into the current Quarkus endpoint, which must be protected by using the Quarkus OIDC adapter. This filter can 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. +endif::no-quarkus-oidc-token-propagation[] + [[smallrye-jwt-authentication]] === SmallRye JWT authentication @@ -404,6 +414,7 @@ It represents them as `org.eclipse.microprofile.jwt.JsonWebToken`. For more information, see the xref:security-jwt.adoc[Using JWT RBAC] guide. +ifndef::no-quarkus-elytron-security-oauth2[] [[oauth2-authentication]] === OAuth2 authentication @@ -411,6 +422,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::no-quarkus-elytron-security-oauth2[] [[oidc-jwt-oauth2-comparison]] == Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms @@ -425,13 +437,20 @@ 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`. +ifndef::no-quarkus-elytron-security-oauth2[] +* If your bearer tokens must be verified, use `quarkus-oidc`, `quarkus-elytron-security-oauth2`, or `quarkus-smallrye-jwt`. +endif::no-quarkus-elytron-security-oauth2[] +ifdef::no-quarkus-elytron-security-oauth2[] +* If your bearer tokens must be verified, use `quarkus-oidc` or `quarkus-smallrye-jwt`. +endif::no-quarkus-elytron-security-oauth2[] * 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::no-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 +461,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::no-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::no-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::no-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] ==== @@ -459,29 +479,82 @@ Nonetheless, the providers effectively delegate most of the token-associated sta [[table]] .Token authentication mechanism comparison |=== -^|Feature required 3+^| Authentication mechanism - -^| ^s|`quarkus-oidc` ^s|`quarkus-smallrye-jwt` ^s| `quarkus-elytron-security-oauth2` - -s|Bearer JWT verification ^|Local verification or introspection ^|Local verification ^|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|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|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 +// Display four columns +ifndef::no-quarkus-elytron-security-oauth2[ ^|Feature required 3+^| Authentication mechanism] +// Display three columns and hide the quarkus-elytron-security-oauth2 column. +ifdef::no-quarkus-elytron-security-oauth2[ ^|Feature required 2+^| Authentication mechanism] + +^| +^s|`quarkus-oidc` +^s|`quarkus-smallrye-jwt` +ifndef::no-quarkus-elytron-security-oauth2[ ^s|`quarkus-elytron-security-oauth2`] + +s|Bearer JWT verification +^|Local verification or introspection +^|Local verification +ifndef::no-quarkus-elytron-security-oauth2[ ^|Introspection] + +s|Bearer opaque token verification +^|Introspection +^|No +ifndef::no-quarkus-elytron-security-oauth2[ ^|Introspection] + +s|Refreshing `JsonWebKey` set to verify JWT tokens +^|Yes +^|Yes +ifndef::no-quarkus-elytron-security-oauth2[ ^|No] + +s|Represent token as `Principal` +^|Yes +^|Yes +ifndef::no-quarkus-elytron-security-oauth2[ ^|Yes] + +s|Inject JWT as MP JWT +^|Yes +^|Yes +ifndef::no-quarkus-elytron-security-oauth2[ ^|No] + +s|Authorization code flow +^| Yes +^|No +ifndef::no-quarkus-elytron-security-oauth2[ ^|No] + +s|Multi-tenancy +^| Yes +^|No +ifndef::no-quarkus-elytron-security-oauth2[ ^|No] + +s|User information support +^| Yes +^|No +ifndef::no-quarkus-elytron-security-oauth2[ ^|No] + +s|PEM key format support +^|No +^|Yes +ifndef::no-quarkus-elytron-security-oauth2[ ^|No] + +s|SecretKey support +^|No +^|In JSON Web Key (JWK) format +ifndef::no-quarkus-elytron-security-oauth2[ ^|No] + +s|Inner-signed and encrypted or encrypted tokens +^|Introspection +^|Local verification +ifndef::no-quarkus-elytron-security-oauth2[ ^|Introspection] + +s|Custom token verification +^|No +^|With injected JWT parser +ifndef::no-quarkus-elytron-security-oauth2[ ^|No] + +s|JWT as a cookie support +^|No +^|Yes +ifndef::no-quarkus-elytron-security-oauth2[ ^|Yes] |=== - == Combining authentication mechanisms If different sources provide the user credentials, you can combine authentication mechanisms. diff --git a/docs/src/main/asciidoc/security-basic-authentication-howto.adoc b/docs/src/main/asciidoc/security-basic-authentication-howto.adoc index 015127dbfb4303..e346a2f31d64ef 100644 --- a/docs/src/main/asciidoc/security-basic-authentication-howto.adoc +++ b/docs/src/main/asciidoc/security-basic-authentication-howto.adoc @@ -18,7 +18,12 @@ Enable xref:security-basic-authentication.adoc[Basic authentication] for your Qu * You have installed at least one extension that provides an `IdentityProvider` based on username and password. For example: -** xref:security-jpa.adoc[Quarkus Security Jakarta Persistence extensions (`security-jpa` or `security-jpa-reactive`)] +ifndef::no-quarkus-security-jpa-reactive[] +** xref:security-jpa.adoc[Quarkus Security Jakarta Persistence extensions (`quarkus-security-jpa` or `quarkus-security-jpa-reactive`)] +endif::no-quarkus-security-jpa-reactive[] +ifdef::no-quarkus-security-jpa-reactive[] +** xref:security-jpa.adoc[Quarkus Security Jakarta Persistence extension (`quarkus-security-jpa`)] +endif::no-quarkus-security-jpa-reactive[] ** xref:security-properties.adoc[Elytron security properties file extension `(quarkus-elytron-security-properties-file)`] ** xref:security-jdbc.adoc[Elytron security JDBC extension `(quarkus-elytron-security-jdbc)`] diff --git a/docs/src/main/asciidoc/security-getting-started-tutorial.adoc b/docs/src/main/asciidoc/security-getting-started-tutorial.adoc index 29311a068cf7d2..5dcab363d539bd 100644 --- a/docs/src/main/asciidoc/security-getting-started-tutorial.adoc +++ b/docs/src/main/asciidoc/security-getting-started-tutorial.adoc @@ -54,12 +54,20 @@ You can find the solution in the `security-jpa-quickstart` link:{quickstarts-tre == Create and verify the Maven project -For Quarkus Security to be able to map your security source to Jakarta Persistence entities, ensure that the Maven project in this tutorial includes the `security-jpa` or `security-jpa-reactive` extension. +ifndef::no-quarkus-security-jpa-reactive[] +For Quarkus Security to be able to map your security source to Jakarta Persistence entities, ensure that the Maven project in this tutorial includes the `quarkus-security-jpa` or `quarkus-security-jpa-reactive` extension. +endif::no-quarkus-security-jpa-reactive[] +ifdef::no-quarkus-security-jpa-reactive[] +For Quarkus Security to be able to map your security source to Jakarta Persistence entities, ensure that the Maven project in this tutorial includes the `quarkus-security-jpa` extension. +endif::no-quarkus-security-jpa-reactive[] [NOTE] ==== -xref:hibernate-orm-panache.adoc[Hibernate ORM with Panache] is used to store your user identities, but you can also use xref:hibernate-orm.adoc[Hibernate ORM] with the `security-jpa` extension. -Both xref:hibernate-reactive.adoc[Hibernate Reactive] and xref:hibernate-reactive-panache.adoc[Hibernate Reactive with Panache] can be used with the `security-jpa-reactive` extension. +xref:hibernate-orm-panache.adoc[Hibernate ORM with Panache] is used to store your user identities, but you can also use xref:hibernate-orm.adoc[Hibernate ORM] with the `quarkus-security-jpa` extension. + +ifndef::no-quarkus-security-jpa-reactive[] +Both xref:hibernate-reactive.adoc[Hibernate Reactive] and xref:hibernate-reactive-panache.adoc[Hibernate Reactive with Panache] can be used with the `quarkus-security-jpa-reactive` extension. +endif::no-quarkus-security-jpa-reactive[] You must also add your preferred database connector library. The instructions in this example tutorial use a PostgreSQL database for the identity store. @@ -86,18 +94,20 @@ include::{includes}/devtools/create-app.adoc[] :add-extension-extensions: security-jpa include::{includes}/devtools/extension-add.adoc[] ==== +ifndef::no-quarkus-security-jpa-reactive[] ** To add the Security Jakarta Persistence extension to an existing Maven project with Hibernate Reactive, run the following command from your project base directory: + ==== :add-extension-extensions: security-jpa-reactive include::{includes}/devtools/extension-add.adoc[] ==== +endif::no-quarkus-security-jpa-reactive[] === Verify the quarkus-security-jpa dependency -After you have run either of the preceding commands to create the Maven project, verify that the `security-jpa` dependency was added to your project build XML file. +After you have run either of the preceding commands to create the Maven project, verify that the `quarkus-security-jpa` dependency was added to your project build XML file. -* To verify the `security-jpa` extension, check for the following configuration: +* To verify the `quarkus-security-jpa` extension, check for the following configuration: + ==== [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"] @@ -115,7 +125,8 @@ After you have run either of the preceding commands to create the Maven project, implementation("io.quarkus:quarkus-security-jpa") ---- ==== -* To verify the `security-jpa-reactive` extension, check for the following configuration: +ifndef::no-quarkus-security-jpa-reactive[] +* To verify the `quarkus-security-jpa-reactive` extension, check for the following configuration: + ==== [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"] @@ -133,6 +144,7 @@ implementation("io.quarkus:quarkus-security-jpa") implementation("io.quarkus:quarkus-security-jpa-reactive") ---- ==== +endif::no-quarkus-security-jpa-reactive[] == Write the application @@ -266,7 +278,7 @@ public class User extends PanacheEntity { ---- -The `security-jpa` extension only initializes if a single entity is annotated with `@UserDefinition`. +The `quarkus-security-jpa` extension only initializes if a single entity is annotated with `@UserDefinition`. <1> The `@UserDefinition` annotation must be present on a single entity, either a regular Hibernate ORM entity or a Hibernate ORM with Panache entity. <2> Indicates the field used for the username. @@ -280,12 +292,13 @@ You can configure it to use plain text or custom passwords. ==== Don’t forget to set up the Panache and PostgreSQL JDBC driver, please see xref:hibernate-orm-panache.adoc#setting-up-and-configuring-hibernate-orm-with-panache[Setting up and configuring Hibernate ORM with Panache] for more information. ==== - +ifndef::no-quarkus-security-jpa-reactive[] [NOTE] ==== Hibernate Reactive Panache uses `io.quarkus.hibernate.reactive.panache.PanacheEntity` instead of `io.quarkus.hibernate.orm.panache.PanacheEntity`. For more information, see link:{quickstarts-tree-url}/security-jpa-reactive-quickstart/src/main/java/org/acme/elytron/security/jpa/reactive/User.java[User file]. ==== +endif::no-quarkus-security-jpa-reactive[] == Configure the application @@ -299,7 +312,7 @@ When secure access is required, and no other authentication mechanisms are enabl Therefore, in this tutorial, you do not need to set the property `quarkus.http.auth.basic` to `true`. ==== + -. Configure at least one data source in the `application.properties` file so the `security-jpa` extension can access your database. +. Configure at least one data source in the `application.properties` file so the `quarkus-security-jpa` extension can access your database. For example: + ==== @@ -318,9 +331,10 @@ quarkus.hibernate-orm.database.generation=drop-and-create + . To initialize the database with users and roles, implement the `Startup` class, as outlined in the following code snippet: +ifndef::no-quarkus-security-jpa-reactive[] [NOTE] ==== -* The URLs of Reactive datasources that are used by the `security-jpa-reactive` extension are set with the `quarkus.datasource.reactive.url` +* The URLs of Reactive datasources that are used by the `quarkus-security-jpa-reactive` extension are set with the `quarkus.datasource.reactive.url` configuration property and not the `quarkus.datasource.jdbc.url` configuration property typically used by JDBC datasources. + [source,properties] @@ -333,6 +347,7 @@ link:https://hibernate.org/orm/[Hibernate ORM] automatically creates the databas This approach is suitable for development but is not recommended for production. Therefore, adjustments are needed in a production environment. ==== +endif::no-quarkus-security-jpa-reactive[] [source,java] ---- @@ -362,7 +377,7 @@ The preceding example demonstrates how the application can be protected and iden [IMPORTANT] ==== In a production environment, do not store plain text passwords. -As a result, the `security-jpa` defaults to using bcrypt-hashed passwords. +As a result, the `quarkus-security-jpa` defaults to using bcrypt-hashed passwords. ==== == Test your application by using Dev Services for PostgreSQL diff --git a/docs/src/main/asciidoc/security-jpa.adoc b/docs/src/main/asciidoc/security-jpa.adoc index d114c46cf9666e..0eefd1783de9e4 100644 --- a/docs/src/main/asciidoc/security-jpa.adoc +++ b/docs/src/main/asciidoc/security-jpa.adoc @@ -78,12 +78,12 @@ public class User extends PanacheEntity { ---- -The `security-jpa` extension initializes only if a single entity is annotated with `@UserDefinition`. +The `quarkus-security-jpa` extension initializes only if a single entity is annotated with `@UserDefinition`. <1> The `@UserDefinition` annotation must be present on a single entity, either a regular Hibernate ORM entity or a Hibernate ORM with Panache entity. <2> Indicates the field used for the username. <3> Indicates the field used for the password. -By default, `security-jpa` uses bcrypt-hashed passwords, or you can configure plain text or custom passwords instead. +By default, `quarkus-security-jpa` uses bcrypt-hashed passwords, or you can configure plain text or custom passwords instead. <4> This indicates the comma-separated list of roles added to the target principal representation attributes. <5> This method lets you add users while hashing passwords with the proper `bcrypt` hash. diff --git a/docs/src/main/asciidoc/security-oidc-auth0-tutorial.adoc b/docs/src/main/asciidoc/security-oidc-auth0-tutorial.adoc index c44e4346d19eb1..6e1ffbb1d991f8 100644 --- a/docs/src/main/asciidoc/security-oidc-auth0-tutorial.adoc +++ b/docs/src/main/asciidoc/security-oidc-auth0-tutorial.adoc @@ -887,6 +887,7 @@ Open a browser, access http://localhost:8080/hello and get the name displayed in To confirm the permission is correctly enforced, change it to `echo.name`: `@PermissionsAllowed("echo.name")`. Clear the browser cache, access http://localhost:8080/hello again and you will get `403` reported by `ApiEchoService`. Now revert it back to `@PermissionsAllowed("echo:name")`. +ifndef::no-deprecated-test-resource[] == Integration testing You have already used OIDC DevUI SPA to login to Auth0 and test the Quarkus endpoint with the access token, updating the endpoint code along the way. @@ -1035,6 +1036,7 @@ image::auth0-test-success.png[Auth0 test success] By the way, if you like, you can run the tests in Continuous mode directly from DevUI: image::auth0-continuous-testing.png[Auth0 Continuous testing] +endif::no-deprecated-test-resource[] [[production-mode]] == Production mode 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..67717da4065b17 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::no-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::no-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::no-quarkus-keycloak-admin-client[] * xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] +endif::no-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 4d764c915a9e93..79675f9d97f7e2 100644 --- a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc +++ b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc @@ -568,6 +568,7 @@ testImplementation("io.rest-assured:rest-assured") testImplementation("io.quarkus:quarkus-junit5") ---- +ifndef::no-deprecated-test-resource[] [[integration-testing-wiremock]] ==== WireMock @@ -688,7 +689,9 @@ public class CustomOidcWireMockStubTest { } } ---- +endif::no-deprecated-test-resource[] +ifndef::no-deprecated-test-resource[] [[integration-testing-oidc-test-client]] === `OidcTestClient` @@ -754,7 +757,9 @@ This test code acquires a token by using a `password` grant from the test `Auth0 For a test like this to work, the test `Auth0` application must have the `password` grant enabled. This example code also shows how to pass additional parameters. For `Auth0`, these are the `audience` and `scope` parameters. +endif::no-deprecated-test-resource[] +ifndef::no-deprecated-test-resource[] [[integration-testing-keycloak-devservices]] ==== Dev Services for Keycloak @@ -848,7 +853,9 @@ public class NativeBearerTokenAuthenticationIT extends BearerTokenAuthentication ---- For more information about initializing and configuring Dev Services for Keycloak, see the xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] guide. +endif::no-deprecated-test-resource[] +ifndef::no-deprecated-test-resource[] [[integration-testing-keycloak]] ==== `KeycloakTestResourceLifecycleManager` @@ -951,6 +958,7 @@ By default: By default, `KeycloakTestResourceLifecycleManager` uses HTTPS to initialize a Keycloak instance, and this can be disabled by using `keycloak.use.https=false`. The default realm name is `quarkus`, and the client id is `quarkus-service-app`. If you want to customize these values, set the `keycloak.realm` and `keycloak.service.client` system properties. +endif::no-deprecated-test-resource[] [[integration-testing-public-key]] ==== Local public key @@ -1350,5 +1358,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::no-quarkus-keycloak-admin-client[] * xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] +endif::no-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..2a8c6219970bf5 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::no-quarkus-keycloak-admin-client[] * xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] +endif::no-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 e2bda15eeca668..2f1bd9e5b42d6e 100644 --- a/docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc +++ b/docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc @@ -640,8 +640,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::no-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::no-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. @@ -667,8 +670,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::no-quarkus-oidc-db-token-state-manager[] An alternative solution is to have the tokens saved in the database. For more information, see <>. +endif::no-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: @@ -760,6 +765,7 @@ public class CustomTokenStateManager implements TokenStateManager { For information about the default `TokenStateManager` storing tokens in an encrypted session cookie, see <>. +ifndef::no-quarkus-oidc-db-token-state-manager[] For information about the custom Quarkus `TokenStateManager` implementation storing tokens in a database, see <>. [[db-token-state-manager]] @@ -861,6 +867,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::no-quarkus-oidc-db-token-state-manager[] ==== Logout and expiration @@ -1533,6 +1540,7 @@ testImplementation("net.sourceforge.htmlunit:htmlunit") testImplementation("io.quarkus:quarkus-junit5") ---- +ifndef::no-deprecated-test-resource[] [[integration-testing-wiremock]] === Wiremock @@ -1619,6 +1627,7 @@ The user `admin` has the `user` and `admin` roles by default - it can be customi Additionally, `OidcWiremockTestResource` sets the token issuer and audience to `https://service.example.com`, which can be customized with `quarkus.test.oidc.token.issuer` and `quarkus.test.oidc.token.audience` system properties. `OidcWiremockTestResource` can be used to emulate all OIDC providers. +endif::no-deprecated-test-resource[] [[integration-testing-keycloak-devservices]] === Dev Services for Keycloak @@ -1655,6 +1664,7 @@ public class CodeFlowAuthorizationTest { } ---- +ifndef::no-deprecated-test-resource[] [[integration-testing-keycloak]] === Using KeycloakTestResourceLifecycleManager @@ -1719,6 +1729,7 @@ The user `admin` has the `user` and `admin` roles by default - it can be customi By default, `KeycloakTestResourceLifecycleManager` uses HTTPS to initialize a Keycloak instance that can be disabled by specifying `keycloak.use.https=false`. The default realm name is `quarkus` and client id is `quarkus-web-app` - set `keycloak.realm` and `keycloak.web-app.client` system properties to customize the values if needed. +endif::no-deprecated-test-resource[] [[integration-testing-security-annotation]] === TestSecurity annotation @@ -1764,4 +1775,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 db214a15dbe159..d749c4bc113637 100644 --- a/docs/src/main/asciidoc/security-openid-connect-client-reference.adoc +++ b/docs/src/main/asciidoc/security-openid-connect-client-reference.adoc @@ -1346,7 +1346,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::no-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. @@ -1401,6 +1402,7 @@ Uni tokenUni = oidcClients.getClient("OIDC_CLIENT_NAME") builder.dynamicHeader("Authorization", tokenUni); VertxDynamicGraphQLClient client = builder.build(); ---- +endif::no-quarkus-oidc-client-graphql[] [[configuration-reference]] == Configuration reference diff --git a/docs/src/main/asciidoc/security-openid-connect-multitenancy.adoc b/docs/src/main/asciidoc/security-openid-connect-multitenancy.adoc index cb2ea8024881ce..f89e79f8c13460 100644 --- a/docs/src/main/asciidoc/security-openid-connect-multitenancy.adoc +++ b/docs/src/main/asciidoc/security-openid-connect-multitenancy.adoc @@ -410,6 +410,7 @@ After a little while, you can run this binary directly: == Test the application +ifndef::no-deprecated-test-resource[] === Use Dev Services for Keycloak xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] is recommended for the integration testing against Keycloak. @@ -562,6 +563,7 @@ public class CodeFlowIT extends CodeFlowTest { ---- For more information about how it is initialized and configured, see xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak]. +endif::no-deprecated-test-resource[] === Use the browser diff --git a/docs/src/main/asciidoc/smallrye-graphql-client.adoc b/docs/src/main/asciidoc/smallrye-graphql-client.adoc index 4aa0a118e0d6b7..bfe200446348c1 100644 --- a/docs/src/main/asciidoc/smallrye-graphql-client.adoc +++ b/docs/src/main/asciidoc/smallrye-graphql-client.adoc @@ -363,7 +363,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::no-quarkus-oidc-client-graphql[] +* xref:security-openid-connect-client-reference.adoc#quarkus-oidc-client-graphql[Integrating OIDC clients into GraphQL clients] +endif::no-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] - diff --git a/docs/src/main/asciidoc/writing-extensions.adoc b/docs/src/main/asciidoc/writing-extensions.adoc index 7bf884802e9b45..303c7089a6a2d0 100644 --- a/docs/src/main/asciidoc/writing-extensions.adoc +++ b/docs/src/main/asciidoc/writing-extensions.adoc @@ -2334,7 +2334,7 @@ A feature can be registered in a <> method that produces } ---- -The name of the feature should only contain lowercase characters, words are separated by dash; e.g. `security-jpa`. +The name of the feature should only contain lowercase characters, words are separated by dash; e.g. `quarkus-security-jpa`. An extension should provide at most one feature and the name must be unique. If multiple extensions register a feature of the same name the build fails.