Chapter 8. OpenID Connect client and token propagation quickstart
Learn how to use OpenID Connect (OIDC) and OAuth2 clients with filters to get, refresh, and propagate access tokens in your applications.
This approach uses an OIDC token propagation Reactive filter to propagate the incoming bearer access tokens.
For more information about OIDC Client
and Token Propagation
support in Quarkus, see the OpenID Connect (OIDC) and OAuth2 client and filters reference guide.
To protect your applications by using Bearer Token Authorization, see the OpenID Connect (OIDC) Bearer token authentication guide.
8.1. Prerequisites
To complete this guide, you need:
- Roughly 15 minutes
- An IDE
-
JDK 17+ installed with
JAVA_HOME
configured appropriately - Apache Maven 3.9.6
- A working container runtime (Docker or Podman)
- Optionally the Quarkus CLI if you want to use it
- Optionally Mandrel or GraalVM installed and configured appropriately if you want to build a native executable (or Docker if you use a native container build)
- jq tool
8.2. Architecture
In this example, an application is built with two Jakarta REST resources, FrontendResource
and ProtectedResource
. Here, FrontendResource
uses one of two methods to propagate access tokens to ProtectedResource
:
- It can get a token by using an OIDC token propagation Reactive filter before propagating it.
- It can use an OIDC token propagation Reactive filter to propagate the incoming access token.
FrontendResource
has four endpoints:
-
/frontend/user-name-with-oidc-client-token
-
/frontend/admin-name-with-oidc-client-token
-
/frontend/user-name-with-propagated-token
-
/frontend/admin-name-with-propagated-token
FrontendResource
uses a REST Client with an OIDC token propagation Reactive filter to get and propagate an access token to ProtectedResource
when either /frontend/user-name-with-oidc-client-token
or /frontend/admin-name-with-oidc-client-token
is called. Also, FrontendResource
uses a REST Client with OpenID Connect Token Propagation Reactive Filter
to propagate the current incoming access token to ProtectedResource
when either /frontend/user-name-with-propagated-token
or /frontend/admin-name-with-propagated-token
is called.
ProtectedResource
has two endpoints:
-
/protected/user-name
-
/protected/admin-name
Both endpoints return the username extracted from the incoming access token, which was propagated to ProtectedResource
from FrontendResource
. The only difference between these endpoints is that calling /protected/user-name
is only allowed if the current access token has a user
role, and calling /protected/admin-name
is only allowed if the current access token has an admin
role.
8.3. Solution
We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.
Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git -b 3.8
, or download an archive.
The solution is in the security-openid-connect-client-quickstart
directory.
8.4. Creating the Maven project
First, you need a new project. Create a new project with the following command:
Using the Quarkus CLI:
quarkus create app org.acme:security-openid-connect-client-quickstart \ --extension='oidc,oidc-client-reactive-filter,oidc-token-propagation-reactive,resteasy-reactive' \ --no-code cd security-openid-connect-client-quickstart
To create a Gradle project, add the
--gradle
or--gradle-kotlin-dsl
option.For more information about how to install and use the Quarkus CLI, see the Quarkus CLI guide.
Using Maven:
mvn io.quarkus.platform:quarkus-maven-plugin:3.8.5:create \ -DprojectGroupId=org.acme \ -DprojectArtifactId=security-openid-connect-client-quickstart \ -Dextensions='oidc,oidc-client-reactive-filter,oidc-token-propagation-reactive,resteasy-reactive' \ -DnoCode cd security-openid-connect-client-quickstart
To create a Gradle project, add the
-DbuildTool=gradle
or-DbuildTool=gradle-kotlin-dsl
option.
For Windows users:
-
If using cmd, (don’t use backward slash
\
and put everything on the same line) -
If using Powershell, wrap
-D
parameters in double quotes e.g."-DprojectArtifactId=security-openid-connect-client-quickstart"
This command generates a Maven project, importing the oidc
, oidc-client-reactive-filter
, oidc-token-propagation-reactive-filter
, and resteasy-reactive
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:
Using the Quarkus CLI:
quarkus extension add oidc,oidc-client-reactive-filter,oidc-token-propagation-reactive,resteasy-reactive
Using Maven:
./mvnw quarkus:add-extension -Dextensions='oidc,oidc-client-reactive-filter,oidc-token-propagation-reactive,resteasy-reactive'
Using Gradle:
./gradlew addExtension --extensions='oidc,oidc-client-reactive-filter,oidc-token-propagation-reactive,resteasy-reactive'
This command adds the following extensions to your build file:
Using Maven:
<dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-oidc</artifactId> </dependency> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-oidc-client-reactive-filter</artifactId> </dependency> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-oidc-token-propagation-reactive</artifactId> </dependency> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-resteasy-reactive</artifactId> </dependency>
Using Gradle:
implementation("io.quarkus:quarkus-oidc,oidc-client-reactive-filter,oidc-token-propagation-reactive,resteasy-reactive")
8.5. Writing the application
Start by implementing ProtectedResource
:
package org.acme.security.openid.connect.client; import jakarta.annotation.security.RolesAllowed; import jakarta.inject.Inject; import jakarta.ws.rs.GET; import jakarta.ws.rs.Path; import jakarta.ws.rs.Produces; import io.quarkus.security.Authenticated; import io.smallrye.mutiny.Uni; import org.eclipse.microprofile.jwt.JsonWebToken; @Path("/protected") @Authenticated public class ProtectedResource { @Inject JsonWebToken principal; @GET @RolesAllowed("user") @Produces("text/plain") @Path("userName") public Uni<String> userName() { return Uni.createFrom().item(principal.getName()); } @GET @RolesAllowed("admin") @Produces("text/plain") @Path("adminName") public Uni<String> adminName() { return Uni.createFrom().item(principal.getName()); } }
ProtectedResource
returns a name from both userName()
and adminName()
methods. The name is extracted from the current JsonWebToken
.
Next, add two REST clients, OidcClientRequestReactiveFilter
and AccessTokenRequestReactiveFilter
, which FrontendResource
uses to call ProtectedResource
.
Add the OidcClientRequestReactiveFilter
REST Client:
package org.acme.security.openid.connect.client; import jakarta.ws.rs.GET; import jakarta.ws.rs.Path; import jakarta.ws.rs.Produces; import org.eclipse.microprofile.rest.client.annotation.RegisterProvider; import org.eclipse.microprofile.rest.client.inject.RegisterRestClient; import io.quarkus.oidc.client.reactive.filter.OidcClientRequestReactiveFilter; import io.smallrye.mutiny.Uni; @RegisterRestClient @RegisterProvider(OidcClientRequestReactiveFilter.class) @Path("/") public interface RestClientWithOidcClientFilter { @GET @Produces("text/plain") @Path("userName") Uni<String> getUserName(); @GET @Produces("text/plain") @Path("adminName") Uni<String> getAdminName(); }
The RestClientWithOidcClientFilter
interface depends on OidcClientRequestReactiveFilter
to get and propagate the tokens.
Add the AccessTokenRequestReactiveFilter
REST Client:
package org.acme.security.openid.connect.client; import jakarta.ws.rs.GET; import jakarta.ws.rs.Path; import jakarta.ws.rs.Produces; import org.eclipse.microprofile.rest.client.annotation.RegisterProvider; import org.eclipse.microprofile.rest.client.inject.RegisterRestClient; import io.quarkus.oidc.token.propagation.reactive.AccessTokenRequestReactiveFilter; import io.smallrye.mutiny.Uni; @RegisterRestClient @RegisterProvider(AccessTokenRequestReactiveFilter.class) @Path("/") public interface RestClientWithTokenPropagationFilter { @GET @Produces("text/plain") @Path("userName") Uni<String> getUserName(); @GET @Produces("text/plain") @Path("adminName") Uni<String> getAdminName(); }
The RestClientWithTokenPropagationFilter
interface depends on AccessTokenRequestReactiveFilter
to propagate the incoming already-existing tokens.
Note that both RestClientWithOidcClientFilter
and RestClientWithTokenPropagationFilter
interfaces are the same. This is because combining OidcClientRequestReactiveFilter
and AccessTokenRequestReactiveFilter
on the same REST Client causes side effects because both filters can interfere with each other. For example, OidcClientRequestReactiveFilter
can override the token propagated by AccessTokenRequestReactiveFilter
, or AccessTokenRequestReactiveFilter
can fail if it is called when no token is available to propagate and OidcClientRequestReactiveFilter
is expected to get a new token instead.
Now, finish creating the application by adding FrontendResource
:
package org.acme.security.openid.connect.client; import jakarta.inject.Inject; import jakarta.ws.rs.GET; import jakarta.ws.rs.Path; import jakarta.ws.rs.Produces; import org.eclipse.microprofile.rest.client.inject.RestClient; import io.smallrye.mutiny.Uni; @Path("/frontend") public class FrontendResource { @Inject @RestClient RestClientWithOidcClientFilter restClientWithOidcClientFilter; @Inject @RestClient RestClientWithTokenPropagationFilter restClientWithTokenPropagationFilter; @GET @Path("user-name-with-oidc-client-token") @Produces("text/plain") public Uni<String> getUserNameWithOidcClientToken() { return restClientWithOidcClientFilter.getUserName(); } @GET @Path("admin-name-with-oidc-client-token") @Produces("text/plain") public Uni<String> getAdminNameWithOidcClientToken() { return restClientWithOidcClientFilter.getAdminName(); } @GET @Path("user-name-with-propagated-token") @Produces("text/plain") public Uni<String> getUserNameWithPropagatedToken() { return restClientWithTokenPropagationFilter.getUserName(); } @GET @Path("admin-name-with-propagated-token") @Produces("text/plain") public Uni<String> getAdminNameWithPropagatedToken() { return restClientWithTokenPropagationFilter.getAdminName(); } }
FrontendResource
uses REST Client with an OIDC token propagation Reactive filter to get and propagate an access token to ProtectedResource
when either /frontend/user-name-with-oidc-client-token
or /frontend/admin-name-with-oidc-client-token
is called. Also, FrontendResource
uses REST Client with OpenID Connect Token Propagation Reactive Filter
to propagate the current incoming access token to ProtectedResource
when either /frontend/user-name-with-propagated-token
or /frontend/admin-name-with-propagated-token
is called.
Finally, add a Jakarta REST ExceptionMapper
:
package org.acme.security.openid.connect.client; import jakarta.ws.rs.core.Response; import jakarta.ws.rs.ext.ExceptionMapper; import jakarta.ws.rs.ext.Provider; import org.jboss.resteasy.reactive.ClientWebApplicationException; @Provider public class FrontendExceptionMapper implements ExceptionMapper<ClientWebApplicationException> { @Override public Response toResponse(ClientWebApplicationException t) { return Response.status(t.getResponse().getStatus()).build(); } }
This exception mapper is only added to verify during the tests that ProtectedResource
returns 403
when the token has no expected role. Without this mapper, RESTEasy Reactive
would correctly convert the exceptions that escape from REST Client calls to 500
to avoid leaking the information from the downstream resources such as ProtectedResource
. However, in the tests, it would not be possible to assert that 500
is caused by an authorization exception instead of some internal error.
8.6. Configuring the application
Having prepared the code, you configure the application:
# Configure OIDC %prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus quarkus.oidc.client-id=backend-service quarkus.oidc.credentials.secret=secret # Tell Dev Services for Keycloak to import the realm file # This property is ineffective when running the application in JVM or Native modes but only in dev and test modes. quarkus.keycloak.devservices.realm-path=quarkus-realm.json # Configure OIDC Client quarkus.oidc-client.auth-server-url=${quarkus.oidc.auth-server-url} quarkus.oidc-client.client-id=${quarkus.oidc.client-id} quarkus.oidc-client.credentials.secret=${quarkus.oidc.credentials.secret} quarkus.oidc-client.grant.type=password quarkus.oidc-client.grant-options.password.username=alice quarkus.oidc-client.grant-options.password.password=alice # Configure REST clients %prod.port=8080 %dev.port=8080 %test.port=8081 org.acme.security.openid.connect.client.RestClientWithOidcClientFilter/mp-rest/url=http://localhost:${port}/protected org.acme.security.openid.connect.client.RestClientWithTokenPropagationFilter/mp-rest/url=http://localhost:${port}/protected
This configuration references Keycloak, which is used by ProtectedResource
to verify the incoming access tokens and by OidcClient
to get the tokens for a user alice
by using a password
grant. Both REST clients point to `ProtectedResource’s HTTP address.
Adding a %prod.
profile prefix to quarkus.oidc.auth-server-url
ensures that Dev Services for Keycloak
launches a container for you when the application is run in dev or test modes. For more information, see the Running the application in dev mode section.
8.7. Starting and configuring the Keycloak server
Do not start the Keycloak server when you run the application in dev or test modes; Dev Services for Keycloak
launches a container. For more information, see the Running the application in dev mode section. Ensure you put the realm configuration file on the classpath, in the target/classes
directory. This placement ensures that the file is automatically imported in dev mode. However, if you have already built a complete solution, you do not need to add the realm file to the classpath because the build process has already done so.
To start a Keycloak Server, you can use Docker and just run the following command:
docker run --name keycloak -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -p 8180:8080 quay.io/keycloak/keycloak:{keycloak.version} start-dev
Set {keycloak.version}
to 24.0.0
or later.
You can access your Keycloak Server at localhost:8180.
Log in as the admin
user to access the Keycloak Administration Console. The password is admin
.
Import the realm configuration file to create a new realm. For more details, see the Keycloak documentation about how to create a new realm.
This quarkus
realm file adds a frontend
client, and alice
and admin
users. alice
has a user
role. admin
has both user
and admin
roles.
8.8. Running the application in dev mode
To run the application in a dev mode, use:
Using the Quarkus CLI:
quarkus dev
Using Maven:
./mvnw quarkus:dev
Using Gradle:
./gradlew --console=plain quarkusDev
Dev Services for Keycloak launches a Keycloak container and imports quarkus-realm.json
.
Open a Dev UI available at /q/dev-ui and click a Provider: Keycloak
link in the OpenID Connect Dev UI card.
When asked, log in to a Single Page Application
provided by the OpenID Connect Dev UI:
Log in as
alice
, with the password,alice
. This user has auser
role.-
Access
/frontend/user-name-with-propagated-token
, which returns200
. -
Access
/frontend/admin-name-with-propagated-token
, which returns403
.
-
Access
Log out and back in as
admin
with the password,admin
. This user has bothadmin
anduser
roles.-
Access
/frontend/user-name-with-propagated-token
, which returns200
. -
Access
/frontend/admin-name-with-propagated-token
, which returns200
.
-
Access
In this case, you are testing that FrontendResource
can propagate the access tokens from the OpenID Connect Dev UI.
8.9. Running the application in JVM mode
After exploring the application in dev mode, you can run it as a standard Java application.
First, compile it:
Using the Quarkus CLI:
quarkus build
Using Maven:
./mvnw install
Using Gradle:
./gradlew build
Then, run it:
java -jar target/quarkus-app/quarkus-run.jar
8.10. Running the application in native mode
You can compile this demo into native code; no modifications are required.
This implies that you no longer need to install a JVM on your production environment, as the runtime technology is included in the produced binary and optimized to run with minimal resources.
Compilation takes longer, so this step is turned off by default. To build again, enable the native
profile:
Using the Quarkus CLI:
quarkus build --native
Using Maven:
./mvnw install -Dnative
Using Gradle:
./gradlew build -Dquarkus.package.type=native
After a little while, when the build finishes, you can run the native binary directly:
./target/security-openid-connect-quickstart-1.0.0-SNAPSHOT-runner
8.11. Testing the application
For more information about testing your application in dev mode, see the preceding Running the application in dev mode section.
You can test the application launched in JVM or Native modes with curl
.
Obtain an access token for alice
:
export access_token=$(\ curl --insecure -X POST http://localhost:8180/realms/quarkus/protocol/openid-connect/token \ --user backend-service:secret \ -H 'content-type: application/x-www-form-urlencoded' \ -d 'username=alice&password=alice&grant_type=password' | jq --raw-output '.access_token' \ )
Now, use this token to call /frontend/user-name-with-propagated-token
and /frontend/admin-name-with-propagated-token
:
curl -i -X GET \ http://localhost:8080/frontend/user-name-with-propagated-token \ -H "Authorization: Bearer "$access_token
This command returns the 200
status code and the name alice
.
curl -i -X GET \ http://localhost:8080/frontend/admin-name-with-propagated-token \ -H "Authorization: Bearer "$access_token
In contrast, this command returns 403
. Recall that alice
only has a user
role.
Next, obtain an access token for admin
:
export access_token=$(\ curl --insecure -X POST http://localhost:8180/realms/quarkus/protocol/openid-connect/token \ --user backend-service:secret \ -H 'content-type: application/x-www-form-urlencoded' \ -d 'username=admin&password=admin&grant_type=password' | jq --raw-output '.access_token' \ )
Use this token to call /frontend/user-name-with-propagated-token
:
curl -i -X GET \ http://localhost:8080/frontend/user-name-with-propagated-token \ -H "Authorization: Bearer "$access_token
This command returns a 200
status code and the name admin
.
Now, use this token to call /frontend/admin-name-with-propagated-token
:
curl -i -X GET \ http://localhost:8080/frontend/admin-name-with-propagated-token \ -H "Authorization: Bearer "$access_token
This command also returns the 200
status code and the name admin
because admin
has both user
and admin
roles.
Now, check the FrontendResource
methods, which do not propagate the existing tokens but use OidcClient
to get and propagate the tokens. As already shown, OidcClient
is configured to get the tokens for the alice
user, so:
curl -i -X GET \ http://localhost:8080/frontend/user-name-with-oidc-client-token
This command returns the 200
status code and the name alice
.
curl -i -X GET \ http://localhost:8080/frontend/admin-name-with-oidc-client-token
In contrast with the preceding command, this command returns a 403
status code.