Jakarta EE Tutorials, MicroProfile Tutorials

MicroProfile JWT Auth to secure your applications

Last Updated: October 11, 2020 | Published: September 6, 2019

In today's microservice architecture security is usually based on the following protocols: OAuth2, OpenID Connect, and SAML. These main security protocols use security tokens to propagate the security state from client to server. This stateless approach is usually achieved by passing a JWT token alongside every client request. For convenient use of this kind of token-based authentication, the Eclipse MicroProfile JWT Auth evolved. The specification ensures, that the security token is extracted from the request, validated and a security context is created out of the extracted information.

Learn more about the MicroProfile JWT Auth specification, its annotations, and how to use it in this blog post.

Specification profile: MicroProfile JWT Auth

Current version: 1.1 in MicroProfile
GitHub repository
Latest specification document
Basic use case: Provide JWT token-based authentication for your application

Securing a JAX-RS application

First, we have to instruct our JAX-RS application, that we'll use the JWTs for authentication and authorization. You can configure this with the @LoginConfig annotation:

@ApplicationPath("resources")
@LoginConfig(authMethod = "MP-JWT")
public class JAXRSConfiguration extends Application {
}

@ApplicationPath("resources")

@LoginConfig(authMethod = "MP-JWT")

public class JAXRSConfiguration extends Application {

}

Once an incoming request has a valid JWT within the HTTP Bearer header, the groups in the JWT are mapped to roles.

We can now limit the access for a resource to specific roles and achieve authorization with the Common Security Annotations (JSR-250) (@RolesAllowed, @PermitAll, @DenyAll):

@GET
@RolesAllowed("admin")
public Response getBook() {

    JsonObject secretBook = Json.createObjectBuilder()
        .add("title", "secret")
        .add("author", "duke")
        .build();

    return Response.ok(secretBook).build();
}

@GET

@RolesAllowed("admin")

public Response getBook() {

JsonObject secretBook = Json.createObjectBuilder()

.add("title", "secret")

.add("author", "duke")

.build();

return Response.ok(secretBook).build();

}

Furthermore, we can inject the actual JWT token (alongside the Principal) with CDI and inject any claim of the JWT in addition:

@Path("books")
@RequestScoped
@Produces(MediaType.APPLICATION_JSON)
public class BookResource {

    @Inject
    private Principal principal;

    @Inject
    private JsonWebToken jsonWebToken;

    @Inject
    @Claim("administrator_id")
    private JsonNumber administrator_id;

    @GET
    @RolesAllowed("admin")
    public Response getBook() {

        System.out.println("Secret book for " + principal.getName()
                + " with roles " + jsonWebToken.getGroups());
        System.out.println("Administrator level: "
                + jsonWebToken.getClaim("administrator_level").toString());
        System.out.println("Administrator id: " + administrator_id);

        JsonObject secretBook = Json.createObjectBuilder()
                .add("title", "secret")
                .add("author", "duke")
                .build();

        return Response.ok(secretBook).build();
    }

}

@Path("books")

@RequestScoped

@Produces(MediaType.APPLICATION_JSON)

public class BookResource {

@Inject

private Principal principal;

@Inject

private JsonWebToken jsonWebToken;

@Inject

@Claim("administrator_id")

private JsonNumber administrator_id;

@GET

@RolesAllowed("admin")

public Response getBook() {

System.out.println("Secret book for " + principal.getName()

+ " with roles " + jsonWebToken.getGroups());

System.out.println("Administrator level: "

+ jsonWebToken.getClaim("administrator_level").toString());

System.out.println("Administrator id: " + administrator_id);

JsonObject secretBook = Json.createObjectBuilder()

.add("title", "secret")

.add("author", "duke")

.build();

return Response.ok(secretBook).build();

}

In this example, I'm injecting the claim administrator_id and access the claim administrator_level via the JWT token. These are not part of the standard JWT claims but you can add any additional metadata in your token.

Always make sure to only inject the JWT token and the claims to @RequestScoped CDI beans, as you'll get a DeploymentExcpetion otherwise:

javax.enterprise.inject.spi.DeploymentException: CWWKS5603E: The claim cannot be injected into the [BackedAnnotatedField] @Inject @Claim private de.rieckpil.blog.BookResource.administrator_id injection point for the ApplicationScoped or SessionScoped scopes.
        at com.ibm.ws.security.mp.jwt.cdi.JwtCDIExtension.processInjectionTarget(JwtCDIExtension.java:92)
        at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
        at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)

javax.enterprise.inject.spi.DeploymentException: CWWKS5603E: The claim cannot be injected into the [BackedAnnotatedField] @Inject @Claim private de.rieckpil.blog.BookResource.administrator_id injection point for the ApplicationScoped or SessionScoped scopes.

at com.ibm.ws.security.mp.jwt.cdi.JwtCDIExtension.processInjectionTarget(JwtCDIExtension.java:92)

at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)

at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)

at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)

HINT: Depending on the application server you'll deploy this example, you might have to first declare the available roles with @DeclareRoles({"admin", "chief", "duke"}).

Required configuration for MicroProfile JWT Auth

Achieving validation of the JWT signature requires the public key. Since MicroProfile JWT Auth 1.1, we can configure this with MicroProfile Config (previously it was vendor-specific). The JWT Auth specification allows the following public key formats:

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

For this example, I'm using the PKCS#8 format and specify the path of the .pem file containing the public key in the microprofile-config.properties file:

mp.jwt.verify.publickey.location=/META-INF/publicKey.pem
mp.jwt.verify.issuer=rieckpil

1 2	mp.jwt.verify.publickey.location=/META-INF/publicKey.pem mp.jwt.verify.issuer=rieckpil

The configuration of the issuer is also required and has to match the iss claim in the JWT. A valid publicKey.pem file might look like the following:

-----BEGIN RSA PUBLIC KEY-----
YOUR_PUBLIC_KEY
-----END RSA PUBLIC KEY-----

-----BEGIN RSA PUBLIC KEY-----

YOUR_PUBLIC_KEY

-----END RSA PUBLIC KEY-----

Using JWTEnizer to create tokens for testing

Usually, an identity provider (e.g. Keycloak) issues a JWT. For quick testing, we can use the JWTenizer tool from Adam Bien. This provides a simple way to create a valid JWT token and generates the corresponding public and private keys. Once you downloaded the jwtenizer.jar you can run it for the first time with the following command:

java -jar jwtenizer.jar

1	java -jar jwtenizer.jar

This will now create a jwt-token.json file in the folder you executed the command above. We can adjust this .json file to our needs and model a sample JWT token:

{
  "iss": "rieckpil",
  "jti": "42",
  "sub": "duke",
  "upn": "duke",
  "groups": [
    "chief",
    "hacker",
    "admin"
  ],
  "administrator_id": 42,
  "administrator_level": "HIGH"
}

{

"iss": "rieckpil",

"jti": "42",

"sub": "duke",

"upn": "duke",

"groups": [

"chief",

"hacker",

"admin"

"administrator_id": 42,

"administrator_level": "HIGH"

}

Once you adjusted the raw jwt-token.json, you can run java -jar jwtenizer.jar again and this second run will now pick the existing .json file for creating the JWT. Alongside the JWT token, the tool generates a microprofile-config.properties file, from which we can copy the public key and paste it to our publicKey.pem file.

Furthermore the shell output of running jwtenizer.jar contains a cURL command we can use to hit our resources:

curl -i -H'Authorization: Bearer GENERATED_JWT' http://localhost:9080/resources/books

1	curl -i -H'Authorization: Bearer GENERATED_JWT' http://localhost:9080/resources/books

With a valid Bearer header you should get the following response from the backend:

HTTP/1.1 200 OK
X-Powered-By: Servlet/4.0
Content-Type: application/json
Date: Fri, 06 Sep 2019 03:24:16 GMT
Content-Language: en-US
Content-Length: 34

{"title":"secret","author":"duke"}

HTTP/1.1 200 OK

X-Powered-By: Servlet/4.0

Content-Type: application/json

Date: Fri, 06 Sep 2019 03:24:16 GMT

Content-Language: en-US

Content-Length: 34

{"title":"secret","author":"duke"}

You can now adjust the jwt-token.json again and remove the admin group and generate a new JWT. With this generated token you shouldn't be able to get a response from the backend. Rather receive 403 Forbidden, as you are authenticated but don't have the correct role.

For further instructions on how to use this tool, have a look at the README on GitHub or the following video of Adam Bien.