Skip to content

Commit

Permalink
Conditionalize content in upstream Quarkus repository for the 3.8.nex…
Browse files Browse the repository at this point in the history
…t product release #39954
  • Loading branch information
rolfedh committed Apr 10, 2024
1 parent 051e910 commit 77d7107
Show file tree
Hide file tree
Showing 8 changed files with 84 additions and 37 deletions.
83 changes: 60 additions & 23 deletions docs/src/main/asciidoc/security-authentication-mechanisms.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,10 @@ The following table maps specific authentication requirements to a supported mec

|Username and password |xref:security-basic-authentication.adoc[Basic], <<form-auth>>

|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], <<form-auth>>

Expand Down Expand Up @@ -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
----

Expand Down Expand Up @@ -315,7 +318,9 @@ Quarkus Security also supports the following authentication mechanisms through e
* <<webauthn-authentication>>
* <<openid-connect-authentication>>
* <<smallrye-jwt-authentication>>
ifndef::quarkus-elytron-security-oauth2[]
* <<oauth2-authentication>>
endif::quarkus-elytron-security-oauth2[]

[[webauthn-authentication]]
=== WebAuthn authentication
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -404,13 +411,15 @@ 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

`quarkus-elytron-security-oauth2` provides an alternative to the Quarkus `quarkus-oidc` Bearer token authentication mechanism extension.
`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

Check warning on line 425 in docs/src/main/asciidoc/security-authentication-mechanisms.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Headings] Use sentence-style capitalization in 'SmallRye JWT authentication'. Raw Output: {"message": "[Quarkus.Headings] Use sentence-style capitalization in 'SmallRye JWT authentication'.", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 425, "column": 1}}}, "severity": "INFO"}
Expand All @@ -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`.

Check warning on line 434 in docs/src/main/asciidoc/security-authentication-mechanisms.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'. Raw Output: {"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 434, "column": 71}}}, "severity": "INFO"}
`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.
Expand All @@ -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]
====
Expand All @@ -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

Check warning on line 494 in docs/src/main/asciidoc/security-authentication-mechanisms.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 494, "column": 14}}}, "severity": "INFO"}
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

Check warning on line 518 in docs/src/main/asciidoc/security-authentication-mechanisms.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 518, "column": 7}}}, "severity": "INFO"}
ifndef::quarkus-elytron-security-oauth2[ ^|Yes]
|===

== Combining authentication mechanisms

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Check warning on line 234 in docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'. Raw Output: {"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc", "range": {"start": {"line": 234, "column": 98}}}, "severity": "INFO"}
For more information, see the xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] guide.
====
endif::quarkus-keycloak-admin-client[]



[[keycloak-dev-mode]]
Expand Down Expand Up @@ -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[]
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<db-token-state-manager>> and <<custom-token-state-manager>> 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 <<db-token-state-manager>> 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.

Check warning on line 635 in docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsWarnings] Consider using 'information about' rather than 'information on' unless updating existing content that uses the term. Raw Output: {"message": "[Quarkus.TermsWarnings] Consider using 'information about' rather than 'information on' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc", "range": {"start": {"line": 635, "column": 67}}}, "severity": "WARNING"}
endif::quarkus-oidc-db-token-state-manager[]

See the <<custom-token-state-manager>> 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.

Expand All @@ -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 <<db-token-state-manager>>.
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:
Expand Down Expand Up @@ -751,6 +756,7 @@ public class CustomTokenStateManager implements TokenStateManager {

For information about the default `TokenStateManager` storing tokens in an encrypted session cookie, see <<token-state-manager>>.

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>>.

[[db-token-state-manager]]
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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]

Original file line number Diff line number Diff line change
Expand Up @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -1392,6 +1393,7 @@ Uni<String> tokenUni = oidcClients.getClient("OIDC_CLIENT_NAME")
builder.dynamicHeader("Authorization", tokenUni);
VertxDynamicGraphQLClient client = builder.build();
----
endif::quarkus-oidc-client-graphql[]

[[configuration-reference]]
== Configuration reference
Expand Down
5 changes: 3 additions & 2 deletions docs/src/main/asciidoc/smallrye-graphql-client.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]

0 comments on commit 77d7107

Please sign in to comment.