Since this topic became very extensive, I decided to split up the blog into 4 parts. To keep blog lengths manageable. Here is the split up
Part 1: Introduction
Part 2: Payara, Spring Boot and Quarkus
Part 3: Ktor and Atbash Runtime (this one)
Part 4: Discussion and conclusion
For an introduction around JWT Tokens, you can have a look at the first part of this blog. It also contains a description how the Keycloak service is created for the example programs described in this part.
Part 2 contains the description for Payara Micro, Spring Boot and Quarkus.
Ktor
Also within Ktor there is some excellent support for using JWT tokens although we need to code a little bit more if we want to have support for rotating public keys and easy checks on the roles within the tokens.
But first, Let us start again with the dependencies you need within your application.
<!-- Ktor authentication -->
<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>
<!-- Ktor support for JWT -->
<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jwt-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>
We need a dependency to add the authentication support and another one for having the JWT token as the source for authentication and authorisation.
Just as with the Payara and Quarkus case, we need to define the location to retrieve the public key, expected issuer, and audience through the configuration of our application. In our example application, this is provided in the application.yml file.
jwt: issuer: "http://localhost:8888/auth/realms/atbash_project_ff" audience: "account"
We programmatically read these values in our own code, so the keys can be whatever you like, they are not predetermined as with the other runtimes. In the example, you see that we also don’t define the location of the public key endpoint as we can derive that from the issuer value in the case of KeyCloak. But you are free to specify a specific URL for this value of course.
Configuration of the modules in Ktor is commonly done by creating an extension function on Application object, as I have also done in this example. This is the general structure of this function
fun Application.configureSecurity() {
authentication {
jwt("jwt-auth") {
realm = "Atbash project FF"
// this@configureSecurity refers to Application.configureSecurity()
val issuer = this@configureSecurity.environment.config.property("jwt.issuer").getString()
val expectedAudience = this@configureSecurity.environment.config.property("jwt.audience").getString()
val jwkUrl = URL("$issuer/protocol/openid-connect/certs")
val jwkProvider = UrlJwkProvider(jwkUrl)
verifier {
// not shown for brevity
}
validate { credential ->
// If we need validation of the roles, use authorizeWithRoles
// We cannot define the roles that we need to be able to check this here.
JWTPrincipal(credential.payload)
}
challenge { defaultScheme, realm ->
// Response when verification fails
// Ideally should be a JSON payload that we sent back
call.respond(HttpStatusCode.Unauthorized, "$realm: Token is not valid or has expired")
}
}
}
}
The function jwt("jwt-auth") { indicates that we define an authentication protocol based on the JWT tokens and we name it jwt-auth. We can name it differently and can have even multiple protocols in the same application as long ask we correctly indicate which protocol name we want at the endpoint.
The JWT protocol in Ktor requires 3 parts, a verification part, a validation one, and lastly how the challenge is handled.
The verification part defines how the verification of the token is performed and will be discussed in more detail in a moment. We can do further validation on the token by looking at the roles that are in the token. If you have many different roles, this leads to many different named JWT protocols. Therefore I opted in this example to write another extension function on the Route object that handles this requirement more generically. And the challenge part is executed to formulate a response for the client in case the validation of the token failed.
The verifier method defines how the verification of the token is performed. We make use of the UrlJwkProvider which can read the keys in the JWKS format which contains keys in a JSON format. But it doesn’t try to reread the endpoint in case the key is not found. This also means we cannot apply rotating keys for signing the JWT tokens which is recommended in production. Therefore, we make use of a small helper which caches the keys but read the endpoint again when the key is not found. This functionality could be improved to avoid a DOS attack by calling your endpoint with some random key ids which would put Keycloak or the JWT Token provider under stress.
val jwkProvider = UrlJwkProvider(jwkUrl)
verifier {
val publicKey = PublicKeyCache.getPublicKey(jwkProvider, it)
JWT.require(Algorithm.RSA256(publicKey, null))
.withAudience(expectedAudience)
.withIssuer(issuer)
.build()
}
The other improvement that you can find in the example is the validation part. Since you only have the credential as input for this validation, you can check if the token has a certain role, but you can’t make this check dynamic based on the endpoint. As mentioned, this would mean that for each role that you want to check, you should make a different JWT check.
The example contains an extension function on the Route object so that you can define the role that you expect. This is how you can use this new authorizeWithRoles function
authorizeWithRoles("jwt-auth", listOf("administrator")) {
get("/protected/admin") {
call.respondText("Protected Resource; Administrator Only ")
}
}
So besides the name for the protocol we like to use, you can also define a set of roles that you expect to be in the token. The function itself is not that long but a little complex because we add a new interceptor in the pipeline used by Ktor to handle the request. If you want to look at the details, have a look at the example code.
If you just need a valid token, without any check on the roles, you can make use of the standard Ktor functionality
authenticate("jwt-auth") {
get("/protected/user") {
val principal = call.authentication.principal<JWTPrincipal>()
//val username = principal?.payload?.getClaim("username")?.asString()
val username = principal?.payload?.getClaim("preferred_username")?.asString()
call.respondText("Hello, $username!")
}
}
This last snippet also shows how you can get access to the claims within the token. You can access the principal associated with- the request by requesting call.authentication.principal<JWTPrincipal>() where you immediately make the cast to the JWTPrincipal class. This contains the entire token content easily accessible from within your Kotlin code as you can see in the example where I retrieve the preferred_username.
You can review all code presented here in the example https://github.com/rdebusscher/Project_FF/tree/main/jwt/ktor.
Atbash Runtime
Atbash Runtime is a small modular Jakarta EE Core profile runtime. So by default, it doesn’t has support for using JWT tokens. But since these tokens are the de facto standard, there is an Atbash Runtime module that supports them so that you can use it for your application.
As a dependency, you can add this JWT supporting module to your project
<dependency>
<!-- Adds JWT Support in the case we are using the Jakarta Runner, no addition of the MP JWT Auth API required -->
<!-- Otherwise, when not using Jakarta Runner, the addition of JWT Auth API as provided is enough if you are using Atbash Runner Jar executable -->
<groupId>be.atbash.runtime</groupId>
<artifactId>jwt-auth-module</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
Since we use the Jakarta Runner feature of the Atbash runtime, which allows you to execute your web application through a simple main method, we need to add the module itself. If you run your application as a war file, make sure you activate the JWT module within the configuration so that the module is active.
The JWT support within Atbash runtime is also based on the Microprofile JWT Auth specification, so you will see many similarities with the Payara and Quarkus examples we have discussed in part 2 of this blog.
Configuration requires the 3 values for public key location, expected issuer, and audience.
mp.jwt.verify.publickey.location=http://localhost:8888/auth/realms/atbash_project_ff/protocol/openid-connect/certs mp.jwt.verify.issuer=http://localhost:8888/auth/realms/atbash_project_ff mp.jwt.verify.audiences=account
You are also required to indicate the @LoginConfig (in case you are executing your application as a WAR file) so that the JWT Module is active for the application. But there is no need to define @DeclareRoles as Atbash Runtime takes the value of the individual @RolesAllowed as valid roles.
A difference with Payara, for example, is that you need to add @PermitAll to a method when you don’t want to check on any roles. Within Atbash Runtime there is the “principle of least privilege” implemented. If you don’t specify anything on a JAX_RS method no client can call it. This is to avoid that you forget to define some security requirements and expose the endpoint without any checks. The JavaDoc says “Specifies that all security roles are allowed to invoke the specified method(s)” and thus it is clearly what we need. Although, some runtimes, including Payara, interpret this differently and I’ll go deeper on this topic in part 4.
The example code is located at https://github.com/rdebusscher/Project_FF/tree/main/jwt/atbash.
Discussion
In the last part of the blog, I’ll have a discussion about similarities and differences. These differences are especially important when you don’t want to have a check on a role within the token.
Part 1: Introduction
Part 2: Payara, Spring Boot and Quarkus
Part 3: Ktor and Atbash Runtime (this one)
Part 4: Discussion and conclusion
Training and Support
Do you need a specific training session on Jakarta EE, Quarkus, Kotlin or MicroProfile? Have a look at the training support that I provide on the page https://www.atbash.be/training/ and contact me for more information.