Microprofile JSON Web Token (JWT) authentication

Red Hat build of Quarkus 3.27

Red Hat Customer Content Services

Abstract

This guide explores the fundamentals of JSON Web Token (JWT) security, focusing on secure token generation, storage, and validation mechanisms. It delves into JWT integration within application architectures and provides practical steps to implement secure builds and deployment pipelines for token-based authentication systems.

Chapter 1. Using JWT RBAC
Copy link

This guide explains how to integrate SmallRye JWT into your Quarkus application to implement JSON Web Token (JWT) security in compliance with the MicroProfile JWT specification. You’ll learn how to verify JWTs, represent them as MicroProfile JWT org.eclipse.microprofile.jwt.JsonWebToken, and secure Quarkus HTTP endpoints using bearer token authorization and Role-Based Access Control.

Note

The Quarkus OpenID Connect (quarkus-oidc) extension also supports bearer token authorization and uses smallrye-jwt to represent bearer tokens as JsonWebToken. For details, see the OIDC Bearer Token Authentication guide.

If your Quarkus application needs to authenticate users using the OIDC Authorization Code Flow, you must use the OpenID Connect extension. For more information, refer to the OIDC Code Flow Mechanism for Protecting Web Applications.

1.1. Prerequisites
Copy link

To complete this guide, you need:

Roughly 15 minutes
An IDE
JDK 17+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.6 or later
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)

1.2. Quickstart
Copy link

1.2.1. Solution
Copy link

We recommend following the instructions in the upcoming sections to create the application step by step. If you prefer, you can skip ahead to the completed example.

To access the example, either clone the Git repository or download an archive:

Clone the repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git -b 3.27.
Download the archive.

The completed solution is located in the security-jwt-quickstart directory.

1.2.2. Creating the Maven project
Copy link

First, create a new project with the following command:

Using the Quarkus CLI:

quarkus create app org.acme:security-jwt-quickstart \
    --extension='rest-jackson,smallrye-jwt,smallrye-jwt-build' \
    --no-code
cd security-jwt-quickstart

quarkus create app org.acme:security-jwt-quickstart \
    --extension='rest-jackson,smallrye-jwt,smallrye-jwt-build' \
    --no-code
cd security-jwt-quickstart

Copy to Clipboard

Toggle word wrap

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 com.redhat.quarkus.platform:quarkus-maven-plugin:3.27.1:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-jwt-quickstart \
    -Dextensions='rest-jackson,smallrye-jwt,smallrye-jwt-build' \
    -DnoCode
cd security-jwt-quickstart

mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.27.1:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-jwt-quickstart \
    -Dextensions='rest-jackson,smallrye-jwt,smallrye-jwt-build' \
    -DnoCode
cd security-jwt-quickstart

Copy to Clipboard

Toggle word wrap

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-jwt-quickstart"

This command generates the Maven project and imports the smallrye-jwt extension, which includes the MicroProfile JWT RBAC support.

If you already have your Quarkus project configured, you can add the smallrye-jwt extension to your project by running the following command in your project base directory:

Using the Quarkus CLI:

quarkus extension add smallrye-jwt,smallrye-jwt-build

quarkus extension add smallrye-jwt,smallrye-jwt-build

Copy to Clipboard

Toggle word wrap

Using Maven:

./mvnw quarkus:add-extension -Dextensions='smallrye-jwt,smallrye-jwt-build'

./mvnw quarkus:add-extension -Dextensions='smallrye-jwt,smallrye-jwt-build'

Copy to Clipboard

Toggle word wrap

Using Gradle:

./gradlew addExtension --extensions='smallrye-jwt,smallrye-jwt-build'

./gradlew addExtension --extensions='smallrye-jwt,smallrye-jwt-build'

Copy to Clipboard

Toggle word wrap

This command adds the following dependencies to your build file:

Using Maven:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-jwt</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-jwt-build</artifactId>
</dependency>

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-jwt</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-jwt-build</artifactId>
</dependency>

Copy to Clipboard

Toggle word wrap

Using Gradle:

implementation("io.quarkus:quarkus-smallrye-jwt")
implementation("io.quarkus:quarkus-smallrye-jwt-build")

implementation("io.quarkus:quarkus-smallrye-jwt")
implementation("io.quarkus:quarkus-smallrye-jwt-build")

Copy to Clipboard

Toggle word wrap

1.2.3. Examine the Jakarta REST resource
Copy link

Create a REST endpoint in src/main/java/org/acme/security/jwt/TokenSecuredResource.java with the following content:

REST endpoint V1

package org.acme.security.jwt;

import jakarta.annotation.security.PermitAll;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.InternalServerErrorException;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.SecurityContext;

import org.eclipse.microprofile.jwt.JsonWebToken;

@Path("/secured")
public class TokenSecuredResource {

    @Inject
    JsonWebToken jwt; 

    @GET
    @Path("permit-all")
    @PermitAll 
    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@Context SecurityContext ctx) {
        return getResponseString(ctx); 
    }

    private String getResponseString(SecurityContext ctx) {
        String name;
        if (ctx.getUserPrincipal() == null) { 
            name = "anonymous";
        } else if (!ctx.getUserPrincipal().getName().equals(jwt.getName())) { 
            throw new InternalServerErrorException("Principal and JsonWebToken names do not match");
        } else {
            name = ctx.getUserPrincipal().getName(); 
        }
        return String.format("hello %s,"
            + " isHttps: %s,"
            + " authScheme: %s,"
            + " hasJWT: %s",
            name, ctx.isSecure(), ctx.getAuthenticationScheme(), hasJwt()); 
    }

    private boolean hasJwt() {
        return jwt.getClaimNames() != null;
    }
}

package org.acme.security.jwt;

import jakarta.annotation.security.PermitAll;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.InternalServerErrorException;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.SecurityContext;

import org.eclipse.microprofile.jwt.JsonWebToken;

@Path("/secured")
public class TokenSecuredResource {

    @Inject
    JsonWebToken jwt;



    @GET
    @Path("permit-all")
    @PermitAll


    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@Context SecurityContext ctx) {
        return getResponseString(ctx);


    }

    private String getResponseString(SecurityContext ctx) {
        String name;
        if (ctx.getUserPrincipal() == null) {


            name = "anonymous";
        } else if (!ctx.getUserPrincipal().getName().equals(jwt.getName())) {


            throw new InternalServerErrorException("Principal and JsonWebToken names do not match");
        } else {
            name = ctx.getUserPrincipal().getName();


        }
        return String.format("hello %s,"
            + " isHttps: %s,"
            + " authScheme: %s,"
            + " hasJWT: %s",
            name, ctx.isSecure(), ctx.getAuthenticationScheme(), hasJwt());


    }

    private boolean hasJwt() {
        return jwt.getClaimNames() != null;
    }
}

Copy to Clipboard

Toggle word wrap

1: The JsonWebToken interface is injected, providing access to claims associated with the current authenticated token. This interface extends java.security.Principal.
2: The @PermitAll is a standard Jakarta security annotation. It indicates that the given endpoint is accessible by all callers, whether authenticated or not.
3: The Jakarta REST SecurityContext is injected to inspect the security state of the request. The getResponseString() function generates the response.
4: Checks if the call is insecure by checking if the request user/caller Principal against null.
5: Ensures the names in the Principal and JsonWebToken match because the JsonWebToken represents the current Principal.
6: Retrieves the name of the Principal.
7: Builds a response containing the caller’s name, the isSecure() and getAuthenticationScheme() states of the request SecurityContext, and whether a non-null JsonWebToken was injected.

1.2.4. Run the application in dev mode
Copy link

Now, you are ready to run the application in dev mode by using one of the following commands:

Using the Quarkus CLI:
```
quarkus dev
```
```
quarkus dev
```
Copy to Clipboard Toggle word wrap
Using Maven:
```
./mvnw quarkus:dev
```
```
./mvnw quarkus:dev
```
Copy to Clipboard Toggle word wrap

Using Gradle:

./gradlew --console=plain quarkusDev

./gradlew --console=plain quarkusDev

Copy to Clipboard

Toggle word wrap

Then, you should see output similar to the following example:

quarkus:dev output

[INFO] Scanning for projects...
[INFO]
[INFO] ----------------------< org.acme:security-jwt-quickstart >-----------------------
[INFO] Building security-jwt-quickstart 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
...
Listening for transport dt_socket at address: 5005
2020-07-15 16:09:50,883 INFO  [io.quarkus] (Quarkus Main Thread) security-jwt-quickstart 1.0.0-SNAPSHOT on JVM (powered by Quarkus 999-SNAPSHOT) started in 1.073s. Listening on: http://0.0.0.0:8080
2020-07-15 16:09:50,885 INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
2020-07-15 16:09:50,885 INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, mutiny, rest, rest-jackson, security, smallrye-context-propagation, smallrye-jwt, vertx, vertx-web]

[INFO] Scanning for projects...
[INFO]
[INFO] ----------------------< org.acme:security-jwt-quickstart >-----------------------
[INFO] Building security-jwt-quickstart 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
...
Listening for transport dt_socket at address: 5005
2020-07-15 16:09:50,883 INFO  [io.quarkus] (Quarkus Main Thread) security-jwt-quickstart 1.0.0-SNAPSHOT on JVM (powered by Quarkus 999-SNAPSHOT) started in 1.073s. Listening on: http://0.0.0.0:8080
2020-07-15 16:09:50,885 INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
2020-07-15 16:09:50,885 INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, mutiny, rest, rest-jackson, security, smallrye-context-propagation, smallrye-jwt, vertx, vertx-web]

Copy to Clipboard

Toggle word wrap

Now that the REST endpoint is running, you can access it by using a command line tool such as curl:

curl command for /secured/permit-all

curl http://127.0.0.1:8080/secured/permit-all; echo

$ curl http://127.0.0.1:8080/secured/permit-all; echo

Copy to Clipboard

Toggle word wrap

This command returns the following response:

hello anonymous, isHttps: false, authScheme: null, hasJWT: false

hello anonymous, isHttps: false, authScheme: null, hasJWT: false

Copy to Clipboard

Toggle word wrap

You have not provided any JWT in our request, so you would not expect the endpoint to see any security state, and the response is consistent with that:

username is anonymous.
isHttps is false because https is not used.
authScheme is null.
hasJWT is false.

Use Ctrl-C to stop the Quarkus server.

So now let’s actually secure something. Take a look at the new endpoint method helloRolesAllowed in the following:

REST endpoint V2

package org.acme.security.jwt;

import jakarta.annotation.security.PermitAll;
import jakarta.annotation.security.RolesAllowed;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.InternalServerErrorException;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.SecurityContext;

import org.eclipse.microprofile.jwt.JsonWebToken;

@Path("/secured")
public class TokenSecuredResource {

    @Inject
    JsonWebToken jwt; 

    @GET
    @Path("permit-all")
    @PermitAll
    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@Context SecurityContext ctx) {
        return getResponseString(ctx);
    }

    @GET
    @Path("roles-allowed") 
    @RolesAllowed({ "User", "Admin" }) 
    @Produces(MediaType.TEXT_PLAIN)
    public String helloRolesAllowed(@Context SecurityContext ctx) {
        return getResponseString(ctx) + ", birthdate: " + jwt.getClaim("birthdate").toString(); 
    }

    private String getResponseString(SecurityContext ctx) {
        String name;
        if (ctx.getUserPrincipal() == null) {
            name = "anonymous";
        } else if (!ctx.getUserPrincipal().getName().equals(jwt.getName())) {
            throw new InternalServerErrorException("Principal and JsonWebToken names do not match");
        } else {
            name = ctx.getUserPrincipal().getName();
        }
        return String.format("hello %s,"
            + " isHttps: %s,"
            + " authScheme: %s,"
            + " hasJWT: %s",
            name, ctx.isSecure(), ctx.getAuthenticationScheme(), hasJwt());
    }

    private boolean hasJwt() {
        return jwt.getClaimNames() != null;
    }
}

package org.acme.security.jwt;

import jakarta.annotation.security.PermitAll;
import jakarta.annotation.security.RolesAllowed;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.InternalServerErrorException;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.SecurityContext;

import org.eclipse.microprofile.jwt.JsonWebToken;

@Path("/secured")
public class TokenSecuredResource {

    @Inject
    JsonWebToken jwt;



    @GET
    @Path("permit-all")
    @PermitAll
    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@Context SecurityContext ctx) {
        return getResponseString(ctx);
    }

    @GET
    @Path("roles-allowed")


    @RolesAllowed({ "User", "Admin" })


    @Produces(MediaType.TEXT_PLAIN)
    public String helloRolesAllowed(@Context SecurityContext ctx) {
        return getResponseString(ctx) + ", birthdate: " + jwt.getClaim("birthdate").toString();


    }

    private String getResponseString(SecurityContext ctx) {
        String name;
        if (ctx.getUserPrincipal() == null) {
            name = "anonymous";
        } else if (!ctx.getUserPrincipal().getName().equals(jwt.getName())) {
            throw new InternalServerErrorException("Principal and JsonWebToken names do not match");
        } else {
            name = ctx.getUserPrincipal().getName();
        }
        return String.format("hello %s,"
            + " isHttps: %s,"
            + " authScheme: %s,"
            + " hasJWT: %s",
            name, ctx.isSecure(), ctx.getAuthenticationScheme(), hasJwt());
    }

    private boolean hasJwt() {
        return jwt.getClaimNames() != null;
    }
}

Copy to Clipboard

Toggle word wrap

1: The JsonWebToken is injected to access claims from the JWT.
2: This endpoint is exposed at /secured/roles-allowed.
3: The @RolesAllowed annotation restricts access to users with either the "User" or "Admin" role.
4: The response is constructed similarly to the hello method, with the addition of the birthdate claim retrieved directly from the injected JsonWebToken.

After you make this addition to your TokenSecuredResource, rerun the ./mvnw quarkus:dev command, and then try curl -v http://127.0.0.1:8080/secured/roles-allowed; echo to attempt to access the new endpoint.

Your output should be as follows:

curl command for /secured/roles-allowed

curl -v http://127.0.0.1:8080/secured/roles-allowed; echo

$ curl -v http://127.0.0.1:8080/secured/roles-allowed; echo

Copy to Clipboard

Toggle word wrap

This command returns the following response:

*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to 127.0.0.1 (127.0.0.1) port 8080 (#0)
> GET /secured/roles-allowed HTTP/1.1
> Host: 127.0.0.1:8080
> User-Agent: curl/7.54.0
> Accept: */*
>
< HTTP/1.1 401 Unauthorized
< Connection: keep-alive
< Content-Type: text/html;charset=UTF-8
< Content-Length: 14
< Date: Sun, 03 Mar 2019 16:32:34 GMT
<
* Connection #0 to host 127.0.0.1 left intact

*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to 127.0.0.1 (127.0.0.1) port 8080 (#0)
> GET /secured/roles-allowed HTTP/1.1
> Host: 127.0.0.1:8080
> User-Agent: curl/7.54.0
> Accept: */*
>
< HTTP/1.1 401 Unauthorized
< Connection: keep-alive
< Content-Type: text/html;charset=UTF-8
< Content-Length: 14
< Date: Sun, 03 Mar 2019 16:32:34 GMT
<
* Connection #0 to host 127.0.0.1 left intact

Copy to Clipboard

Toggle word wrap

Excellent. You did not provide a JWT in the request, so access to the endpoint was correctly denied. Instead, you received an HTTP 401 Unauthorized error.

To access the endpoint, you must obtain and include a valid JWT in your request. This involves two steps:

Configuring the SmallRye JWT extension with the necessary information to validate a JWT.
Generating a JWT with the appropriate claims to match the configuration.

1.2.5. Configuring the SmallRye JWT extension security information
Copy link

Create a security-jwt-quickstart/src/main/resources/application.properties with the following content:

Application properties for TokenSecuredResource

mp.jwt.verify.publickey.location=publicKey.pem 
mp.jwt.verify.issuer=https://example.com/issuer 

quarkus.native.resources.includes=publicKey.pem

mp.jwt.verify.publickey.location=publicKey.pem


mp.jwt.verify.issuer=https://example.com/issuer



quarkus.native.resources.includes=publicKey.pem

Copy to Clipboard

Toggle word wrap

1: Specifies the location of the public key file publicKey.pem on the classpath. See Adding a public key for adding this key.
2: Defines the expected issuer as https://example.com/issuer.
3: Ensures the publicKey.pem file is included as a resource in the native executable.

1.2.6. Adding a public key
Copy link

The JWT specification defines various levels of security of JWTs that one can use. The MicroProfile JWT RBAC specification requires JWTs signed with the RSA-256 signature algorithm. This in turn requires an RSA public key pair. On the REST endpoint server side, you need to configure the location of the RSA public key to use to verify the JWT sent along with requests. The mp.jwt.verify.publickey.location=publicKey.pem setting configured previously expects that the public key is available on the classpath as publicKey.pem. To accomplish this, copy the following content to a security-jwt-quickstart/src/main/resources/publicKey.pem file.

RSA public key PEM content

Copy to Clipboard

Toggle word wrap

1.2.7. Generating a JWT
Copy link

Often, one obtains a JWT from an identity manager such as Keycloak. But for this quickstart, you generate our own by using the JWT generation API provided by smallrye-jwt. For more information, see Generate JWT tokens with SmallRye JWT.

Take the code from the following listing and place it into security-jwt-quickstart/src/test/java/org/acme/security/jwt/GenerateToken.java:

GenerateToken main driver class

package org.acme.security.jwt;

import java.util.Arrays;
import java.util.HashSet;

import org.eclipse.microprofile.jwt.Claims;
import io.smallrye.jwt.build.Jwt;

/**
 * A utility class to generate and print a JWT token string to stdout.
 */
public class GenerateToken {

    /**
     * Generates and prints a JWT token.
     */
    public static void main(String[] args) {
        String token = Jwt.issuer("https://example.com/issuer") 
                .upn("jdoe@quarkus.io") 
                .groups(new HashSet<>(Arrays.asList("User", "Admin"))) 
                .claim(Claims.birthdate.name(), "2001-07-13") 
                .sign();

        System.out.println(token);
        System.exit(0);
    }
}

package org.acme.security.jwt;

import java.util.Arrays;
import java.util.HashSet;

import org.eclipse.microprofile.jwt.Claims;
import io.smallrye.jwt.build.Jwt;

/**
 * A utility class to generate and print a JWT token string to stdout.
 */
public class GenerateToken {

    /**
     * Generates and prints a JWT token.
     */
    public static void main(String[] args) {
        String token = Jwt.issuer("https://example.com/issuer")


                .upn("jdoe@quarkus.io")


                .groups(new HashSet<>(Arrays.asList("User", "Admin")))


                .claim(Claims.birthdate.name(), "2001-07-13")


                .sign();

        System.out.println(token);
        System.exit(0);
    }
}

Copy to Clipboard

Toggle word wrap

1: Sets the iss (issuer) claim in the JWT. This value must match the server-side mp.jwt.verify.issuer configuration for the token to be considered valid.
2: Specifies the upn (User Principal Name) claim, which the MicroProfile JWT RBAC specification defines as the preferred claim for identifying the Principal in container security APIs.
3: Defines the groups claim, which provides the group memberships and top-level roles assigned to the JWT bearer.
4: Adds a birthdate claim. Because this can be considered sensitive information, consider encrypting claims as described in Generate JWT tokens with SmallRye JWT.

Note that for this code to work, you need the content of the RSA private key corresponding to the public key you have in the TokenSecuredResource application. Take the following PEM content and place it into security-jwt-quickstart/src/test/resources/privateKey.pem:

RSA private key PEM content

Copy to Clipboard

Toggle word wrap

Later, you configure the smallrye.jwt.sign.key.location property to specify the location of the private signing key.

Generating keys with OpenSSL

It is also possible to generate a public and private key pair by using the OpenSSL command line tool.

openssl commands to generate keys

openssl genrsa -out rsaPrivateKey.pem 2048
openssl rsa -pubout -in rsaPrivateKey.pem -out publicKey.pem

openssl genrsa -out rsaPrivateKey.pem 2048
openssl rsa -pubout -in rsaPrivateKey.pem -out publicKey.pem

Copy to Clipboard

Toggle word wrap

An additional step is required to generate and convert the private key to the PKCS#8 format, commonly used for secure key storage and transport.

openssl commands to perform the conversion

openssl pkcs8 -topk8 -nocrypt -inform pem -in rsaPrivateKey.pem -outform pem -out privateKey.pem

openssl pkcs8 -topk8 -nocrypt -inform pem -in rsaPrivateKey.pem -outform pem -out privateKey.pem

Copy to Clipboard

Toggle word wrap

You can use the generated key pair instead of those used in this quickstart.

Ensure the application is running before generating the JSON Web Token (JWT) for the TokenSecuredResource endpoint.

Next, use the following command to generate the JWT:

Sample JWT generation output

mvn exec:java -Dexec.mainClass=org.acme.security.jwt.GenerateToken -Dexec.classpathScope=test -Dsmallrye.jwt.sign.key.location=privateKey.pem

$ mvn exec:java -Dexec.mainClass=org.acme.security.jwt.GenerateToken -Dexec.classpathScope=test -Dsmallrye.jwt.sign.key.location=privateKey.pem

Copy to Clipboard

Toggle word wrap

The JWT string is a Base64 URL-encoded string consisting of three parts, separated by . characters:

The header, which contains metadata about the token, such as the signing algorithm.
The payload, also called "claims", which includes the token’s claims or data.
The signature, which verifies the token’s integrity.

1.2.8. Finally, secured access to /secured/roles-allowed
Copy link

Now, let’s use this to make a secured request to the /secured/roles-allowed endpoint. Make sure you have the Quarkus server still running in dev mode, and then run the following command, making sure to use your version of the generated JWT from the previous step:

curl command for /secured/roles-allowed with JWT

curl -H "Authorization: Bearer eyJraWQ..." http://127.0.0.1:8080/secured/roles-allowed; echo

$ curl -H "Authorization: Bearer eyJraWQ..." http://127.0.0.1:8080/secured/roles-allowed; echo

Copy to Clipboard

Toggle word wrap

Make sure to use the generated token as the HTTP Authorization Bearer scheme value.

This command returns the following response:

hello jdoe@quarkus.io, isHttps: false, authScheme: Bearer, hasJWT: true, birthdate: 2001-07-13

hello jdoe@quarkus.io, isHttps: false, authScheme: Bearer, hasJWT: true, birthdate: 2001-07-13

Copy to Clipboard

Toggle word wrap

Success! You now have the following:

A non-anonymous caller name: jdoe@quarkus.io
An authentication scheme: Bearer
A non-null JsonWebToken
The birthdate claim value

1.2.9. Using the JsonWebToken and claim injection
Copy link

Now that you can generate a JWT to access our secured REST endpoints, let’s see what more you can do with the JsonWebToken interface and the JWT claims. The org.eclipse.microprofile.jwt.JsonWebToken interface extends the java.security.Principal interface, and is the object type returned by the jakarta.ws.rs.core.SecurityContext#getUserPrincipal() call you used previously. This means that code that does not use CDI but does have access to the REST container SecurityContext can get hold of the caller JsonWebToken interface by casting the SecurityContext#getUserPrincipal().

The JsonWebToken interface defines methods for accessing claims in the underlying JWT. It provides accessors for common claims that are required by the MicroProfile JWT RBAC specification and arbitrary claims that might exist in the JWT.

All the JWT claims can also be injected. Let’s expand our TokenSecuredResource with another endpoint /secured/roles-allowed-admin which uses the injected birthdate claim (as opposed to getting it from JsonWebToken):

package org.acme.security.jwt;

import jakarta.annotation.security.PermitAll;
import jakarta.annotation.security.RolesAllowed;
import jakarta.enterprise.context.RequestScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.InternalServerErrorException;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.SecurityContext;

import org.eclipse.microprofile.jwt.Claim;
import org.eclipse.microprofile.jwt.Claims;
import org.eclipse.microprofile.jwt.JsonWebToken;

@Path("/secured")
@RequestScoped 
public class TokenSecuredResource {

    @Inject
    JsonWebToken jwt; 
    @Inject
    @Claim(standard = Claims.birthdate)
    String birthdate; 

    @GET
    @Path("permit-all")
    @PermitAll
    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@Context SecurityContext ctx) {
        return getResponseString(ctx);
    }

    @GET
    @Path("roles-allowed")
    @RolesAllowed({ "User", "Admin" })
    @Produces(MediaType.TEXT_PLAIN)
    public String helloRolesAllowed(@Context SecurityContext ctx) {
        return getResponseString(ctx) + ", birthdate: " + jwt.getClaim("birthdate").toString();
    }

    @GET
    @Path("roles-allowed-admin")
    @RolesAllowed("Admin")
    @Produces(MediaType.TEXT_PLAIN)
    public String helloRolesAllowedAdmin(@Context SecurityContext ctx) {
        return getResponseString(ctx) + ", birthdate: " + birthdate; 
    }

    private String getResponseString(SecurityContext ctx) {
        String name;
        if (ctx.getUserPrincipal() == null) {
            name = "anonymous";
        } else if (!ctx.getUserPrincipal().getName().equals(jwt.getName())) {
            throw new InternalServerErrorException("Principal and JsonWebToken names do not match");
        } else {
            name = ctx.getUserPrincipal().getName();
        }
        return String.format("hello %s,"
            + " isHttps: %s,"
            + " authScheme: %s,"
            + " hasJWT: %s",
            name, ctx.isSecure(), ctx.getAuthenticationScheme(), hasJwt());
    }

    private boolean hasJwt() {
        return jwt.getClaimNames() != null;
    }
}

package org.acme.security.jwt;

import jakarta.annotation.security.PermitAll;
import jakarta.annotation.security.RolesAllowed;
import jakarta.enterprise.context.RequestScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.InternalServerErrorException;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.SecurityContext;

import org.eclipse.microprofile.jwt.Claim;
import org.eclipse.microprofile.jwt.Claims;
import org.eclipse.microprofile.jwt.JsonWebToken;

@Path("/secured")
@RequestScoped


public class TokenSecuredResource {

    @Inject
    JsonWebToken jwt;


    @Inject
    @Claim(standard = Claims.birthdate)
    String birthdate;



    @GET
    @Path("permit-all")
    @PermitAll
    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@Context SecurityContext ctx) {
        return getResponseString(ctx);
    }

    @GET
    @Path("roles-allowed")
    @RolesAllowed({ "User", "Admin" })
    @Produces(MediaType.TEXT_PLAIN)
    public String helloRolesAllowed(@Context SecurityContext ctx) {
        return getResponseString(ctx) + ", birthdate: " + jwt.getClaim("birthdate").toString();
    }

    @GET
    @Path("roles-allowed-admin")
    @RolesAllowed("Admin")
    @Produces(MediaType.TEXT_PLAIN)
    public String helloRolesAllowedAdmin(@Context SecurityContext ctx) {
        return getResponseString(ctx) + ", birthdate: " + birthdate;


    }

    private String getResponseString(SecurityContext ctx) {
        String name;
        if (ctx.getUserPrincipal() == null) {
            name = "anonymous";
        } else if (!ctx.getUserPrincipal().getName().equals(jwt.getName())) {
            throw new InternalServerErrorException("Principal and JsonWebToken names do not match");
        } else {
            name = ctx.getUserPrincipal().getName();
        }
        return String.format("hello %s,"
            + " isHttps: %s,"
            + " authScheme: %s,"
            + " hasJWT: %s",
            name, ctx.isSecure(), ctx.getAuthenticationScheme(), hasJwt());
    }

    private boolean hasJwt() {
        return jwt.getClaimNames() != null;
    }
}

Copy to Clipboard

Toggle word wrap

1: The @RequestScoped scope is required to enable injection of the birthdate claim as a String.
2: The JsonWebToken is injected here, providing access to all claims and JWT-related information.
3: The birthdate claim is injected as a String. This highlights why the @RequestScoped scope is mandatory.
4: The injected birthdate claim is directly used to construct the response.

Now generate the token again and run:

curl -H "Authorization: Bearer eyJraWQ..." http://127.0.0.1:8080/secured/roles-allowed-admin; echo

$ curl -H "Authorization: Bearer eyJraWQ..." http://127.0.0.1:8080/secured/roles-allowed-admin; echo

Copy to Clipboard

Toggle word wrap

Make sure to use the generated token as the HTTP Authorization Bearer scheme value.

This command returns the following response:

hello jdoe@quarkus.io, isHttps: false, authScheme: Bearer, hasJWT: true, birthdate: 2001-07-13

hello jdoe@quarkus.io, isHttps: false, authScheme: Bearer, hasJWT: true, birthdate: 2001-07-13

Copy to Clipboard

Toggle word wrap

1.2.10. Run the application in JVM mode
Copy link

You can run the application as a standard Java application.

Compile the application:
- Using the Quarkus CLI:
  quarkus build
  
  Copy to Clipboard Toggle word wrap
- Using Maven:
  ./mvnw install
  
  Copy to Clipboard Toggle word wrap
- Using Gradle:
  ./gradlew build
  
  Copy to Clipboard Toggle word wrap

Run the application:

java -jar target/quarkus-app/quarkus-run.jar

java -jar target/quarkus-app/quarkus-run.jar

Copy to Clipboard

Toggle word wrap

1.2.11. Run the application in native mode
Copy link

You can compile this same demo into native mode without any modifications. This implies that you no longer need to install a JVM on your production environment. The runtime technology is included in the produced binary and optimized to run with minimal resources required.

Compilation takes a bit longer, so this step is disabled by default.

Build your application again by enabling the native profile:
- Using the Quarkus CLI:
  quarkus build --native
  
  Copy to Clipboard Toggle word wrap
- Using Maven:
  ./mvnw install -Dnative
  
  Copy to Clipboard Toggle word wrap
- Using Gradle:
  ./gradlew build -Dquarkus.native.enabled=true
  
  Copy to Clipboard Toggle word wrap

Run the following binary directly:

./target/security-jwt-quickstart-1.0.0-SNAPSHOT-runner

./target/security-jwt-quickstart-1.0.0-SNAPSHOT-runner

Copy to Clipboard

Toggle word wrap

1.2.12. Explore the solution
Copy link

The security-jwt-quickstart directory repository contains all the versions covered in this quickstart guide, along with additional endpoints that demonstrate subresources using injected JsonWebToken tokens and their claims via CDI APIs.

We encourage you to explore the security-jwt-quickstart directory and review the quickstart solutions to learn more about the features of the SmallRye JWT extension.

1.3. Reference guide
Copy link

1.3.1. Supported injection scopes
Copy link

@ApplicationScoped, @Singleton and @RequestScoped outer bean injection scopes are all supported when an org.eclipse.microprofile.jwt.JsonWebToken is injected, with the @RequestScoped scoping for JsonWebToken enforced to ensure the current token is represented.

However, @RequestScoped must be used when the individual token claims are injected as simple types such as String, for example:

package org.acme.security.jwt;

import jakarta.inject.Inject;
import org.eclipse.microprofile.jwt.Claim;
import org.eclipse.microprofile.jwt.Claims;

@Path("/secured")
@RequestScoped
public class TokenSecuredResource {

    @Inject
    @Claim(standard = Claims.birthdate)
    String birthdate;
}

package org.acme.security.jwt;

import jakarta.inject.Inject;
import org.eclipse.microprofile.jwt.Claim;
import org.eclipse.microprofile.jwt.Claims;

@Path("/secured")
@RequestScoped
public class TokenSecuredResource {

    @Inject
    @Claim(standard = Claims.birthdate)
    String birthdate;
}

Copy to Clipboard

Toggle word wrap

Note you can also use the injected JsonWebToken to access the individual claims, but setting @RequestScoped is unnecessary in this case.

Please see MP JWT CDI Injection Requirements for more details.

1.3.2. Supported public key formats
Copy link

Public keys can be formatted in any of the following formats, specified in order of precedence:

Public Key Cryptography Standards #8 (PKCS#8) PEM
JSON Web Key (JWK)
JSON Web Key Set (JWKS)
JSON Web Key (JWK) Base64 URL encoded
JSON Web Key Set (JWKS) Base64 URL encoded

1.3.3. Dealing with verification keys
Copy link

If you need to verify the token signature by using the asymmetric RSA or Elliptic Curve (EC) key, use the mp.jwt.verify.publickey.location property to refer to the local or remote verification key.

Use mp.jwt.verify.publickey.algorithm to customize the verification algorithm (default is RS256); for example, set it to ES256 when working with the EC keys.

If you need to verify the token signature by using the symmetric secret key, then either a JSON Web Key (JWK) or JSON Web Key Set (JWK Set) format must be used to represent this secret key, for example:

{
 "keys": [
   {
     "kty":"oct",
     "kid":"secretKey",
     "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"
   }
 ]
}

{
 "keys": [
   {
     "kty":"oct",
     "kid":"secretKey",
     "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"
   }
 ]
}

Copy to Clipboard

Toggle word wrap

This secret key JWK must also be referred to with smallrye.jwt.verify.key.location. smallrye.jwt.verify.algorithm should be set to HS256/HS384/HS512.

1.3.4. Parse and verify JsonWebToken with JWTParser
Copy link

If the JWT token can not be injected, for example, if it is embedded in the service request payload or the service endpoint acquires it out of band, then one can use JWTParser:

import org.eclipse.microprofile.jwt.JsonWebToken;
import io.smallrye.jwt.auth.principal.JWTParser;
...
@Inject JWTParser parser;

String token = getTokenFromOidcServer();

// Parse and verify the token
JsonWebToken jwt = parser.parse(token);

import org.eclipse.microprofile.jwt.JsonWebToken;
import io.smallrye.jwt.auth.principal.JWTParser;
...
@Inject JWTParser parser;

String token = getTokenFromOidcServer();

// Parse and verify the token
JsonWebToken jwt = parser.parse(token);

Copy to Clipboard

Toggle word wrap

You can also use it to customize how the token is verified or decrypted. For example, one can supply a local SecretKey:

package org.acme.security.jwt;

import io.smallrye.jwt.auth.principal.ParseException;
import jakarta.inject.Inject;
import jakarta.ws.rs.CookieParam;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.NewCookie;
import jakarta.ws.rs.core.Response;
import org.eclipse.microprofile.jwt.JsonWebToken;
import io.smallrye.jwt.auth.principal.JWTParser;
import io.smallrye.jwt.build.Jwt;

@Path("/secured")
public class SecuredResource {
    private static final String SECRET = "AyM1SysPpbyDfgZld3umj1qzKObwVMko";

    @Inject
    JWTParser parser;

    @GET
    @Produces("text/plain")
    public Response getUserName(@CookieParam("jwt") String jwtCookie) throws ParseException {
        if (jwtCookie == null) {
            // Create a JWT token signed by using the 'HS256' algorithm
            String newJwtCookie = Jwt.upn("Alice").signWithSecret(SECRET);
            // or create a JWT token encrypted by using the 'A256KW' algorithm
            // Jwt.upn("alice").encryptWithSecret(secret);
            return Response.ok("Alice").cookie(new NewCookie("jwt", newJwtCookie)).build();
        } else {
            // All mp.jwt and smallrye.jwt properties are still effective; only the verification key is customized.
            JsonWebToken jwt = parser.verify(jwtCookie, SECRET);
            // or jwt = parser.decrypt(jwtCookie, secret);
            return Response.ok(jwt.getName()).build();
        }
    }
}

package org.acme.security.jwt;

import io.smallrye.jwt.auth.principal.ParseException;
import jakarta.inject.Inject;
import jakarta.ws.rs.CookieParam;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.NewCookie;
import jakarta.ws.rs.core.Response;
import org.eclipse.microprofile.jwt.JsonWebToken;
import io.smallrye.jwt.auth.principal.JWTParser;
import io.smallrye.jwt.build.Jwt;

@Path("/secured")
public class SecuredResource {
    private static final String SECRET = "AyM1SysPpbyDfgZld3umj1qzKObwVMko";

    @Inject
    JWTParser parser;

    @GET
    @Produces("text/plain")
    public Response getUserName(@CookieParam("jwt") String jwtCookie) throws ParseException {
        if (jwtCookie == null) {
            // Create a JWT token signed by using the 'HS256' algorithm
            String newJwtCookie = Jwt.upn("Alice").signWithSecret(SECRET);
            // or create a JWT token encrypted by using the 'A256KW' algorithm
            // Jwt.upn("alice").encryptWithSecret(secret);
            return Response.ok("Alice").cookie(new NewCookie("jwt", newJwtCookie)).build();
        } else {
            // All mp.jwt and smallrye.jwt properties are still effective; only the verification key is customized.
            JsonWebToken jwt = parser.verify(jwtCookie, SECRET);
            // or jwt = parser.decrypt(jwtCookie, secret);
            return Response.ok(jwt.getName()).build();
        }
    }
}

Copy to Clipboard

Toggle word wrap

Please also see the How to Add SmallRye JWT directly section about using JWTParser without the HTTP support provided by quarkus-smallrye-jwt.

1.3.5. Token decryption
Copy link

If your application needs to accept tokens with encrypted claims or encrypted inner-signed claims, simply set the smallrye.jwt.decrypt.key.location property to point to the decryption key.

If this is the only key property set, the incoming token is expected to contain only encrypted claims. If either mp.jwt.verify.publickey or mp.jwt.verify.publickey.location verification properties are also set, then the incoming token is expected to contain the encrypted inner-signed token.

See Generate JWT tokens with SmallRye JWT and learn how to generate the encrypted or inner-signed and then encrypted tokens quickly.

1.3.6. Custom factories
Copy link

The io.smallrye.jwt.auth.principal.DefaultJWTCallerPrincipalFactory is the default implementation used to parse and verify JWT tokens, converting them into JsonWebToken principals. This factory relies on the MP JWT and smallrye-jwt properties, as described in the Configuration section, to validate and customize JWT tokens.

If you need to implement a custom factory—such as to skip re-verifying tokens that have already been validated by a firewall—you can do so in one of the following ways:

Use the ServiceLoader mechanism by creating a META-INF/services/io.smallrye.jwt.auth.principal.JWTCallerPrincipalFactory resource.
Provide an Alternative CDI bean implementation, like the example below:

import java.nio.charset.StandardCharsets;
import java.util.Base64;
import jakarta.annotation.Priority;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Alternative;
import org.jose4j.jwt.JwtClaims;
import org.jose4j.jwt.consumer.InvalidJwtException;
import io.smallrye.jwt.auth.principal.DefaultJWTCallerPrincipal;
import io.smallrye.jwt.auth.principal.JWTAuthContextInfo;
import io.smallrye.jwt.auth.principal.JWTCallerPrincipal;
import io.smallrye.jwt.auth.principal.JWTCallerPrincipalFactory;
import io.smallrye.jwt.auth.principal.ParseException;

@ApplicationScoped
@Alternative
@Priority(1)
public class TestJWTCallerPrincipalFactory extends JWTCallerPrincipalFactory {

    @Override
    public JWTCallerPrincipal parse(String token, JWTAuthContextInfo authContextInfo) throws ParseException {
        try {
            // Token has already been verified; parse the token claims only
            String json = new String(Base64.getUrlDecoder().decode(token.split("\\.")[1]), StandardCharsets.UTF_8);
            return new DefaultJWTCallerPrincipal(JwtClaims.parse(json));
        } catch (InvalidJwtException ex) {
            throw new ParseException(ex.getMessage());
        }
    }
}

import java.nio.charset.StandardCharsets;
import java.util.Base64;
import jakarta.annotation.Priority;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Alternative;
import org.jose4j.jwt.JwtClaims;
import org.jose4j.jwt.consumer.InvalidJwtException;
import io.smallrye.jwt.auth.principal.DefaultJWTCallerPrincipal;
import io.smallrye.jwt.auth.principal.JWTAuthContextInfo;
import io.smallrye.jwt.auth.principal.JWTCallerPrincipal;
import io.smallrye.jwt.auth.principal.JWTCallerPrincipalFactory;
import io.smallrye.jwt.auth.principal.ParseException;

@ApplicationScoped
@Alternative
@Priority(1)
public class TestJWTCallerPrincipalFactory extends JWTCallerPrincipalFactory {

    @Override
    public JWTCallerPrincipal parse(String token, JWTAuthContextInfo authContextInfo) throws ParseException {
        try {
            // Token has already been verified; parse the token claims only
            String json = new String(Base64.getUrlDecoder().decode(token.split("\\.")[1]), StandardCharsets.UTF_8);
            return new DefaultJWTCallerPrincipal(JwtClaims.parse(json));
        } catch (InvalidJwtException ex) {
            throw new ParseException(ex.getMessage());
        }
    }
}

Copy to Clipboard

Toggle word wrap

1.3.7. Blocking calls
Copy link

quarkus-smallrye-jwt extension uses SmallRye JWT library which is currently not reactive.

What it means from the perspective of quarkus-smallrye-jwt, which operates as part of the reactive Quarkus security architecture, is that an IO thread entering the SmallRye JWT verification or decryption code might block in one of the following cases:

The default key resolver refreshes the JsonWebKey set containing the keys, which involves a remote call to the OIDC endpoint.
The custom key resolver, such as AWS Application Load Balancer (ALB) key resolver, resolves the keys against the AWS ALB key endpoint by using the current token’s key identifier header value.

In such cases, if connections are slow—for instance, taking more than 3 seconds to respond to the key endpoint—the current event loop thread is likely to become blocked.

To prevent it from blocking, set quarkus.smallrye-jwt.blocking-authentication=true.

1.3.8. Token propagation
Copy link

Please see the Token Propagation section about the Bearer access token propagation to the downstream services.

1.3.9. Testing
Copy link

1.3.9.1. Automatic key generation
Copy link

This extension generates an asymmetric RSA 2024 bit signing key pair in the dev and test modes if the verification key has not been configured. Once the key pair is generated, the public RSA key is used to configure the mp.jwt.verify.publickey property, and the RSA private key is available to tests to sign tokens using smallrye-jwt-build, for example:

import io.smallrye.jwt.build.Jwt;
import jakarta.ws.rs.GET;

@GET
public String token() {
   return Jwt.upn("Alice").sign();
}

import io.smallrye.jwt.build.Jwt;
import jakarta.ws.rs.GET;

@GET
public String token() {
   return Jwt.upn("Alice").sign();
}

Copy to Clipboard

Toggle word wrap

See signing claims guide for mode details.

You can disable automatic key generation by setting at least one of the following properties:

mp.jwt.verify.publickey.location
mp.jwt.verify.publickey
mp.jwt.decrypt.key.location
smallrye.jwt.encrypt.key.location
smallrye.jwt.sign.key.location
smallrye.jwt.sign.key

Note

In dev mode, if you do not explicitly configure the issuer using the mp.jwt.verify.issuer property, the SmallRye JWT extension will set a default issuer of https://quarkus.io/issuer.

If you prefer to configure the issuer programmatically, set mp.jwt.verify.issuer to NONE to prevent the default value from being applied.

1.3.9.2. Wiremock
Copy link

If you configure mp.jwt.verify.publickey.location to point to HTTPS or HTTP-based JsonWebKey (JWK) set, then you can use the same approach as described in the OpenID Connect Bearer Token Integration testing Wiremock section but only change the application.properties to use MP JWT configuration properties instead:

keycloak.url is set by OidcWiremockTestResource

# keycloak.url is set by OidcWiremockTestResource
mp.jwt.verify.publickey.location=${keycloak.url}/realms/quarkus/protocol/openid-connect/certs
mp.jwt.verify.issuer=${keycloak.url}/realms/quarkus

Copy to Clipboard

Toggle word wrap

1.3.9.3. Keycloak
Copy link

If you work with Keycloak and configure mp.jwt.verify.publickey.location to point to HTTPS or HTTP-based JsonWebKey (JWK) set, you can use the same approach as described in the OpenID Connect Bearer Token Integration testing Keycloak section but only change the application.properties to use MP JWT configuration properties instead:

keycloak.url is set by DevServices for Keycloak

# keycloak.url is set by DevServices for Keycloak
mp.jwt.verify.publickey.location=${keycloak.url}/realms/quarkus/protocol/openid-connect/certs
mp.jwt.verify.issuer=${keycloak.url}/realms/quarkus

Copy to Clipboard

Toggle word wrap

Note that the tokens issued by Keycloak have an iss (issuer) claim set to the realm endpoint address.

If your Quarkus application runs in a Docker container, it might share a network interface with a Keycloak container started by DevServices for Keycloak. In this scenario, the Quarkus application and Keycloak communicate through an internal shared Docker network.

In such cases, use the following configuration instead:

keycloak.url is set by DevServices for Keycloak,
Quarkus accesses it through an internal shared docker network interface.
Issuer is set to the docker bridge localhost endpoint address represented by the `client.quarkus.oidc.auth-server-url` property

# keycloak.url is set by DevServices for Keycloak,
# Quarkus accesses it through an internal shared docker network interface.
mp.jwt.verify.publickey.location=${keycloak.url}/realms/quarkus/protocol/openid-connect/certs

# Issuer is set to the docker bridge localhost endpoint address represented by the `client.quarkus.oidc.auth-server-url` property
mp.jwt.verify.issuer=${client.quarkus.oidc.auth-server-url}

Copy to Clipboard

Toggle word wrap

1.3.9.4. Local public key
Copy link

You can use the same approach as described in the OpenID Connect Bearer Token Integration testing Local public key section but only change the application.properties to use MP JWT configuration properties instead:

mp.jwt.verify.publickey=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlivFI8qB4D0y2jy0CfEqFyy46R0o7S8TKpsx5xbHKoU1VWg6QkQm+ntyIv1p4kE1sPEQO73+HY8+Bzs75XwRTYL1BmR1w8J5hmjVWjc6R2BTBGAYRPFRhor3kpM6ni2SPmNNhurEAHw7TaqszP5eUF/F9+KEBWkwVta+PZ37bwqSE4sCb1soZFrVz/UT/LF4tYpuVYt3YbqToZ3pZOZ9AX2o1GCG3xwOjkc4x0W7ezbQZdC9iftPxVHR8irOijJRRjcPDtA6vPKpzLl6CyYnsIYPd99ltwxTHjr3npfv/3Lw50bAkbT4HeLFxTx4flEoZLKO/g0bAoV2uqBhkA9xnQIDAQAB
# set it to the issuer value which is used to generate the tokens
mp.jwt.verify.issuer=${keycloak.url}/realms/quarkus

# required to sign the tokens
smallrye.jwt.sign.key.location=privateKey.pem

mp.jwt.verify.publickey=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlivFI8qB4D0y2jy0CfEqFyy46R0o7S8TKpsx5xbHKoU1VWg6QkQm+ntyIv1p4kE1sPEQO73+HY8+Bzs75XwRTYL1BmR1w8J5hmjVWjc6R2BTBGAYRPFRhor3kpM6ni2SPmNNhurEAHw7TaqszP5eUF/F9+KEBWkwVta+PZ37bwqSE4sCb1soZFrVz/UT/LF4tYpuVYt3YbqToZ3pZOZ9AX2o1GCG3xwOjkc4x0W7ezbQZdC9iftPxVHR8irOijJRRjcPDtA6vPKpzLl6CyYnsIYPd99ltwxTHjr3npfv/3Lw50bAkbT4HeLFxTx4flEoZLKO/g0bAoV2uqBhkA9xnQIDAQAB
# set it to the issuer value which is used to generate the tokens
mp.jwt.verify.issuer=${keycloak.url}/realms/quarkus

# required to sign the tokens
smallrye.jwt.sign.key.location=privateKey.pem

Copy to Clipboard

Toggle word wrap

1.3.9.5. TestSecurity annotation
Copy link

Add the following dependency:

Using Maven:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-test-security-jwt</artifactId>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-test-security-jwt</artifactId>
    <scope>test</scope>
</dependency>

Copy to Clipboard

Toggle word wrap

Using Gradle:

testImplementation("io.quarkus:quarkus-test-security-jwt")

testImplementation("io.quarkus:quarkus-test-security-jwt")

Copy to Clipboard

Toggle word wrap

Then, write test code such as this:

import static org.hamcrest.Matchers.is;
import org.junit.jupiter.api.Test;
import io.quarkus.test.common.http.TestHTTPEndpoint;
import io.quarkus.test.junit.QuarkusTest;
import io.quarkus.test.security.TestSecurity;
import io.quarkus.test.security.jwt.Claim;
import io.quarkus.test.security.jwt.JwtSecurity;
import io.restassured.RestAssured;

@QuarkusTest
@TestHTTPEndpoint(ProtectedResource.class)
public class TestSecurityAuthTest {

    @Test
    @TestSecurity(user = "userJwt", roles = "viewer")
    public void testJwt() {
        RestAssured.when().get("test-security-jwt").then()
                .body(is("userJwt:viewer"));
    }

    @Test
    @TestSecurity(user = "userJwt", roles = "viewer")
    @JwtSecurity(claims = {
            @Claim(key = "email", value = "user@gmail.com")
    })
    public void testJwtWithClaims() {
        RestAssured.when().get("test-security-jwt-claims").then()
                .body(is("userJwt:viewer:user@gmail.com"));
    }

}

import static org.hamcrest.Matchers.is;
import org.junit.jupiter.api.Test;
import io.quarkus.test.common.http.TestHTTPEndpoint;
import io.quarkus.test.junit.QuarkusTest;
import io.quarkus.test.security.TestSecurity;
import io.quarkus.test.security.jwt.Claim;
import io.quarkus.test.security.jwt.JwtSecurity;
import io.restassured.RestAssured;

@QuarkusTest
@TestHTTPEndpoint(ProtectedResource.class)
public class TestSecurityAuthTest {

    @Test
    @TestSecurity(user = "userJwt", roles = "viewer")
    public void testJwt() {
        RestAssured.when().get("test-security-jwt").then()
                .body(is("userJwt:viewer"));
    }

    @Test
    @TestSecurity(user = "userJwt", roles = "viewer")
    @JwtSecurity(claims = {
            @Claim(key = "email", value = "user@gmail.com")
    })
    public void testJwtWithClaims() {
        RestAssured.when().get("test-security-jwt-claims").then()
                .body(is("userJwt:viewer:user@gmail.com"));
    }

}

Copy to Clipboard

Toggle word wrap

where the ProtectedResource class might look like this:

@Path("/web-app")
@Authenticated
public class ProtectedResource {

    @Inject
    JsonWebToken accessToken;

    @GET
    @Path("test-security-jwt")
    public String testSecurityOidc() {
        return accessToken.getName() + ":" + accessToken.getGroups().iterator().next();
    }

    @GET
    @Path("test-security-jwt-claims")
    public String testSecurityOidcUserInfoMetadata() {
        return accessToken.getName() + ":" + accessToken.getGroups().iterator().next()
                + ":" + accessToken.getClaim("email");
    }
}

@Path("/web-app")
@Authenticated
public class ProtectedResource {

    @Inject
    JsonWebToken accessToken;

    @GET
    @Path("test-security-jwt")
    public String testSecurityOidc() {
        return accessToken.getName() + ":" + accessToken.getGroups().iterator().next();
    }

    @GET
    @Path("test-security-jwt-claims")
    public String testSecurityOidcUserInfoMetadata() {
        return accessToken.getName() + ":" + accessToken.getGroups().iterator().next()
                + ":" + accessToken.getClaim("email");
    }
}

Copy to Clipboard

Toggle word wrap

Note that the @TestSecurity annotation must always be used, and its user property is returned as JsonWebToken.getName() and roles property - as JsonWebToken.getGroups(). @JwtSecurity annotation is optional and can be used to set the additional token claims.

Tip

@TestSecurity and @JwtSecurity can be combined in a meta-annotation, as follows:

    @Retention(RetentionPolicy.RUNTIME)
    @Target({ ElementType.METHOD })
    @TestSecurity(user = "userOidc", roles = "viewer")
    @OidcSecurity(introspectionRequired = true,
        introspection = {
            @TokenIntrospection(key = "email", value = "user@gmail.com")
        }
    )
    public @interface TestSecurityMetaAnnotation {

    }

    @Retention(RetentionPolicy.RUNTIME)
    @Target({ ElementType.METHOD })
    @TestSecurity(user = "userOidc", roles = "viewer")
    @OidcSecurity(introspectionRequired = true,
        introspection = {
            @TokenIntrospection(key = "email", value = "user@gmail.com")
        }
    )
    public @interface TestSecurityMetaAnnotation {

    }

Copy to Clipboard

Toggle word wrap

This is particularly useful if the same set of security settings needs to be used in multiple test methods.

1.3.10. How to check the errors in the logs
Copy link

Please enable io.quarkus.smallrye.jwt.runtime.auth.MpJwtValidator TRACE level logging to see more details about the token verification or decryption errors:

quarkus.log.category."io.quarkus.smallrye.jwt.runtime.auth.MpJwtValidator".level=TRACE
quarkus.log.category."io.quarkus.smallrye.jwt.runtime.auth.MpJwtValidator".min-level=TRACE

quarkus.log.category."io.quarkus.smallrye.jwt.runtime.auth.MpJwtValidator".level=TRACE
quarkus.log.category."io.quarkus.smallrye.jwt.runtime.auth.MpJwtValidator".min-level=TRACE

Copy to Clipboard

Toggle word wrap

1.3.11. Proactive authentication
Copy link

If you’d like to skip the token verification when the public endpoint methods are invoked, disable the proactive authentication.

Note that you can’t access the injected JsonWebToken through public methods if token verification has not been done.

1.3.12. How to add SmallRye JWT directly
Copy link

To parse and verify JsonWebToken with JWTParser, use smallrye-jwt instead of quarkus-smallrye-jwt directly for the following situations:

You work with Quarkus extensions that do not support HTTP, such as Quarkus GRPC.
You provide an extension-specific HTTP, the support of which conflicts with the support of those offered by quarkus-smallrye-jwt and Vert.x HTTP, such as Quarkus AWS Lambda.

Start with adding the smallrye-jwt dependency:

Using Maven:

<dependency>
    <groupId>io.smallrye</groupId>
    <artifactId>smallrye-jwt</artifactId>
</dependency>

<dependency>
    <groupId>io.smallrye</groupId>
    <artifactId>smallrye-jwt</artifactId>
</dependency>

Copy to Clipboard

Toggle word wrap

Using Gradle:

implementation("io.smallrye:smallrye-jwt")

implementation("io.smallrye:smallrye-jwt")

Copy to Clipboard

Toggle word wrap

Then, update application.properties to get all the CDI producers provided by smallrye-jwt included as follows:

quarkus.index-dependency.smallrye-jwt.group-id=io.smallrye
quarkus.index-dependency.smallrye-jwt.artifact-id=smallrye-jwt

quarkus.index-dependency.smallrye-jwt.group-id=io.smallrye
quarkus.index-dependency.smallrye-jwt.artifact-id=smallrye-jwt

Copy to Clipboard

Toggle word wrap

1.4. Configuration reference
Copy link

1.4.1. Quarkus configuration
Copy link

🔒 Fixed at build time: Configuration property fixed at build time - All other configuration properties are overridable at runtime

Expand

Configuration property	Type	Default
🔒 Fixed at build time `quarkus.smallrye-jwt.enabled` The MP-JWT configuration object Environment variable: `QUARKUS_SMALLRYE_JWT_ENABLED`	boolean	`true`
🔒 Fixed at build time `quarkus.smallrye-jwt.rsa-sig-provider` The name of the `java.security.Provider` that supports SHA256withRSA signatures Environment variable: `QUARKUS_SMALLRYE_JWT_RSA_SIG_PROVIDER`	string	`SunRsaSign`
`quarkus.smallrye-jwt.blocking-authentication` Enable this property if fetching the remote keys can be a time-consuming operation. Do not enable it if you use the local keys. Environment variable: `QUARKUS_SMALLRYE_JWT_BLOCKING_AUTHENTICATION`	boolean	`false`
`quarkus.smallrye-jwt.silent` Always create HTTP 401 challenge, even for requests containing no authentication credentials. JWT authentication mechanism will return HTTP 401 when an authentication challenge is required. However if it is used alongside one of the interactive authentication mechanisms then returning HTTP 401 to the users accessing the application from a browser may not be desired. If you prefer you can request that JWT authentication mechanism does not create a challenge in such cases by setting this property to 'true'. Environment variable: `QUARKUS_SMALLRYE_JWT_SILENT`	boolean	`false`

1.4.2. MicroProfile JWT configuration
Copy link

Expand

Property Name	Default	Description
`mp.jwt.verify.publickey`	`none`	The `mp.jwt.verify.publickey` config property allows the public key text to be supplied as a string. The public key is parsed from the supplied string in the order defined in the Supported public key formats section.
`mp.jwt.verify.publickey.location`	`none`	Config property allows for a specified external or internal location of the public key. The value can be a relative path or a URL. If the value points to an HTTPS-based JWK set, then, for it to work in native mode, the `quarkus.ssl.native` property must also be set to `true`. See Using SSL With Native Executables for more details.
`mp.jwt.verify.publickey.algorithm`	`RS256`	List of signature algorithms. Set it to `ES256` to support the Elliptic Curve signature algorithm.
`mp.jwt.decrypt.key.location`	`none`	Config property allows for a specified external or internal location of the Private Decryption Key.
`mp.jwt.decrypt.key.algorithm`	`RSA-OAEP,RSA-OAEP-256`	List of decryption algorithms. Set it to `RSA-OAEP-256` to support RSA-OAEP with SHA-256 only.
`mp.jwt.verify.issuer`	`none`	Config property specifies the value of the `iss` (issuer) claim of the JWT that the server accepts as valid.
`mp.jwt.verify.audiences`	`none`	Comma-separated list of audiences a token `aud` claim might contain.
`mp.jwt.verify.clock.skew`	`60`	Clock skew in seconds used during the token expiration and age verification. An expired token is accepted if the current time is within the number of seconds specified by this property after the token expiration time. The default value is 60 seconds.
`mp.jwt.verify.token.age`	`none`	Number of seconds that must not elapse since the token `iat` (issued at) time.
`mp.jwt.token.header`	`Authorization`	Set this property if another header, such as `Cookie`, is used to pass the token.
`mp.jwt.token.cookie`	`none`	Name of the cookie containing a token. This property is effective only if `mp.jwt.token.header` is set to `Cookie`.

1.4.3. Additional SmallRye JWT configuration
Copy link

SmallRye JWT provides more properties that can be used to customize the token processing:

Expand

Property Name	Default	Description
`smallrye.jwt.verify.secretkey`	`none`	Secret key supplied as a string.
`smallrye.jwt.verify.key.location`	`NONE`	Location of the verification key, which can point to both public and secret keys. Secret keys can only be in the JWK format. Note that 'mp.jwt.verify.publickey.location' is ignored if this property is set.
`smallrye.jwt.verify.algorithm`		Signature algorithm. This property should only be used to set a symmetric algorithm such as `HS256`. It is deprecated for setting asymmetric algorithms such as `ES256` - use 'mp.jwt.verify.publickey.algorithm' instead.
`smallrye.jwt.verify.key-format`	`ANY`	Set this property to a specific key format such as `PEM_KEY`, `PEM_CERTIFICATE`, `JWK` or `JWK_BASE64URL` to optimize the way the verification key is loaded.
`smallrye.jwt.verify.key-provider`	`DEFAULT`	By default, PEM, JWK, or JWK key sets can be read from the local file system or fetched from URIs as required by MicroProfile JWT specification. Set this property to `AWS_ALB` to support an AWS Application Load Balancer verification key resolution.
`smallrye.jwt.verify.relax-key-validation`	`false`	Relax the validation of the verification keys; setting this property to `true` allows public RSA keys with a length of less than 2048 bits.
`smallrye.jwt.verify.certificate-thumbprint`	`false`	If this property is enabled, a signed token must contain either 'x5t' or 'x5t#S256' X509Certificate thumbprint headers. Verification keys can only be in JWK or PEM Certificate key formats. JWK keys must have an 'x5c' (Base64-encoded X509Certificate) property set.
`smallrye.jwt.token.header`	`Authorization`	Set this property if another header, such as `Cookie`, is used to pass the token. This property is deprecated - use 'mp.jwt.token.header'.
`smallrye.jwt.key-cache-size`	`100`	Key cache size. Use this property and `smallrye.jwt.key-cache-time-to-live` to control the key cache when a key provider such as `AWS_ALB` is configured with `smallrye.jwt.verify.key-provider=AWS_ALB` for resolving the keys dynamically.
`smallrye.jwt.key-cache-time-to-live`	`10`	Key cache entry time-to-live in minutes. Use this property and `smallrye.jwt.key-cache-size` to control the key cache when a key provider such as `AWS_ALB` is configured with `smallrye.jwt.verify.key-provider=AWS_ALB` for resolving the keys dynamically.
`smallrye.jwt.token.cookie`	`none`	Name of the cookie containing a token. This property is effective only if `smallrye.jwt.token.header` is set to `Cookie`. This property is deprecated - use `mp.jwt.token.cookie`.
`smallrye.jwt.always-check-authorization`	`false`	Set this property to `true` for the `Authorization` header to be checked even if the `smallrye.jwt.token.header` is set to `Cookie` but no cookie with a `smallrye.jwt.token.cookie` name exists.
`smallrye.jwt.token.schemes`	`Bearer`	Comma-separated list containing alternative single or multiple schemes, such as `DPoP`.
`smallrye.jwt.token.kid`	`none`	Key identifier. The verification JWK key and every JWT token must have a matching `kid` header if it is set.
`smallrye.jwt.time-to-live`	`none`	The maximum number of seconds a JWT can be issued for use. Effectively, the difference between the expiration date of the JWT and the issued at date must not exceed this value. Setting this property to a non-positive value relaxes the requirement for the token to have a valid 'iat' (issued at) claim.
`smallrye.jwt.require.named-principal`	`true`	If an application relies on `java.security.Principal` returning a name, then a token must have a `upn` or `preferred_username` or `sub` claim set. Setting this property results in SmallRye JWT throwing an exception if none of these claims is available for the application code to deal with a non-null `Principal` name reliably.
`smallrye.jwt.path.sub`	`none`	Path to the claim containing the subject name. It starts from the top-level JSON object and can contain multiple segments where each segment only represents a JSON object name, for example, `realms/subject`. This property can be used if a token has no 'sub' claim but has the subject set in a different claim. Use double quotes with the namespace-qualified claims.
`smallrye.jwt.claims.sub`	`none`	This property can set a default sub claim value when the current token has no standard or custom `sub` claim available. Effectively, this property can be used to customize the `java.security.Principal` name if no `upn` or `preferred_username` or `sub` claim is set.
`smallrye.jwt.path.groups`	`none`	Path to the claim containing the groups. It starts from the top-level JSON object and can contain multiple segments where each segment represents a JSON object name only, for example: `realm/groups`. This property can be used if a token has no 'groups' claim but has the groups set in a different claim. Use double quotes with the namespace-qualified claims.
`smallrye.jwt.groups-separator`	`space`	Separator for splitting a string which might contain multiple group values. It is only used if the `smallrye.jwt.path.groups` property points to a custom claim with a string value. The default value is a single space because a standard OAuth2 `scope` claim might contain a space-separated sequence.
`smallrye.jwt.claims.groups`	`none`	This property can set a default groups claim value when the current token has no standard or custom groups claim available.
`smallrye.jwt.jwks.refresh-interval`	`60`	JWK cache refresh interval in minutes. It is ignored unless the `mp.jwt.verify.publickey.location` points to the HTTP or HTTPS URL-based JWK set and no HTTP `Cache-Control` response header with a positive `max-age` parameter value is returned from a JWK HTTPS endpoint.
`smallrye.jwt.jwks.forced-refresh-interval`	`30`	Forced JWK cache refresh interval in minutes, which is used to restrict the frequency of the forced refresh attempts that might happen when the token verification fails due to the cache having no JWK key with a `kid` property matching the current token’s `kid` header. It is ignored unless the `mp.jwt.verify.publickey.location` points to the HTTP or HTTPS URL-based JWK set.
`smallrye.jwt.expiration.grace`	`0`	Expiration grace in seconds. By default, an expired token is still accepted if the current time is no more than 1 min after the token expiry time. This property is deprecated. Use `mp.jwt.verify.clock.skew` instead.
`smallrye.jwt.verify.aud`	`none`	Comma-separated list of audiences a token `aud` claim might contain. This property is deprecated - use `mp.jwt.verify.audiences`.
`smallrye.jwt.required.claims`	`none`	Comma-separated list of the claims a token must contain.
`smallrye.jwt.decrypt.key.location`	`none`	Config property to specify the external or internal location of Private Decryption Key. This property is deprecated - use `mp.jwt.decrypt.key.location`.
`smallrye.jwt.decrypt.algorithm`	`RSA_OAEP`	Decryption algorithm.
`smallrye.jwt.decrypt.key`	`none`	Decryption key supplied as a string.
`smallrye.jwt.token.decryption.kid`	`none`	Decryption Key identifier. If it is set then the decryption JWK key as well every JWT token must have a matching `kid` header.
`smallrye.jwt.client.tls.certificate.path`	`none`	Path to TLS trusted certificate which might need to be configured if the keys have to be fetched over `HTTPS`.
`smallrye.jwt.client.tls.trust-all`	`false`	Trust all the hostnames. If the keys have to be fetched over `HTTPS` and this property is set to `true` then all the hostnames are trusted by default.
`smallrye.jwt.client.tls.hosts`	`none`	Set of trusted hostnames. If the keys have to be fetched over `HTTPS` and `smallrye.jwt.client.tls.trust-all` is set to `false` then this property can be used to configure the trusted hostnames.
`smallrye.jwt.http.proxy.host`	`none`	HTTP proxy host.
`smallrye.jwt.http.proxy.port`	`80`	HTTP proxy port.
`smallrye.jwt.keystore.type`	`JKS`	This property can be used to customize a keystore type if either `mp.jwt.verify.publickey.location` or `mp.jwt.decrypt.key.location` points to a `KeyStore` file. If it is not set, the file name is checked to determine the keystore type before defaulting to `JKS`.
`smallrye.jwt.keystore.provider`		This property can be used to customize a `KeyStore` provider if `mp.jwt.verify.publickey.location` or `mp.jwt.decrypt.key.location` points to a `KeyStore` file.
`smallrye.jwt.keystore.password`		Keystore password. If `mp.jwt.verify.publickey.location` or `mp.jwt.decrypt.key.location`, this property must be set.
`smallrye.jwt.keystore.verify.key.alias`		This property has to be set to identify a public verification key which is extracted from `KeyStore` from a matching certificate if `mp.jwt.verify.publickey.location` points to a `KeyStore` file.
`smallrye.jwt.keystore.decrypt.key.alias`		This property has to be set to identify a private decryption key if `mp.jwt.decrypt.key.location` points to a `KeyStore` file.
`smallrye.jwt.keystore.decrypt.key.password`		This property can be set if a private decryption key’s password in `KeyStore` is different from `smallrye.jwt.keystore.password` when `mp.jwt.decrypt.key.location` points to a `KeyStore` file.
`smallrye.jwt.resolve-remote-keys-at-startup`	`false`	Set this property to true to resolve the remote keys at the application startup.

1.5. References
Copy link

Chapter 2. Build, sign, and encrypt JSON Web Tokens
Copy link

JSON Web Token (JWT) is defined by the RFC 7519 specification as a compact, URL-safe means of representing claims. These claims are encoded as a JSON object and can be used as the payload of a JSON Web Signature (JWS) structure or the plaintext of a JSON Web Encryption (JWE) structure. This mechanism enables claims to be digitally signed or protected for integrity with a Message Authentication Code (MAC) and encrypted.

Signing the claims is the most common method for securing them. Typically, a JWT token is produced by signing claims formatted as JSON, following the steps outlined in the JSON Web Signature (JWS) specification.

When the claims contain sensitive information, their confidentiality can be ensured by using the JSON Web Encryption (JWE) specification. This approach produces a JWT with encrypted claims.

For enhanced security, you can combine both methods: sign the claims first and then encrypt the resulting nested JWT. This process ensures both the confidentiality and integrity of the claims.

The SmallRye JWT Build API simplifies securing JWT claims by supporting all these options. It uses the Jose4J library internally to provide this functionality.

2.1. Dependency
Copy link

To use the SmallRye JWT Build API, add the following dependency to your project:

Using Maven:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-jwt-build</artifactId>
</dependency>

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-jwt-build</artifactId>
</dependency>

Copy to Clipboard

Toggle word wrap

Using Gradle:

implementation("io.quarkus:quarkus-smallrye-jwt-build")

implementation("io.quarkus:quarkus-smallrye-jwt-build")

Copy to Clipboard

Toggle word wrap

You can use the SmallRye JWT Build API independently, without creating MicroProfile JWT endpoints supported by the quarkus-smallrye-jwt extension.

2.2. Create JwtClaimsBuilder and set the claims
Copy link

The first step is to initialize a JwtClaimsBuilder by using one of the following options and add some claims to it:

import java.util.Collections;
import jakarta.json.Json;
import jakarta.json.JsonObject;
import io.smallrye.jwt.build.Jwt;
import io.smallrye.jwt.build.JwtClaimsBuilder;
import org.eclipse.microprofile.jwt.JsonWebToken;
...
// Create an empty builder and add some claims
JwtClaimsBuilder builder1 = Jwt.claims();
builder1.claim("customClaim", "custom-value").issuer("https://issuer.org");
// Alternatively, start with claims directly:
// JwtClaimsBuilder builder1 = Jwt.upn("Alice");

// Create a builder from an existing claims file
JwtClaimsBuilder builder2 = Jwt.claims("/tokenClaims.json");

// Create a builder from a map of claims
JwtClaimsBuilder builder3 = Jwt.claims(Collections.singletonMap("customClaim", "custom-value"));

// Create a builder from a JsonObject
JsonObject userName = Json.createObjectBuilder().add("username", "Alice").build();
JsonObject userAddress = Json.createObjectBuilder().add("city", "someCity").add("street", "someStreet").build();
JsonObject json = Json.createObjectBuilder(userName).add("address", userAddress).build();
JwtClaimsBuilder builder4 = Jwt.claims(json);

// Create a builder from a JsonWebToken
@Inject JsonWebToken token;
JwtClaimsBuilder builder5 = Jwt.claims(token);

import java.util.Collections;
import jakarta.json.Json;
import jakarta.json.JsonObject;
import io.smallrye.jwt.build.Jwt;
import io.smallrye.jwt.build.JwtClaimsBuilder;
import org.eclipse.microprofile.jwt.JsonWebToken;
...
// Create an empty builder and add some claims
JwtClaimsBuilder builder1 = Jwt.claims();
builder1.claim("customClaim", "custom-value").issuer("https://issuer.org");
// Alternatively, start with claims directly:
// JwtClaimsBuilder builder1 = Jwt.upn("Alice");

// Create a builder from an existing claims file
JwtClaimsBuilder builder2 = Jwt.claims("/tokenClaims.json");

// Create a builder from a map of claims
JwtClaimsBuilder builder3 = Jwt.claims(Collections.singletonMap("customClaim", "custom-value"));

// Create a builder from a JsonObject
JsonObject userName = Json.createObjectBuilder().add("username", "Alice").build();
JsonObject userAddress = Json.createObjectBuilder().add("city", "someCity").add("street", "someStreet").build();
JsonObject json = Json.createObjectBuilder(userName).add("address", userAddress).build();
JwtClaimsBuilder builder4 = Jwt.claims(json);

// Create a builder from a JsonWebToken
@Inject JsonWebToken token;
JwtClaimsBuilder builder5 = Jwt.claims(token);

Copy to Clipboard

Toggle word wrap

The API is fluent so you can initialize the builder as part of a fluent sequence.

The builder automatically sets the following claims if they are not explicitly configured:

iat (issued at): Current time
exp (expires at): Five minutes from the current time (customizable with the smallrye.jwt.new-token.lifespan property)
jti (unique token identifier)

You can configure the following properties globally to avoid setting them directly in the builder:

smallrye.jwt.new-token.issuer: Specifies the default issuer.
smallrye.jwt.new-token.audience: Specifies the default audience.

After initializing and setting claims, the next step is to decide how to secure the claims.

2.3. Sign the claims
Copy link

You can sign the claims immediately or after configuring the JSON Web Signature (JWS) headers:

import io.smallrye.jwt.build.Jwt;
...

// Sign the claims using an RSA private key loaded from the location specified by the 'smallrye.jwt.sign.key.location' property.
// No 'jws()' transition is required. The default algorithm is RS256.
String jwt1 = Jwt.claims("/tokenClaims.json").sign();

// Set the headers and sign the claims by using an RSA private key loaded in the code (the implementation of this method is omitted).
// Includes a 'jws()' transition to a 'JwtSignatureBuilder'. The default algorithm is RS256.

String jwt2 = Jwt.claims("/tokenClaims.json")
                 .jws()
                 .keyId("kid1")
                 .header("custom-header", "custom-value")
                 .sign(getPrivateKey());

import io.smallrye.jwt.build.Jwt;
...

// Sign the claims using an RSA private key loaded from the location specified by the 'smallrye.jwt.sign.key.location' property.
// No 'jws()' transition is required. The default algorithm is RS256.
String jwt1 = Jwt.claims("/tokenClaims.json").sign();

// Set the headers and sign the claims by using an RSA private key loaded in the code (the implementation of this method is omitted).
// Includes a 'jws()' transition to a 'JwtSignatureBuilder'. The default algorithm is RS256.

String jwt2 = Jwt.claims("/tokenClaims.json")
                 .jws()
                 .keyId("kid1")
                 .header("custom-header", "custom-value")
                 .sign(getPrivateKey());

Copy to Clipboard

Toggle word wrap

Default behaviors:

The alg (algorithm) header is set to RS256 by default.
You do not have to set a signing key identifier (kid header) if a single JSON Web Key (JWK) containing a kid property is used.

Supported keys and algorithms:

To sign the claims, you can use RSA private keys, Elliptic Curve (EC) private keys, and symmetric secret keys.
RS256 is the default RSA private key signature algorithm.
ES256 is the default EC private key signature algorithm.
HS256 is the default symmetric key signature algorithm.

To customize the signature algorithm, use the JwtSignatureBuilder API. For example:

import io.smallrye.jwt.SignatureAlgorithm;
import io.smallrye.jwt.build.Jwt;

// Sign the claims using an RSA private key loaded from the location set with a 'smallrye.jwt.sign.key.location' property. The algorithm is PS256.
String jwt = Jwt.upn("Alice").jws().algorithm(SignatureAlgorithm.PS256).sign();

import io.smallrye.jwt.SignatureAlgorithm;
import io.smallrye.jwt.build.Jwt;

// Sign the claims using an RSA private key loaded from the location set with a 'smallrye.jwt.sign.key.location' property. The algorithm is PS256.
String jwt = Jwt.upn("Alice").jws().algorithm(SignatureAlgorithm.PS256).sign();

Copy to Clipboard

Toggle word wrap

Alternatively, you can configure the signature algorithm globally with the following property:

smallrye.jwt.new-token.signature-algorithm=PS256

smallrye.jwt.new-token.signature-algorithm=PS256

Copy to Clipboard

Toggle word wrap

This approach gives you a simpler API sequence:

import io.smallrye.jwt.build.Jwt;

// Sign the claims using an RSA private key loaded from the location set with a 'smallrye.jwt.sign.key.location' property. The algorithm is PS256.
String jwt = Jwt.upn("Alice").sign();

import io.smallrye.jwt.build.Jwt;

// Sign the claims using an RSA private key loaded from the location set with a 'smallrye.jwt.sign.key.location' property. The algorithm is PS256.
String jwt = Jwt.upn("Alice").sign();

Copy to Clipboard

Toggle word wrap

You can combine the sign step with the encrypt step to create inner-signed and encrypted tokens. For more information, see the Sign the claims and encrypt the nested JWT token section.

2.4. Encrypt the claims
Copy link

You can encrypt claims immediately or after setting the JSON Web Encryption (JWE) headers, similar to how claims are signed. However, encrypting claims always requires a jwe() transition to a JwtEncryptionBuilder because the API is optimized to support signing and inner-signing operations.

import io.smallrye.jwt.build.Jwt;
...

// Encrypt the claims using an RSA public key loaded from the location specified by the 'smallrye.jwt.encrypt.key.location' property.
// The default key encryption algorithm is RSA-OAEP.

String jwt1 = Jwt.claims("/tokenClaims.json").jwe().encrypt();

// Set the headers and encrypt the claims by using an RSA public key loaded in the code (the implementation of this method is omitted).
// The default key encryption algorithm is A256KW.
String jwt2 = Jwt.claims("/tokenClaims.json").jwe().header("custom-header", "custom-value").encrypt(getSecretKey());

import io.smallrye.jwt.build.Jwt;
...

// Encrypt the claims using an RSA public key loaded from the location specified by the 'smallrye.jwt.encrypt.key.location' property.
// The default key encryption algorithm is RSA-OAEP.

String jwt1 = Jwt.claims("/tokenClaims.json").jwe().encrypt();

// Set the headers and encrypt the claims by using an RSA public key loaded in the code (the implementation of this method is omitted).
// The default key encryption algorithm is A256KW.
String jwt2 = Jwt.claims("/tokenClaims.json").jwe().header("custom-header", "custom-value").encrypt(getSecretKey());

Copy to Clipboard

Toggle word wrap

Default behaviors:

The alg (key management algorithm) header defaults to RSA-OAEP.
The enc (content encryption) header defaults to A256GCM.

Supported keys and algorithms:

You can use RSA public keys, Elliptic Curve (EC) public keys, and symmetric secret keys, to encrypt the claims.
RSA-OAEP is the default RSA public key encryption algorithm.
ECDH-ES is the default EC public key encryption algorithm.
A256KW is the default symmetric key encryption algorithm.

Note two encryption operations are done when creating an encrypted token:

The generated content encryption key is encrypted using the supplied key and a key encryption algorithm such as RSA-OAEP.
The claims are encrypted using the content encryption key and a content encryption algorithm such as A256GCM.

You can customize the key and content encryption algorithms by using the JwtEncryptionBuilder API. For example:

import io.smallrye.jwt.KeyEncryptionAlgorithm;
import io.smallrye.jwt.ContentEncryptionAlgorithm;
import io.smallrye.jwt.build.Jwt;

// Encrypt the claims using an RSA public key loaded from the location set with a 'smallrye.jwt.encrypt.key.location' property.
// Key encryption algorithm is RSA-OAEP-256. The content encryption algorithm is A256CBC-HS512.

String jwt = Jwt.subject("Bob").jwe()
    .keyAlgorithm(KeyEncryptionAlgorithm.RSA_OAEP_256)
    .contentAlgorithm(ContentEncryptionAlgorithm.A256CBC_HS512)
    .encrypt();

import io.smallrye.jwt.KeyEncryptionAlgorithm;
import io.smallrye.jwt.ContentEncryptionAlgorithm;
import io.smallrye.jwt.build.Jwt;

// Encrypt the claims using an RSA public key loaded from the location set with a 'smallrye.jwt.encrypt.key.location' property.
// Key encryption algorithm is RSA-OAEP-256. The content encryption algorithm is A256CBC-HS512.

String jwt = Jwt.subject("Bob").jwe()
    .keyAlgorithm(KeyEncryptionAlgorithm.RSA_OAEP_256)
    .contentAlgorithm(ContentEncryptionAlgorithm.A256CBC_HS512)
    .encrypt();

Copy to Clipboard

Toggle word wrap

Alternatively, you can configure the algorithms globally by using the following properties:

smallrye.jwt.new-token.key-encryption-algorithm=RSA-OAEP-256
smallrye.jwt.new-token.content-encryption-algorithm=A256CBC-HS512

smallrye.jwt.new-token.key-encryption-algorithm=RSA-OAEP-256
smallrye.jwt.new-token.content-encryption-algorithm=A256CBC-HS512

Copy to Clipboard

Toggle word wrap

This configuration allows for a simpler API sequence:

import io.smallrye.jwt.build.Jwt;

// Encrypt the claims by using an RSA public key loaded from the location set with a 'smallrye.jwt.encrypt.key.location' property.
// Key encryption algorithm is RSA-OAEP-256. The content encryption algorithm is A256CBC-HS512.
String jwt = Jwt.subject("Bob").encrypt();

import io.smallrye.jwt.build.Jwt;

// Encrypt the claims by using an RSA public key loaded from the location set with a 'smallrye.jwt.encrypt.key.location' property.
// Key encryption algorithm is RSA-OAEP-256. The content encryption algorithm is A256CBC-HS512.
String jwt = Jwt.subject("Bob").encrypt();

Copy to Clipboard

Toggle word wrap

Recommendations for secure token encryption:

When a token is directly encrypted with a public RSA or EC key, it cannot be verified which party sent the token. To address this, symmetric secret keys are preferred for direct encryption, especially when using JWT as cookies managed solely by the Quarkus endpoint.
To encrypt a token with RSA or EC public keys, it is recommended to sign the token first if a signing key is available. For more information, see the Sign the claims and encrypt the nested JWT token section.

2.5. Sign the claims and encrypt the nested JWT token
Copy link

You can sign the claims and then encrypt the nested JWT token by combining the sign and encrypt steps.

import io.smallrye.jwt.build.Jwt;
...

// Sign the claims and encrypt the nested token using the private and public keys loaded from the locations
// specified by the 'smallrye.jwt.sign.key.location' and 'smallrye.jwt.encrypt.key.location' properties, respectively.
// The signature algorithm is RS256, and the key encryption algorithm is RSA-OAEP-256.
String jwt = Jwt.claims("/tokenClaims.json").innerSign().encrypt();

import io.smallrye.jwt.build.Jwt;
...

// Sign the claims and encrypt the nested token using the private and public keys loaded from the locations
// specified by the 'smallrye.jwt.sign.key.location' and 'smallrye.jwt.encrypt.key.location' properties, respectively.
// The signature algorithm is RS256, and the key encryption algorithm is RSA-OAEP-256.
String jwt = Jwt.claims("/tokenClaims.json").innerSign().encrypt();

Copy to Clipboard

Toggle word wrap

2.6. Fast JWT generation
Copy link

If the smallrye.jwt.sign.key.location or smallrye.jwt.encrypt.key.location properties are set, you can secure existing claims, such as resources, maps, JsonObjects, with a single call:

// More compact than Jwt.claims("/claims.json").sign();
Jwt.sign("/claims.json");

// More compact than Jwt.claims("/claims.json").jwe().encrypt();
Jwt.encrypt("/claims.json");

// More compact than Jwt.claims("/claims.json").innerSign().encrypt();
Jwt.signAndEncrypt("/claims.json");

// More compact than Jwt.claims("/claims.json").sign();
Jwt.sign("/claims.json");

// More compact than Jwt.claims("/claims.json").jwe().encrypt();
Jwt.encrypt("/claims.json");

// More compact than Jwt.claims("/claims.json").innerSign().encrypt();
Jwt.signAndEncrypt("/claims.json");

Copy to Clipboard

Toggle word wrap

As mentioned earlier, the following claims are added automatically if they are not already set: iat (issued at), exp (expires at), jti (token identifier), iss (issuer), and aud (audience).

2.7. Dealing with the keys
Copy link

You can use the smallrye.jwt.sign.key.location and smallrye.jwt.encrypt.key.location properties to specify the locations of signing and encryption keys. These keys can be located on the local file system, on the classpath, or fetched from remote endpoints. Keys can be in PEM or JSON Web Key (JWK) formats. For example:

smallrye.jwt.sign.key.location=privateKey.pem
smallrye.jwt.encrypt.key.location=publicKey.pem

smallrye.jwt.sign.key.location=privateKey.pem
smallrye.jwt.encrypt.key.location=publicKey.pem

Copy to Clipboard

Toggle word wrap

Alternatively, you can fetch keys from external services, such as HashiCorp Vault or other secret managers, by using MicroProfile ConfigSource and the smallrye.jwt.sign.key and smallrye.jwt.encrypt.key properties:

smallrye.jwt.sign.key=${private.key.from.vault}
smallrye.jwt.encrypt.key=${public.key.from.vault}

smallrye.jwt.sign.key=${private.key.from.vault}
smallrye.jwt.encrypt.key=${public.key.from.vault}

Copy to Clipboard

Toggle word wrap

In this example, private.key.from.vault and public.key.from.vault are PEM or JWK formatted key values provided by the custom ConfigSource.

The smallrye.jwt.sign.key and smallrye.jwt.encrypt.key properties can also contain Base64-encoded private or public key values directly.

However, be aware that directly inlining private keys in the configuration is not recommended. Use the smallrye.jwt.sign.key property only when you need to fetch a signing key value from a remote secret manager.

The keys can also be loaded by the code that builds the token, and then supplied to JWT Build API for token creation.

If you need to sign or encrypt the token by using the symmetric secret key, consider using io.smallrye.jwt.util.KeyUtils to generate a SecretKey of the required length.

For example, a 64-byte key is required to sign a token by using the HS512 algorithm (512/8), and a 32-byte key is needed to encrypt the content encryption key with the A256KW algorithm (256/8):

import javax.crypto.SecretKey;
import io.smallrye.jwt.KeyEncryptionAlgorithm;
import io.smallrye.jwt.SignatureAlgorithm;
import io.smallrye.jwt.build.Jwt;
import io.smallrye.jwt.util.KeyUtils;

SecretKey signingKey = KeyUtils.generateSecretKey(SignatureAlgorithm.HS512);
SecretKey encryptionKey = KeyUtils.generateSecretKey(KeyEncryptionAlgorithm.A256KW);
String jwt = Jwt.claim("sensitiveClaim", getSensitiveClaim()).innerSign(signingKey).encrypt(encryptionKey);

import javax.crypto.SecretKey;
import io.smallrye.jwt.KeyEncryptionAlgorithm;
import io.smallrye.jwt.SignatureAlgorithm;
import io.smallrye.jwt.build.Jwt;
import io.smallrye.jwt.util.KeyUtils;

SecretKey signingKey = KeyUtils.generateSecretKey(SignatureAlgorithm.HS512);
SecretKey encryptionKey = KeyUtils.generateSecretKey(KeyEncryptionAlgorithm.A256KW);
String jwt = Jwt.claim("sensitiveClaim", getSensitiveClaim()).innerSign(signingKey).encrypt(encryptionKey);

Copy to Clipboard

Toggle word wrap

You can also consider using a JSON Web Key (JWK) or JSON Web Key Set (JWK Set) format to store a secret key on a secure file system. You can reference the key by using the smallrye.jwt.sign.key.location or smallrye.jwt.encrypt.key.location properties.

Example JWK

{
 "kty":"oct",
 "kid":"secretKey",
 "k":"Fdh9u8rINxfivbrianbbVT1u232VQBZYKx1HGAGPt2I"
}

{
 "kty":"oct",
 "kid":"secretKey",
 "k":"Fdh9u8rINxfivbrianbbVT1u232VQBZYKx1HGAGPt2I"
}

Copy to Clipboard

Toggle word wrap

Example JWK Set

{
 "keys": [
   {
     "kty":"oct",
     "kid":"secretKey1",
     "k":"Fdh9u8rINxfivbrianbbVT1u232VQBZYKx1HGAGPt2I"
   },
   {
     "kty":"oct",
     "kid":"secretKey2",
     "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"
   }
 ]
}

{
 "keys": [
   {
     "kty":"oct",
     "kid":"secretKey1",
     "k":"Fdh9u8rINxfivbrianbbVT1u232VQBZYKx1HGAGPt2I"
   },
   {
     "kty":"oct",
     "kid":"secretKey2",
     "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"
   }
 ]
}

Copy to Clipboard

Toggle word wrap

You can also use io.smallrye.jwt.util.KeyUtils to generate a pair of asymmetric RSA or EC keys. These keys can be stored in JWK, JWK Set, or PEM format.

2.8. SmallRye JWT Builder configuration
Copy link

SmallRye JWT supports the following properties, which can be used to customize how claims are signed or encrypted:

Expand

Property Name	Default	Description
`smallrye.jwt.sign.key.location`	`none`	Location of a private key used to sign the claims when either a no-argument `sign()` or `innerSign()` method is called.
`smallrye.jwt.sign.key`	`none`	Key value used to sign the claims when either a no-argument `sign()` or `innerSign()` method is called.
`smallrye.jwt.sign.key.id`	`none`	Signing key identifier, checked only when JWK keys are used.
`smallrye.jwt.encrypt.key.location`	`none`	Location of the public key used to encrypt claims or the inner JWT when the no-argument `encrypt()` method is called.
`smallrye.jwt.sign.relax-key-validation`	`false`	Relax the validation of the signing keys.
`smallrye.jwt.encrypt.key`	`none`	Key value used to encrypt the claims or the inner JWT when a no-argument `encrypt()` method is called.
`smallrye.jwt.encrypt.key.id`	`none`	Encryption key identifier, checked only when JWK keys are used.
`smallrye.jwt.encrypt.relax-key-validation`	`false`	Relax the validation of the encryption keys.
`smallrye.jwt.new-token.signature-algorithm`	`RS256`	Signature algorithm. Checked if the JWT signature builder has not already set the signature algorithm.
`smallrye.jwt.new-token.key-encryption-algorithm`	`RSA-OAEP`	Key encryption algorithm. Checked if the JWT encryption builder has not already set the key encryption algorithm.
`smallrye.jwt.new-token.content-encryption-algorithm`	`A256GCM`	Content encryption algorithm. Checked if the JWT encryption builder has not already set the content encryption algorithm.
`smallrye.jwt.new-token.lifespan`	`300`	Token lifespan in seconds used to calculate an `exp` (expiry) claim value if this claim has not already been set.
`smallrye.jwt.new-token.issuer`	`none`	Token issuer used to set an `iss` (issuer) claim value if this claim has not already been set.
`smallrye.jwt.new-token.audience`	`none`	Token audience used to set an `aud` (audience) claim value if this claim has not already been set.
`smallrye.jwt.new-token.override-matching-claims`	`false`	Set this property to `true` for `smallrye.jwt.new-token.issuer` and `smallrye.jwt.new-token.audience` values to override the already initialized `iss` (issuer) and `aud` (audience) claims.
`smallrye.jwt.new-token.add-default-claims`	`true`	Set this property to `false` to disable an automatic addition of the `iat` (issued at), `exp` (expiration time) and `jti` (token identifier) claims when such claims have not already been set.
`smallrye.jwt.keystore.type`	`JKS`	This property can be used to customize a keystore type if either `smallrye.jwt.sign.key.location` or `smallrye.jwt.encrypt.key.location` or both of these properties point to a `KeyStore` file. If it is not set then the file name will be checked to determine the keystore type before defaulting to `JKS`.
`smallrye.jwt.keystore.provider`		This property can be used to customize a `KeyStore` provider if `smallrye.jwt.sign.key.location` or `smallrye.jwt.encrypt.key.location` point to a `KeyStore` file.
`smallrye.jwt.keystore.password`		Keystore password. If `smallrye.jwt.sign.key.location` or `smallrye.jwt.encrypt.key.location` point to a `KeyStore` file, this property must be set.
`smallrye.jwt.keystore.encrypt.key.alias`		This property must be set to identify the public encryption key that is extracted from `KeyStore` from a matching certificate if `smallrye.jwt.encrypt.key.location` points to a `KeyStore` file.
`smallrye.jwt.keystore.sign.key.alias`		This property must be set to identify a private signing key if `smallrye.jwt.sign.key.location` points to a `KeyStore` file.
`smallrye.jwt.keystore.sign.key.password`		This property can be set if a private signing key’s password in `KeyStore` is different from `smallrye.jwt.keystore.password` when `smallrye.jwt.sign.key.location` points to a `KeyStore` file.

2.9. References
Copy link

Legal Notice
Copy link

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Microprofile JSON Web Token (JWT) authentication

Chapter 1. Using JWT RBACCopy linkLink copied to clipboard!

1.1. PrerequisitesCopy linkLink copied to clipboard!

1.2. QuickstartCopy linkLink copied to clipboard!

1.2.1. SolutionCopy linkLink copied to clipboard!

1.2.2. Creating the Maven projectCopy linkLink copied to clipboard!

1.2.3. Examine the Jakarta REST resourceCopy linkLink copied to clipboard!

1.2.4. Run the application in dev modeCopy linkLink copied to clipboard!

1.2.5. Configuring the SmallRye JWT extension security informationCopy linkLink copied to clipboard!

1.2.6. Adding a public keyCopy linkLink copied to clipboard!

1.2.7. Generating a JWTCopy linkLink copied to clipboard!

1.2.8. Finally, secured access to /secured/roles-allowedCopy linkLink copied to clipboard!

1.2.9. Using the JsonWebToken and claim injectionCopy linkLink copied to clipboard!

1.2.10. Run the application in JVM modeCopy linkLink copied to clipboard!

1.2.11. Run the application in native modeCopy linkLink copied to clipboard!

1.2.12. Explore the solutionCopy linkLink copied to clipboard!

1.3. Reference guideCopy linkLink copied to clipboard!

1.3.1. Supported injection scopesCopy linkLink copied to clipboard!

1.3.2. Supported public key formatsCopy linkLink copied to clipboard!

1.3.3. Dealing with verification keysCopy linkLink copied to clipboard!

1.3.4. Parse and verify JsonWebToken with JWTParserCopy linkLink copied to clipboard!

1.3.5. Token decryptionCopy linkLink copied to clipboard!

1.3.6. Custom factoriesCopy linkLink copied to clipboard!

1.3.7. Blocking callsCopy linkLink copied to clipboard!

1.3.8. Token propagationCopy linkLink copied to clipboard!

1.3.9. TestingCopy linkLink copied to clipboard!

1.3.9.1. Automatic key generationCopy linkLink copied to clipboard!

1.3.9.2. WiremockCopy linkLink copied to clipboard!

1.3.9.3. KeycloakCopy linkLink copied to clipboard!

1.3.9.4. Local public keyCopy linkLink copied to clipboard!

1.3.9.5. TestSecurity annotationCopy linkLink copied to clipboard!

1.3.10. How to check the errors in the logsCopy linkLink copied to clipboard!

1.3.11. Proactive authenticationCopy linkLink copied to clipboard!

1.3.12. How to add SmallRye JWT directlyCopy linkLink copied to clipboard!

1.4. Configuration referenceCopy linkLink copied to clipboard!

1.4.1. Quarkus configurationCopy linkLink copied to clipboard!

1.4.2. MicroProfile JWT configurationCopy linkLink copied to clipboard!

1.4.3. Additional SmallRye JWT configurationCopy linkLink copied to clipboard!

1.5. ReferencesCopy linkLink copied to clipboard!

Chapter 2. Build, sign, and encrypt JSON Web TokensCopy linkLink copied to clipboard!

2.1. DependencyCopy linkLink copied to clipboard!

2.2. Create JwtClaimsBuilder and set the claimsCopy linkLink copied to clipboard!

2.3. Sign the claimsCopy linkLink copied to clipboard!

2.4. Encrypt the claimsCopy linkLink copied to clipboard!

2.5. Sign the claims and encrypt the nested JWT tokenCopy linkLink copied to clipboard!

2.6. Fast JWT generationCopy linkLink copied to clipboard!

2.7. Dealing with the keysCopy linkLink copied to clipboard!

2.8. SmallRye JWT Builder configurationCopy linkLink copied to clipboard!

2.9. ReferencesCopy linkLink copied to clipboard!

Legal NoticeCopy linkLink copied to clipboard!

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 1. Using JWT RBAC
Copy link

1.1. Prerequisites
Copy link

1.2. Quickstart
Copy link

1.2.1. Solution
Copy link

1.2.2. Creating the Maven project
Copy link

1.2.3. Examine the Jakarta REST resource
Copy link

1.2.4. Run the application in dev mode
Copy link

1.2.5. Configuring the SmallRye JWT extension security information
Copy link

1.2.6. Adding a public key
Copy link

1.2.7. Generating a JWT
Copy link

1.2.8. Finally, secured access to /secured/roles-allowed
Copy link

1.2.9. Using the JsonWebToken and claim injection
Copy link

1.2.10. Run the application in JVM mode
Copy link

1.2.11. Run the application in native mode
Copy link

1.2.12. Explore the solution
Copy link

1.3. Reference guide
Copy link

1.3.1. Supported injection scopes
Copy link

1.3.2. Supported public key formats
Copy link

1.3.3. Dealing with verification keys
Copy link

1.3.4. Parse and verify JsonWebToken with JWTParser
Copy link

1.3.5. Token decryption
Copy link

1.3.6. Custom factories
Copy link

1.3.7. Blocking calls
Copy link

1.3.8. Token propagation
Copy link

1.3.9. Testing
Copy link

1.3.9.1. Automatic key generation
Copy link

1.3.9.2. Wiremock
Copy link

1.3.9.3. Keycloak
Copy link

1.3.9.4. Local public key
Copy link

1.3.9.5. TestSecurity annotation
Copy link

1.3.10. How to check the errors in the logs
Copy link

1.3.11. Proactive authentication
Copy link

1.3.12. How to add SmallRye JWT directly
Copy link

1.4. Configuration reference
Copy link

1.4.1. Quarkus configuration
Copy link

1.4.2. MicroProfile JWT configuration
Copy link

1.4.3. Additional SmallRye JWT configuration
Copy link

1.5. References
Copy link

Chapter 2. Build, sign, and encrypt JSON Web Tokens
Copy link

2.1. Dependency
Copy link

2.2. Create JwtClaimsBuilder and set the claims
Copy link

2.3. Sign the claims
Copy link

2.4. Encrypt the claims
Copy link

2.5. Sign the claims and encrypt the nested JWT token
Copy link

2.6. Fast JWT generation
Copy link

2.7. Dealing with the keys
Copy link

2.8. SmallRye JWT Builder configuration
Copy link

2.9. References
Copy link

Legal Notice
Copy link