Skip to content

Commit

Permalink
Avoid using Reactive for Quarkus REST in security doc
Browse files Browse the repository at this point in the history 
Also remove a redundant section.
  • Loading branch information
@gsmet
gsmet committed Sep 6, 2024
1 parent c7204eb commit 141e84a
Show file tree
Hide file tree
Showing 6 changed files with 11 additions and 29 deletions.
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/security-jwt.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -817,7 +817,7 @@ To prevent it, set `quarkus.smallrye-jwt.blocking-authentication=true`.

=== Token Propagation

Please see the xref:security-openid-connect-client-reference.adoc#token-propagation[Token Propagation] section about the Bearer access token propagation to the downstream services.
Please see the xref:security-openid-connect-client-reference.adoc#token-propagation-rest[Token Propagation] section about the Bearer access token propagation to the downstream services.

Check warning on line 820 in docs/src/main/asciidoc/security-jwt.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Token Propagation'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Token Propagation'.", "location": {"path": "docs/src/main/asciidoc/security-jwt.adoc", "range": {"start": {"line": 820, "column": 73}}}, "severity": "INFO"}

[[integration-testing]]
=== Testing
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/security-oidc-auth0-tutorial.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -625,7 +625,7 @@ In fact, the last code example, showing the injected `UserInfo`, is a concrete e
But what about propagating access tokens to some custom services ? It is very easy to achieve in Quarkus, both for the authorization code and bearer token flows. All you need to do is to create a REST Client interface for calling the service requiring a Bearer token access and annotate it with `@AccessToken` and the access token arriving to the front-end endpoint as the Auth0 Bearer access token or acquired by Quarkus after completing the Auth0 authorization code flow, will be propagated to the target microservice. This is as easy as it can get.

Check warning on line 625 in docs/src/main/asciidoc/security-oidc-auth0-tutorial.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.

Raw Output:
{"message": "[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "docs/src/main/asciidoc/security-oidc-auth0-tutorial.adoc", "range": {"start": {"line": 625, "column": 163}}}, "severity": "INFO"}

Check warning on line 625 in docs/src/main/asciidoc/security-oidc-auth0-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-auth0-tutorial.adoc", "range": {"start": {"line": 625, "column": 171}}}, "severity": "INFO"}

Check warning on line 625 in docs/src/main/asciidoc/security-oidc-auth0-tutorial.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-oidc-auth0-tutorial.adoc", "range": {"start": {"line": 625, "column": 367}}}, "severity": "INFO"}

For examples of propagating access tokens, see the following sections in this tutorial.
For more information about token propagation, see xref:security-openid-connect-client-reference.adoc#reactive-token-propagation[OIDC token propagation].
For more information about token propagation, see xref:security-openid-connect-client-reference.adoc#token-propagation-rest[OIDC token propagation].

[[jwt-access-tokens]]
=== Access tokens in JWT format
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -475,7 +475,7 @@ quarkus.oidc.introspection-path=/protocol/openid-connect/tokens/introspect

=== Token propagation

For information about bearer access token propagation to the downstream services, see the xref:security-openid-connect-client-reference.adoc#token-propagation[Token propagation] section of the Quarkus "OpenID Connect (OIDC) and OAuth2 client and filters reference" guide.
For information about bearer access token propagation to the downstream services, see the xref:security-openid-connect-client-reference.adoc#token-propagation-rest[Token propagation] section of the Quarkus "OpenID Connect (OIDC) and OAuth2 client and filters reference" guide.

=== JWT token certificate chain

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

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'JWT token certificate chain'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'JWT token certificate chain'.", "location": {"path": "docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc", "range": {"start": {"line": 480, "column": 5}}}, "severity": "INFO"}

Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1497,7 +1497,7 @@ TIP: You can listen to other security events as described in the xref:security-c

=== Propagating tokens to downstream services

For information about Authorization Code Flow access token propagation to downstream services, see the xref:security-openid-connect-client-reference.adoc#token-propagation[Token Propagation] section.
For information about Authorization Code Flow access token propagation to downstream services, see the xref:security-openid-connect-client-reference.adoc#token-propagation-rest[Token Propagation] section.


== Integration considerations
Expand Down
30 changes: 6 additions & 24 deletions docs/src/main/asciidoc/security-openid-connect-client-reference.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ quarkus.oidc-client.grant.type=refresh

Then you can use the `OidcClient.refreshTokens` method with a provided refresh token to get the access token.

Using the `urn:ietf:params:oauth:grant-type:token-exchange` or `urn:ietf:params:oauth:grant-type:jwt-bearer` grants might be required if you are building a complex microservices application and want to avoid the same `Bearer` token be propagated to and used by more than one service. See <<token-propagation-reactive,Token Propagation in MicroProfile RestClient Reactive filter>> and <<token-propagation,Token Propagation in MicroProfile RestClient filter>> for more details.
Using the `urn:ietf:params:oauth:grant-type:token-exchange` or `urn:ietf:params:oauth:grant-type:jwt-bearer` grants might be required if you are building a complex microservices application and want to avoid the same `Bearer` token be propagated to and used by more than one service. See <<token-propagation-rest,Token Propagation for Quarkus REST>> and <<token-propagation-resteasy,Token Propagation for RESTEasy Classic>> for more details.

Using `OidcClient` to support the `authorization code` grant might be required if, for some reason, you cannot use the xref:security-oidc-code-flow-authentication.adoc[Quarkus OIDC extension] to support Authorization Code Flow. If there is a very good reason for you to implement Authorization Code Flow, then you can configure `OidcClient` as follows:

Check warning on line 136 in docs/src/main/asciidoc/security-openid-connect-client-reference.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-openid-connect-client-reference.adoc", "range": {"start": {"line": 136, "column": 342}}}, "severity": "INFO"}

Expand Down Expand Up @@ -1138,10 +1138,10 @@ public class OidcRequestCustomizer implements OidcRequestFilter {
}
----

[[token-propagation-reactive]]
== Token Propagation Reactive
[[token-propagation-rest]]
== Token Propagation for Quarkus REST

Check warning on line 1142 in docs/src/main/asciidoc/security-openid-connect-client-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Token Propagation for Quarkus REST'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Token Propagation for Quarkus REST'.", "location": {"path": "docs/src/main/asciidoc/security-openid-connect-client-reference.adoc", "range": {"start": {"line": 1142, "column": 4}}}, "severity": "INFO"}

The `quarkus-rest-client-oidc-token-propagation` extension provides a REST Client, `io.quarkus.oidc.token.propagation.reactive.AccessTokenRequestReactiveFilter`, that simplifies the propagation of authentication information. This client propagates the xref:security-oidc-bearer-token-authentication.adoc[bearer token] present in the currently active request or the token acquired from the xref:security-oidc-code-flow-authentication.adoc[authorization code flow mechanism] as the HTTP `Authorization` header's `Bearer` scheme value.
The `quarkus-rest-client-oidc-token-propagation` extension provides a REST Client filter, `io.quarkus.oidc.token.propagation.reactive.AccessTokenRequestReactiveFilter`, that simplifies the propagation of authentication information. This client propagates the xref:security-oidc-bearer-token-authentication.adoc[bearer token] present in the currently active request or the token acquired from the xref:security-oidc-code-flow-authentication.adoc[authorization code flow mechanism] as the HTTP `Authorization` header's `Bearer` scheme value.

You can selectively register `AccessTokenRequestReactiveFilter` by using either `io.quarkus.oidc.token.propagation.AccessToken` or `org.eclipse.microprofile.rest.client.annotation.RegisterProvider` annotation, for example:

Expand Down Expand Up @@ -1214,8 +1214,8 @@ quarkus.resteasy-client-oidc-token-propagation.exchange-token=true

`AccessTokenRequestReactiveFilter` uses a default `OidcClient` by default. A named `OidcClient` can be selected with a `quarkus.rest-client-oidc-token-propagation.client-name` configuration property or with the `io.quarkus.oidc.token.propagation.AccessToken#exchangeTokenClient` annotation attribute.

[[token-propagation]]
== Token Propagation
[[token-propagation-resteasy]]
== Token Propagation for RESTEasy Classic

The `quarkus-resteasy-client-oidc-token-propagation` extension provides two Jakarta REST `jakarta.ws.rs.client.ClientRequestFilter` class implementations that simplify the propagation of authentication information.
`io.quarkus.oidc.token.propagation.AccessTokenRequestFilter` propagates the xref:security-oidc-bearer-token-authentication.adoc[Bearer token] present in the current active request or the token acquired from the xref:security-oidc-code-flow-authentication.adoc[Authorization code flow mechanism], as the HTTP `Authorization` header's `Bearer` scheme value.
Expand Down Expand Up @@ -1369,24 +1369,6 @@ As mentioned, use `AccessTokenRequestFilter` if you work with Keycloak or an Ope
You can generate the tokens as described in xref:security-oidc-bearer-token-authentication.adoc#bearer-token-integration-testing[OpenID Connect Bearer Token Integration testing] section.
Prepare the REST test endpoints. You can have the test front-end endpoint, which uses the injected MP REST client with a registered token propagation filter, call the downstream endpoint. For example, see the `integration-tests/resteasy-client-oidc-token-propagation` in the `main` Quarkus repository.

[[reactive-token-propagation]]
== Token Propagation Reactive

Add the following Maven Dependency:

[source,xml]
----
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest-client-oidc-token-propagation</artifactId>
</dependency>
----

The `quarkus-rest-client-oidc-token-propagation` extension provides `io.quarkus.oidc.token.propagation.reactive.AccessTokenRequestReactiveFilter` which can be used to propagate the current `Bearer` or `Authorization Code Flow` access tokens.

The `quarkus-rest-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.

ifndef::no-quarkus-oidc-client-graphql[]
[[quarkus-oidc-client-graphql]]
== GraphQL client integration
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/security-openid-connect-providers.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -584,7 +584,7 @@ As mentioned in the xref:security-oidc-code-flow-authentication.adoc[OIDC code f
It is this access token that has to be propagated to services such as `Google Calendar`, or `Spotify Playlists` for the currently authenticated user to be able to use such services.

You do not have to bring provider-specific libraries in order to achieve this, but instead you can use a reactive `Token Propagation` filter, which can be bound to a given REST client with a simple annotation.

Check warning on line 586 in docs/src/main/asciidoc/security-openid-connect-providers.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.

Raw Output:
{"message": "[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "docs/src/main/asciidoc/security-openid-connect-providers.adoc", "range": {"start": {"line": 586, "column": 1}}}, "severity": "INFO"}

Check warning on line 586 in docs/src/main/asciidoc/security-openid-connect-providers.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'to' rather than 'in order to' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'to' rather than 'in order to' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/security-openid-connect-providers.adoc", "range": {"start": {"line": 586, "column": 54}}}, "severity": "WARNING"}

Check warning on line 586 in docs/src/main/asciidoc/security-openid-connect-providers.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'in order to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'in order to'.", "location": {"path": "docs/src/main/asciidoc/security-openid-connect-providers.adoc", "range": {"start": {"line": 586, "column": 54}}}, "severity": "INFO"}
For more information, see the Quarkus xref:security-openid-connect-client-reference.adoc#token-propagation-reactive[Access token propagation] guide.
For more information, see the Quarkus xref:security-openid-connect-client-reference.adoc#token-propagation-rest[Access token propagation] guide.

For example, after you have configured the <<google>> provider, you can have events added to the user's Google Calendar by using a REST client as shown in the following example:

Expand Down

4 comments on commit 141e84a

@dhoffer
Copy link

@dhoffer dhoffer commented on 141e84a Sep 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The title of this commit is concerning me. 'Avoid using Reactive for Quarkus REST in security doc' We are in the process of updating our apps to latest Quarkus and are switching to the Reactive REST. My understanding is that is what is recommended by Quarkus but this commit title seems to imply the opposite. Can someone clarify this?

@gsmet
Copy link
Member Author

@gsmet gsmet commented on 141e84a Sep 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it's about avoiding using "Reactive" naming because we rebranded it to Quarkus REST. It's about consistency. Quarkus REST (formerly RESTEasy Reactive) is our default REST stack and is what we recommend.

@gsmet
Copy link
Member Author

@gsmet gsmet commented on 141e84a Sep 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dhoffer ^ (not sure you will get the notification if I don't ping you)

@dhoffer
Copy link

@dhoffer dhoffer commented on 141e84a Sep 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perfect, thanks for clarifying.

Please sign in to comment.