Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update content for support of quarkus-oidc-token-propagation-(reactive) extensions #41938

Merged
merged 1 commit into from
Jul 17, 2024
Merged

Update content for support of quarkus-oidc-token-propagation-(reactive) extensions #41938

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions docs/src/main/asciidoc/security-authentication-mechanisms.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -399,17 +399,15 @@

[IMPORTANT]
====
In this scenario, you do not need to protect your Quarkus endpoint by using the Quarkus OpenID Connect adapter.

Check warning on line 402 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": 402, "column": 30}}}, "severity": "INFO"}
====

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]]
Expand Down
11 changes: 0 additions & 11 deletions docs/src/main/asciidoc/security-openid-connect-client-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,9 @@

- Using `quarkus-oidc-client`, `quarkus-rest-client-oidc-filter` and `quarkus-resteasy-client-oidc-filter` extensions to acquire and refresh access tokens from OpenID Connect and OAuth 2.0 compliant Authorization Servers such as link:https://www.keycloak.org[Keycloak].

ifndef::no-quarkus-oidc-token-propagation[]

- Using `quarkus-rest-client-oidc-token-propagation` and `quarkus-resteasy-client-oidc-token-propagation` extensions to propagate the current `Bearer` or `Authorization Code Flow` access tokens.
endif::no-quarkus-oidc-token-propagation[]

The access tokens managed by these extensions can be used as HTTP Authorization Bearer tokens to access the remote services.

Check warning on line 21 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": 21, "column": 59}}}, "severity": "INFO"}

Also see xref:security-openid-connect-client.adoc[OpenID Connect client and token propagation quickstart].

Expand Down Expand Up @@ -1106,9 +1103,8 @@
}
----

ifndef::no-quarkus-oidc-token-propagation-reactive[]
[[token-propagation-reactive]]
== Token Propagation Reactive

Check warning on line 1107 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 Reactive'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Token Propagation Reactive'.", "location": {"path": "docs/src/main/asciidoc/security-openid-connect-client-reference.adoc", "range": {"start": {"line": 1107, "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.

Expand Down Expand Up @@ -1182,11 +1178,9 @@
----

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

ifndef::no-quarkus-oidc-token-propagation[]
[[token-propagation]]
== Token Propagation

Check warning on line 1183 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'.

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

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 All @@ -1196,12 +1190,11 @@

However, the direct end-to-end Bearer token propagation should be avoided. For example, `Client -> Service A -> Service B` where `Service B` receives a token sent by `Client` to `Service A`. In such cases, `Service B` cannot distinguish if the token came from `Service A` or from `Client` directly. For `Service B` to verify the token came from `Service A`, it should be able to assert a new issuer and audience claims.

Additionally, a complex application might need to exchange or update the tokens before propagating them. For example, the access context might be different when `Service A` is accessing `Service B`. In this case, `Service A` might be granted a narrow or completely different set of scopes to access `Service B`.

Check warning on line 1193 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.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-openid-connect-client-reference.adoc", "range": {"start": {"line": 1193, "column": 43}}}, "severity": "INFO"}

The following sections show how `AccessTokenRequestFilter` and `JsonWebTokenRequestFilter` can help.
endif::no-quarkus-oidc-token-propagation[]

=== RestClient AccessTokenRequestFilter

Check warning on line 1197 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 'RestClient AccessTokenRequestFilter'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'RestClient AccessTokenRequestFilter'.", "location": {"path": "docs/src/main/asciidoc/security-openid-connect-client-reference.adoc", "range": {"start": {"line": 1197, "column": 5}}}, "severity": "INFO"}

`AccessTokenRequestFilter` treats all tokens as Strings, and as such, it can work with both JWT and opaque tokens.

Expand Down Expand Up @@ -1341,9 +1334,8 @@
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.

ifndef::no-quarkus-oidc-token-propagation[]
[[reactive-token-propagation]]
== Token Propagation Reactive

Check warning on line 1338 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 Reactive'.

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

Add the following Maven Dependency:

Expand All @@ -1359,7 +1351,6 @@

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.
endif::no-quarkus-oidc-token-propagation[]

ifndef::no-quarkus-oidc-client-graphql[]
[[quarkus-oidc-client-graphql]]
Expand Down Expand Up @@ -1426,11 +1417,9 @@

include::{generated-dir}/config/quarkus-oidc-client.adoc[opts=optional, leveloffset=+1]

ifndef::no-quarkus-oidc-token-propagation-reactive[]
=== OIDC token propagation

include::{generated-dir}/config/quarkus-oidc-token-propagation-reactive.adoc[opts=optional, leveloffset=+1]
endif::no-quarkus-oidc-token-propagation-reactive[]

== References

Expand Down
46 changes: 0 additions & 46 deletions docs/src/main/asciidoc/security-openid-connect-client.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,6 @@
First, you need a new project.
Create a new project with the following command:

ifndef::no-quarkus-oidc-token-propagation[]
:create-app-artifact-id: security-openid-connect-client-quickstart
:create-app-extensions: oidc,rest-client-oidc-filter,rest-client-oidc-token-propagation,rest
include::{includes}/devtools/create-app.adoc[]
Expand All @@ -79,24 +78,9 @@

:add-extension-extensions: oidc,rest-client-oidc-filter,rest-client-oidc-token-propagation,rest
include::{includes}/devtools/extension-add.adoc[]
endif::no-quarkus-oidc-token-propagation[]

ifdef::no-quarkus-oidc-token-propagation[]
:create-app-artifact-id: security-openid-connect-client-quickstart
:create-app-extensions: oidc,rest-client-oidc-filter,rest
include::{includes}/devtools/create-app.adoc[]

It generates a Maven project, importing the `oidc`, `rest-client-oidc-filter`, and `rest` extensions.

If you already have your Quarkus project configured, you can add these extensions to your project by running the following command in your project base directory:

:add-extension-extensions: oidc,rest-client-oidc-filter,rest
include::{includes}/devtools/extension-add.adoc[]
endif::no-quarkus-oidc-token-propagation[]

It adds the following extensions to your build file:

ifndef::no-quarkus-oidc-token-propagation[]
[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
Expand All @@ -123,32 +107,6 @@
----
implementation("io.quarkus:quarkus-oidc,rest-client-oidc-filter,rest-client-oidc-token-propagation,rest")
----
endif::no-quarkus-oidc-token-propagation[]

ifdef::no-quarkus-oidc-token-propagation[]
[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-oidc</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest-client-oidc-filter</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest</artifactId>
</dependency>
----

[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
.build.gradle
----
implementation("io.quarkus:quarkus-oidc,rest-client-oidc-filter,rest")
----
endif::no-quarkus-oidc-token-propagation[]

== Writing the application

Expand Down Expand Up @@ -200,10 +158,8 @@
Next, add the following REST clients:

1. `RestClientWithOidcClientFilter`, which uses an OIDC client filter provided by the `quarkus-rest-client-oidc-filter` extension to get and propagate an access token.
2. `RestClientWithTokenHeaderParam`, which accepts a token already acquired by the programmatically created OidcClient as an HTTP `Authorization` header value.

Check warning on line 161 in docs/src/main/asciidoc/security-openid-connect-client.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.adoc", "range": {"start": {"line": 161, "column": 120}}}, "severity": "INFO"}
ifndef::no-quarkus-oidc-token-propagation[]
3. `RestClientWithTokenPropagationFilter`, which uses an OIDC token propagation filter provided by the `quarkus-rest-client-oidc-token-propagation` extension to get and propagate an access token.
endif::no-quarkus-oidc-token-propagation[]

Add the `RestClientWithOidcClientFilter` REST client:

Expand Down Expand Up @@ -268,9 +224,8 @@
Uni<String> getAdminName(@HeaderParam("Authorization") String authorization); <1>
}
----
<1> `RestClientWithTokenHeaderParam` REST client expects that the tokens will be passed to it as HTTP `Authorization` header values.

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

ifndef::no-quarkus-oidc-token-propagation[]
Add the `RestClientWithTokenPropagationFilter` REST client:

[source,java]
Expand Down Expand Up @@ -308,7 +263,6 @@

IMPORTANT: Do not use the `RestClientWithOidcClientFilter` and `RestClientWithTokenPropagationFilter` interfaces in the same REST client because they can conflict, leading to issues.
For example, the OIDC client filter can override the token from the OIDC token propagation filter, or the propagation filter might not work correctly if it attempts to propagate a token when none is available, expecting the OIDC client filter to obtain a new token instead.
endif::no-quarkus-oidc-token-propagation[]


Also, add `OidcClientCreator` to create an OIDC client programmatically at startup. `OidcClientCreator` supports `RestClientWithTokenHeaderParam` REST client calls:
Expand Down