If you haven’t seen my previous articles, then I highly encourage you to check them out:

• Secure REST API with Ktor and JWT Access Tokens
• Secure Ktor app with JWT refresh tokens. Refresh token flow.

Moreover, in this tutorial, we will build functionality based on the refresh token article, so I highly encourage you to fetch the code from this repo now. But don’t worry, if you are interested only in the RBAC part, then please navigate to the “Custom Ktor Authorization Plugin” paragraph.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

What Exactly Will We Do Today?

At the end of this tutorial, you will know precisely how to secure your Ktor REST API with role-based access control (RBAC).

But to be more specific, we will work with two endpoints:

The GET /api/user/{id} will be accessible for users with either ADMIN or USER roles. The second one, GET /api/user, will be accessible only for ADMIN users.

And how we will achieve that?

Well, we will implement a custom Ktor authorization plugin, which will be triggered on the AuthenticationChecked hook.

And I’ll show you how to do it the easy way, without unnecessary logic 🙂

What Is Role-Based Access Control (RBAC)?

Again, before we learn how to implement role-based access control (RBAC) in Ktor, let’s learn a bit about it.

Role-based access control (RBAC) or role-based security is nothing else than a way of restricting system access to authorized users.

To put it simply, we define a set of roles in our system, which reflects the needs of given permissions from our organization. An example of such a role can be a user, manager, admin, and many many more. And based on this role we allow, or deny access for a particular, authenticated user.

When dealing with JWT tokens in a REST API, such information can be first stored inside the token, so that later, we can easily read a claim and check whether a request should be served, or not.

Update User Class and Repo

With all of that said, let’s finally start the practice part.

As the first step, let’s navigate to the User class and insert a new field- role:

import java.util.UUID

data class User(
  val id: UUID,
  val username: String,
  val password: String,
  val role: String
)

For the sake of simplicity, let’s leave it as a String value, but depending on your needs, you may want to consider using an enum, or even a sealed class instead.

At this point, our code won’t compile, so let’s navigate to the UserRoute.kt and update the .toModel() extension function:

private fun UserRequest.toModel(): User =
  User(
    id = UUID.randomUUID(),
    username = this.username,
    password = this.password,
    role = "USER"
  )

As we can see, by default, all created users will have the USER role assigned.

Lastly, let’s navigate to the UserRepository and add some ADMIN user:

class UserRepository {

  private val users = mutableListOf(
    User(UUID.randomUUID(), "admin", "password", "ADMIN")
  )

  // the rest of the class
}

Add Role Claim to JWT Token

As the next step, let’s open up the JwtService and update these 3 functions:

fun createAccessToken(username: String, role: String): String =
  createJwtToken(username, role, 3_600_000)

fun createRefreshToken(username: String, role: String): String =
  createJwtToken(username, role, 86_400_000)

private fun createJwtToken(
  username: String,
  role: String, 
  expireIn: Int,
): String =
  JWT.create()
    .withAudience(audience)
    .withIssuer(issuer)
    .withClaim("username", username)
    .withClaim("role", role)
    .withExpiresAt(Date(System.currentTimeMillis() + expireIn))
    .sign(Algorithm.HMAC256(secret))

As I mentioned in the “theory” part- when dealing with JWT tokens, we can put information about the user’s role inside the token.

And that’s exactly what is happening here. From now on, every access and refresh token will contain an additional claim- the role– which will be populated with a role assigned to a user.

Update UserService

With that done, we must navigate to the UserService and update authenticate and refreshToken functions:

fun authenticate(loginRequest: LoginRequest): AuthResponse? {
  val username = loginRequest.username
  val foundUser: User? = userRepository.findByUsername(username)

  return if (foundUser != null && loginRequest.password == foundUser.password) {
    val accessToken = jwtService.createAccessToken(username, foundUser.role)
    val refreshToken = jwtService.createRefreshToken(username, foundUser.role)

    refreshTokenRepository.save(refreshToken, username)

    AuthResponse(
      accessToken = accessToken,
      refreshToken = refreshToken,
    )
  } else
    null
}

fun refreshToken(token: String): String? {
  val decodedRefreshToken = verifyRefreshToken(token)
  val persistedUsername = refreshTokenRepository.findUsernameByToken(token)

  return if (decodedRefreshToken != null && persistedUsername != null) {
    val foundUser: User? = userRepository.findByUsername(persistedUsername)
    val usernameFromRefreshToken: String? = decodedRefreshToken.getClaim("username").asString()

    if (foundUser != null && usernameFromRefreshToken == foundUser.username)
      jwtService.createAccessToken(persistedUsername, foundUser.role)
    else
      null
  } else
    null
}

From now on we must pass the user role to the JwtService when creating new tokens and that’s exactly what we updated here.

Custom Ktor Authorization Plugin

What Are Ktor Plugins?

Before we implement our custom one, let’s understand what exactly Ktor plugins are.

Basically, plugins in Ktor are a way to implement a common functionality that is out of the scope of the application logic. But what do we mean by that? Well, things like serialization, deserialization, compression, encoding, etc.

And when we take a look at the following diagram:

We will clearly see that plugins are everything that sits between request, application handler, and response. And yes, routing is a plugin too.

At this point, we can see that a custom plugin will be a great wait to achieve RBAC in our Ktor application. Moreover, we will use a new simplified API for creating custom plugins introduced in Ktor v2.0.0.

Implement Ktor RBAC Plugin

With all of that said, let’s navigate to the plugins package and create the RoleBasedAuthorization.kt and write the following:

import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.auth.jwt.*
import io.ktor.server.response.*

class PluginConfiguration {
  var roles: Set<String> = emptySet()
}

val RoleBasedAuthorizationPlugin = createRouteScopedPlugin(
  name = "RbacPlugin",
  createConfiguration = ::PluginConfiguration
) {
  val roles = pluginConfig.roles

  pluginConfig.apply {

    on(AuthenticationChecked) { call ->
      val tokenRole = getRoleFromToken(call)

      val authorized = roles.contains(tokenRole)

      if (!authorized) {
        println("User does not have any of the following roles: $roles")
        call.respond(HttpStatusCode.Forbidden)
      }
    }
  }
}

private fun getRoleFromToken(call: ApplicationCall): String? =
  call.principal<JWTPrincipal>()
    ?.payload
    ?.getClaim("role")
    ?.asString()

Firstly, we create the PluginConfiguration class with a roles field. This way, we will be able to configure later, which roles should be allowed for the given endpoint and which should be forbidden.

Later, we introduce our new, custom Ktor plugin using the createRouteScopedPlugin function. We must do that if we want to introduce a plugin that can be installed for a specific route.

Inside this function, we refer to pluginConfig and configure what exactly our custom authorization plugin must do. Firstly, we set the on handler that accepts a Hook as a parameter- in our case the AuthenticationChecked is a hook. As per the documentation:

AuthenticationChecked is executed after authentication credentials are checked.

Which simply means, that our plugin will be invoked after we authenticate the user successfully. With the old API, we would have to use the after Authentication.ChallengePhase.

Following, we extract the user role from the JWT role claim and if it is inside the Set with allowed roles, then we do nothing. Otherwise, we return 403 Forbidden.

Add RoleUtil

With that done, let’s navigate to the util package and introduce the authorized function inside the RouteUtil.kt:

import com.codersee.plugins.RoleBasedAuthorizationPlugin
import io.ktor.server.application.*
import io.ktor.server.routing.*

fun Route.authorized(
  vararg hasAnyRole: String,
  build: Route.() -> Unit
) {
  install(RoleBasedAuthorizationPlugin) { roles = hasAnyRole.toSet() }
  build()
}

To put it simply, we will use this function whenever we would like to authorize our request using role-based access control.

As a result, it will register our authorization plugin for a particular route.

Update User Routes

And with that said, let’s see it in action:

authenticate {
  authorized("ADMIN") {

    get {
      val users = userService.findAll()

      call.respond(
        message = users.map(User::toResponse)
      )
    }

  }
}

authenticate("another-auth") {
  authorized("ADMIN", "USER") {

    get("/{id}") {
      val id: String = call.parameters["id"]
        ?: return@get call.respond(HttpStatusCode.BadRequest)

      val foundUser = userService.findById(id)
        ?: return@get call.respond(HttpStatusCode.NotFound)

      if (foundUser.username != extractPrincipalUsername(call))
        return@get call.respond(HttpStatusCode.NotFound)

      call.respond(
        message = foundUser.toResponse()
      )
    }
  }

As we can see, from now on we can simply use the authorized whenever we want to limit endpoint accessibility to particular roles.

Of course, we must remember that this can be done only when the user is authenticated, because otherwise, we won’t be able to read the role claim.

Ktor RBAC summary

And that’s all for this article on how to implement role-based access control (RBAC) in Ktor.

I hope this article (and a series) helped you to learn how easily we can set up different things related to security in Ktor. If you haven’t seen previous materials yet, then you can do that right here:

• Secure REST API with Ktor and JWT Access Tokens
• Secure Ktor app with JWT refresh tokens. Refresh token flow.

As always, you can find a source code in this GitHub repository and let me know your thoughts in the comments section below 🙂

The post Secure REST API with Ktor – Role-based access control (RBAC) appeared first on Codersee blog- Kotlin on the backend.

To not duplicate ourselves, we will use the project implemented in the previous blog post, in which we learned how to implement a secure REST API with Ktor and authenticate with JWT access tokens. So if you haven’t read that article yet, I highly encourage you to do it now. Nevertheless, if you are interested more in the refresh token part, you can find a link to the GitHub repository and simply clone the project.

Without any further ado, let’s get to work 🙂

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

A Tiny Bit Of Theory

If you’re following me for a longer period, you know that I focus on the practical side of different problems.

Nevertheless, I owe you a bit of explanation before we learn how to secure our Ktor app with JWT refresh token flow. So, in the following paragraphs, I will shortly describe:

• the difference between access tokens and refresh tokens,
• what is a refresh token flow,
• and advantages of such a flow.

Of course, if you feel that’s not necessary in your case, then feel free to skip to the Implement RefreshTokenRepository section 😉

Access Tokens vs Refresh Tokens

Let’s start everything by distinguishing these two.

First of all, they both play distinct roles in token-based authentication systems.

An access token is a short-lived credential that is issued to a client after a successful authentication. Its purpose is to grant the client permission to access protected resources on behalf of the user. And by the client, we mean here a web app, a mobile app, or any other integration working with our REST API.

They are designed to have a limited lifespan to enhance security, reducing the risk associated with compromised tokens.

Refresh tokens, on the other hand, are long-lived credentials that are used to obtain new access tokens without requiring the user to re-authenticate.

While access tokens are meant for short-term authorization, refresh tokens provide a mechanism for obtaining fresh access tokens and extending the user’s session securely.

Refresh Token Flow

To put it simply, when a client authenticates successfully, it receives two tokens: an access token, and a refresh token.

The access token will be used to query our API. If it is compromised, the bad actor will have a limited time to perform unwanted actions on behalf of the user (thanks to its short-lived nature).

The refresh token, with a longer expiration time, will allow the client to get a new access token whenever it expires. This way, the user does not need to specify credentials (like username, and password for instance) every time an access token expires.

With this flow, we can strike a balance between usability and security. We improve user experience and maintain protection against unauthorized access.

Pros vs Cons

As with every solution, refresh token flow has both pros and cons.

When it comes to the advantages, we already covered the first two- the shorter lifespan of access tokens limits the potential impact of a token compromise. Additionally, a long-living refresh token means a better user experience– a longer time between asking the user for his credentials. Lastly, this flow gives us more granular control over token management, for example, we can revoke refresh tokens selectively.

When it comes to the disadvantages, we could call them additional complexity. Not only we must carefully implement on the backend to prevent any vulnerabilities, but also, the storage and transmission of refresh tokens need to be handled securely to prevent unauthorized access.

Lastly, should we always use refresh token flow in our applications?

The answer is- as always- it depends. When dealing with security for our app we should spend some time investigating in depth all options on the table. Such an analysis would be way too much for the article about implementing a Ktor JWT refresh token flow 😉

Implement RefreshTokenRepository

With all of that said, we can finally start the practice part.

As the first step, let’s navigate to the repository package in our Ktor project and add the RefreshTokenRepository class:

class RefreshTokenRepository {

  private val tokens = mutableMapOf<String, String>()

  fun findUsernameByToken(token: String): String? =
    tokens[token]

  fun save(token: String, username: String) {
    tokens[token] = username
  }

}

Again, in a real-life scenario, this would be the class responsible for communicating to the data source, like a relational database, MongoDB, or any other source used in the project. To keep our tutorial simple and focused on the Ktor/JWT combination, we will use a mutable map storing a combination of tokens with usernames in memory.

As we can see, this class exposes two functions. One is for persisting the data in our map, and the second one is to retrieve usernames based on the JWT refresh token value.

Update JwtService

Nextly, let’s open up the JwtService class and update it a bit:

import com.auth0.jwt.JWT
import com.auth0.jwt.JWTVerifier
import com.auth0.jwt.algorithms.Algorithm
import com.codersee.model.User
import com.codersee.repository.UserRepository
import io.ktor.server.application.*
import io.ktor.server.auth.jwt.*
import java.util.*

class JwtService(
  private val application: Application,
  private val userRepository: UserRepository,
) {

  private val secret = getConfigProperty("jwt.secret")
  private val issuer = getConfigProperty("jwt.issuer")
  private val audience = getConfigProperty("jwt.audience")

  val realm = getConfigProperty("jwt.realm")

  val jwtVerifier: JWTVerifier =
    JWT
      .require(Algorithm.HMAC256(secret))
      .withAudience(audience)
      .withIssuer(issuer)
      .build()

  fun createAccessToken(username: String): String =
    createJwtToken(username, 3_600_000)

  fun createRefreshToken(username: String): String =
    createJwtToken(username, 86_400_000)

  private fun createJwtToken(username: String, expireIn: Int): String =
    JWT.create()
      .withAudience(audience)
      .withIssuer(issuer)
      .withClaim("username", username)
      .withExpiresAt(Date(System.currentTimeMillis() + expireIn))
      .sign(Algorithm.HMAC256(secret))


  fun customValidator(
    credential: JWTCredential,
  ): JWTPrincipal? {
    val username: String? = extractUsername(credential)
    val foundUser: User? = username?.let(userRepository::findByUsername)

    return foundUser?.let {
      if (audienceMatches(credential))
        JWTPrincipal(credential.payload)
      else
        null
    }
  }

  private fun audienceMatches(
    credential: JWTCredential,
  ): Boolean =
    credential.payload.audience.contains(audience)

  fun audienceMatches(
    audience: String
  ): Boolean =
    this.audience == audience

  private fun getConfigProperty(path: String) =
    application.environment.config.property(path).getString()

  private fun extractUsername(credential: JWTCredential): String? =
    credential.payload.getClaim("username").asString()
}

First of all, we replaced the UserService dependency from the constructor with the UserRepository. This way, we would avoid a circular dependency between this class and UserService later.

Then, we extracted the code responsible for generating JWT tokens into a separate function- createJwtToken– which will be called by the createAccessToken, and createRefreshToken. Please note that these two functions declare different expiration times for both token types- 1 hour for the access token and 24 for the refresh token.

But what expiration time should we set in a real-life? Well, again, it depends 🙂 And we must consider both security concerns, as well as the storage. Yes, the longer the expiration time, the bigger the amount of refresh tokens stored in our database.

Lastly, we added the audienceMatches function, which we will use later in the code.

Update Routing Layer

With all of that done, let’s navigate to the routing package and make the necessary changes too.

Add Request/Response Classes

As the first step, let’s add a class responsible for mapping refresh token call JSON payload:

import kotlinx.serialization.Serializable

@Serializable
data class RefreshTokenRequest(
  val token: String,
)

Following, let’s implement a class, which will serialize the authentication response:

import kotlinx.serialization.Serializable

@Serializable
data class AuthResponse(
  val accessToken: String,
  val refreshToken: String,
)

And finally, the RefreshTokenResponse:

import kotlinx.serialization.Serializable

@Serializable
data class RefreshTokenResponse(
  val token: String,
)

Update Routing.kt

As the next step, let’s update the Routing.kt class:

import com.codersee.service.UserService
import io.ktor.server.application.*
import io.ktor.server.routing.*

fun Application.configureRouting(
  userService: UserService
) {
  routing {

    route("/api/auth") {
      authRoute(userService)
    }

    route("/api/user") {
      userRoute(userService)
    }

  }
}

As we can see, we don’t inject the JwtService anymore. Instead, we invoke the authRoute with UserService instance instead.

Edit AuthRoute.kt

import com.codersee.routing.request.LoginRequest
import com.codersee.routing.request.RefreshTokenRequest
import com.codersee.routing.response.AuthResponse
import com.codersee.routing.response.RefreshTokenResponse
import com.codersee.service.UserService
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Route.authRoute(userService: UserService) {

  post {
    val loginRequest = call.receive<LoginRequest>()

    val authResponse: AuthResponse? = userService.authenticate(loginRequest)

    authResponse?.let {
      call.respond(authResponse)
    } ?: call.respond(
      message = HttpStatusCode.Unauthorized
    )
  }

  post("/refresh") {
    val request = call.receive<RefreshTokenRequest>()

    val newAccessToken = userService.refreshToken(token = request.token)

    newAccessToken?.let {
      call.respond(
        RefreshTokenResponse(it)
      )
    } ?: call.respond(
      message = HttpStatusCode.Unauthorized
    )
  }

}

So, instead of dealing with JwtService, we are going to invoke the UserService functions instead.

In the first handler for POST /api/auth calls, we invoke the authenticate method and if we receive an AuthResponse, then we will simply return that to the API client with 200 OK status. Otherwise, we will return 401 Unauthorized.

Additionally, we add a new handler for POST /api/auth/refresh calls. Inside it, we read the JSON payload and create an instance of RefreshTokenRequest. Then, we invoke the refreshToken method from UserService (which we are going to implement in a moment). And just like previously, if the service returns a non-null object, then we respond with 200 OK and with 401 Unauthorized if that’s not the case.

Update UserService

As the last thing in our Ktor with the JWT refresh token tutorial, we must update the UserService:

import com.auth0.jwt.interfaces.DecodedJWT
import com.codersee.model.User
import com.codersee.repository.RefreshTokenRepository
import com.codersee.repository.UserRepository
import com.codersee.routing.request.LoginRequest
import com.codersee.routing.response.AuthResponse
import java.util.*

class UserService(
  private val userRepository: UserRepository,
  private val jwtService: JwtService,
  private val refreshTokenRepository: RefreshTokenRepository
) {

  fun findAll(): List<User> =
    userRepository.findAll()

  fun findById(id: String): User? =
    userRepository.findById(
      id = UUID.fromString(id)
    )

  fun findByUsername(username: String): User? =
    userRepository.findByUsername(username)

  fun save(user: User): User? {
    val foundUser = userRepository.findByUsername(user.username)

    return if (foundUser == null) {
      userRepository.save(user)
      user
    } else null
  }

  fun authenticate(loginRequest: LoginRequest): AuthResponse? {
    val username = loginRequest.username
    val foundUser: User? = userRepository.findByUsername(username)

    return if (foundUser != null && loginRequest.password == foundUser.password) {
      val accessToken = jwtService.createAccessToken(username)
      val refreshToken = jwtService.createRefreshToken(username)

      refreshTokenRepository.save(refreshToken, username)

      AuthResponse(
        accessToken = accessToken,
        refreshToken = refreshToken,
      )
    } else
      null
  }

  fun refreshToken(token: String): String? {
    val decodedRefreshToken = verifyRefreshToken(token)
    val persistedUsername = refreshTokenRepository.findUsernameByToken(token)

    return if (decodedRefreshToken != null && persistedUsername != null) {
      val foundUser: User? = userRepository.findByUsername(persistedUsername)
      val usernameFromRefreshToken: String? = decodedRefreshToken.getClaim("username").asString()

      if (foundUser != null && usernameFromRefreshToken == foundUser.username)
        jwtService.createAccessToken(persistedUsername)
      else
        null
    } else
      null
  }

  private fun verifyRefreshToken(token: String): DecodedJWT? {
    val decodedJwt: DecodedJWT? = getDecodedJwt(token)

    return decodedJwt?.let {
      val audienceMatches = jwtService.audienceMatches(it.audience.first())

      if (audienceMatches)
        decodedJwt
      else
        null
    }
  }

  private fun getDecodedJwt(token: String): DecodedJWT? =
    try {
      jwtService.jwtVerifier.verify(token)
    } catch (ex: Exception) {
      null
    }
}

And let’s see the most important changes here.

Firstly, we add the authenticate function:

fun authenticate(loginRequest: LoginRequest): AuthResponse? {
  val username = loginRequest.username
  val foundUser: User? = userRepository.findByUsername(username)

  return if (foundUser != null && loginRequest.password == foundUser.password) {
    val accessToken = jwtService.createAccessToken(username)
    val refreshToken = jwtService.createRefreshToken(username)

    refreshTokenRepository.save(refreshToken, username)

    AuthResponse(
      accessToken = accessToken,
      refreshToken = refreshToken,
    )
  } else
    null
}

This one is simply responsible for fetching a user from our repository using the passed username.

If we find it successfully, we check if the password matches (again, it’s just a dummy plain text comparison and you want to learn more about password checks in real-life scenarios). And if that’s the case, then we simply return the access and refresh tokens to the user and persist the refresh token in our “database”.

Nextly, we have a refresh token flow function:

fun refreshToken(token: String): String? {
  val decodedRefreshToken = verifyRefreshToken(token)
  val persistedUsername = refreshTokenRepository.findUsernameByToken(token)

  return if (decodedRefreshToken != null && persistedUsername != null) {
    val foundUser: User? = userRepository.findByUsername(persistedUsername)
    val usernameFromRefreshToken: String? = decodedRefreshToken.getClaim("username").asString()

    if (foundUser != null && usernameFromRefreshToken == foundUser.username)
      jwtService.createAccessToken(persistedUsername)
    else
      null
  } else
    null
}

When it comes to refreshing a token, we check if there is any persisted username found by the token value. If it is, then we fetch the user by the given username (this way, we won’t refresh a token for user that does not exist anymore).

And at this point, we can rerun our application and verify if our logic works, as expected. Again, if you’d like to get a ready-to-go Postman collection, then please let me know in the comments section.

Ktor With JWT Refresh Token Summary

And basically, that’s all for this, second tutorial in a series related to Ktor security, in which we learned how to create a Ktor application with JWT refresh token flow.

As always, you can find the whole source code in my GitHub repository.

Thank you for being here and please do not forget to share it with other people on your social media (it will help me a lot) and check other posts from the series:

• Secure REST API with Ktor and JWT Access Tokens,
• and how to add a role-based access control (RBAC) to the project.

The post Secure Ktor app with JWT refresh tokens. Refresh token flow. appeared first on Codersee blog- Kotlin on the backend.

To be even more specific, in this tutorial I will teach you:

• how to implement a simple REST API,
• what are JSON Web Tokens and what does the authentication mean,
• how to generate and validate JWT access tokens, and authenticate users,
• and how to read data using the JWTPrincipal.

In the upcoming articles, we will continue the topic and learn additionally:

• how to implement a refresh token flow with Ktor,
• and how to add a role-based access control (RBAC) to the project.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

What Is Authentication?

But before we start implementing our Ktor app with JWT tokens, let me quickly explain what exactly authentication is.

In essence, it is the process of verifying the identity of a user, system, or device to ensure that they are who they claim to be.

It is like having a secret code to enter a club. Let’s imagine we want to get into a cool party, and at the entrance, there’s a bouncer checking everyone’s membership. To prove we belong, we provide a special password. If the password matches what’s on the list, we’re in!

In the digital world, it’s the same idea – we need to confirm our identity with a unique key (like a password or JWT token) to access our email, bank account, or, like in our case, any resource through the exposed REST API.

Of course, authentication is not a synonym for authorization (but we will get back to that in the upcoming post).

JWT Tokens Explained

As the last thing before we head to the practice, let’s learn a bit about the JWT tokens.

JWTs, also known as JSON Web Tokens, are nothing else than one of plenty of existing ways to authenticate users.

Just like with our previous example- in real life, we can use our ID, passport, or in other cases, some secret word.

Here, the JWT is like a digital secret handshake on the internet. When sign in using our username and password, the server gives us a special JWT, and later, we can use it to access a REST API. This way, we don’t need to specify such vulnerable data every time we want to make a request.

What are the other advantages? Well, they are safe and compact, and allow us to hold information.

JWTs consist of three parts separated by dots: header.payload.signature:

The encoded value can be easily decoded and JWT token values can be read.

The header typically consists of two parts: the type of the token (missing above), and the signing algorithm being used (HMAC SHA512).

The second part of the token is the payload, which contains the claims. Claims, Claims are statements about an entity (typically, the user) and additional data.

Lastly, the signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn’t changed along the way.

Set Up New Ktor Project

With all of that said, let’s navigate to the Ktor Project Generator and start by specifying the necessary details:

At this stage, we must specify the basic things, like the Ktor version, engine, etc.

Nextly, let’s click the “Add plugins” button and configure the following plugins (aka dependencies):

As we can see, in order to expose a REST API and secure it with JWT in Ktor, we will need the following:

• Authentication,
• Authentication JWT,
• Content Negotiation,
• kotlinx.serialization,
• and Routing.

With that done, let’s generate the project, download the ZIP file, extract it, and import it to the IntelliJ IDEA.

When we open up the project, we should see that there are some plugins already configured inside the plugins package and Application.kt file.

Let’s delete files inside the plugins and clean up the Application.kt to be on the same page:

import io.ktor.server.application.*

fun main(args: Array<String>) {
  io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {
}

Expose Users API

As the next step, let’s expose the API responsible for user management.

Add User Model

Firstly, let’s create the model package and implement the User.kt class:

import java.util.UUID

data class User(
  val id: UUID,
  val username: String,
  val password: String
)

As can be seen, it’s just a simple class with the id, username, and password fields.

Create UserRepository

Secondly, we must add a class responsible for user storage and retrieval.

To do so, let’s add the repository package and put the UserRepository inside it:

import com.codersee.model.User
import java.util.*

class UserRepository {

  private val users = mutableListOf<User>()

  fun findAll(): List<User> =
    users

  fun findById(id: UUID): User? =
    users.firstOrNull { it.id == id }

  fun findByUsername(username: String): User? =
    users.firstOrNull { it.username == username }

  fun save(user: User): Boolean =
    users.add(user)
}

Normally, we would put a code responsible for “talking” to the database right here.

In our case, to not lose focus from the clue of this article- authentication in Ktor and JWT- we introduce a dummy repository, which uses the mutable list to store users in memory.

Note: in our dummy repository, we store user password in a plain text.

Nevertheless, in real-life scenarios we should always encrypt it before persisting. To learn a bit more about different encryption algorithms, you can check out my other post in which I explain PBKDF2 hashing.

Implement UserService

With that done, let’s introduce a service layer in our project.

So, similarly, let’s add the service package and the UserService class:

import com.codersee.model.User
import com.codersee.repository.UserRepository
import java.util.*

class UserService(
  private val userRepository: UserRepository
) {

  fun findAll(): List<User> =
    userRepository.findAll()

  fun findById(id: String): User? =
    userRepository.findById(
      id = UUID.fromString(id)
    )

  fun findByUsername(username: String): User? =
    userRepository.findByUsername(username)

  fun save(user: User): User? {
    val foundUser = userRepository.findByUsername(user.username)

    return if (foundUser == null) {
      userRepository.save(user)
      user
    } else null
  }
}

This time, we expose 4 functions, which we will utilize later when handling requests and working with JWT tokens.

Add Request and Response Classes

Before we expose our REST endpoint, let’s take care of the request and response classes.

Let’s start by creating the routing.request package and implementing the UserRequest:

import kotlinx.serialization.Serializable

@Serializable
data class UserRequest(
  val username: String,
  val password: String,
)

As we can see, we must annotate objects that we want to serialize or deserialize using the @Serializable when working with kotlinx.serialization library.

As a result, the serialization plugin will automatically generate the implementation of KSerializer.

Similarly, let’s add the routing.response package and the UserResponse:

import kotlinx.serialization.Serializable
import java.util.*

@Serializable
data class UserResponse(
  val id: UUID,
  val username: String,
)

This one seems pretty similar, but unfortunately, we must do one more thing here.

Custom UUID KSerializer

If we would try to use this class as it is, we would end up with the following error:

Serializer has not been found for type ‘UUID’. To use context serializer as fallback, explicitly annotate type or property with @Contextual.

And to fix this issue, we must implement our own UUID serializer.

So as the first step, let’s introduce the util package and add the UUIDSerializer object:

import kotlinx.serialization.KSerializer
import kotlinx.serialization.descriptors.PrimitiveKind
import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor
import kotlinx.serialization.descriptors.SerialDescriptor
import kotlinx.serialization.encoding.Decoder
import kotlinx.serialization.encoding.Encoder
import java.util.*

object UUIDSerializer : KSerializer<UUID> {

  override val descriptor: SerialDescriptor
    get() = PrimitiveSerialDescriptor("UUID", PrimitiveKind.STRING)

  override fun deserialize(decoder: Decoder): UUID =
    UUID.fromString(decoder.decodeString())

  override fun serialize(encoder: Encoder, value: UUID) =
    encoder.encodeString(value.toString())
}

Following, let’s instruct the plugin to use our implementation whenever it wants to serialize the id field:

import com.codersee.util.UUIDSerializer
import kotlinx.serialization.Serializable
import java.util.*

@Serializable
data class UserResponse(
  @Serializable(with = UUIDSerializer::class)
  val id: UUID,
  val username: String,
)

Register Serialization Plugin

When working with Ktor, we must explicitly specify the plugins we use. There is no component scan based on the dependencies which you may know from Spring Boot 🙂

So as the next step, let’s add the Seriaization.kt to the plugins package:

import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*

fun Application.configureSerialization() {
  install(ContentNegotiation) {
    json()
  }
}

The ContentNegotiation plugin has two tasks:

• it negotiates the media types between the client and server,
• and serializes/deserializes the content in a specific format.

In our case, we can clearly see that we will be using the JSON format.

Note: other formats, like XML, CBOR, and ProtoBuf are supported, too.

Lastly, we must make use of our extension function inside the Application.kt file:

import com.codersee.plugins.configureSerialization
import io.ktor.server.application.*

fun main(args: Array<String>) {
  io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {
  configureSerialization()
}

Add User Route

With all of that being done, we can finally expose endpoints for user management.

As the first step, let’s implement the Routing.kt class inside the routing package:

import com.codersee.service.UserService
import io.ktor.server.application.*
import io.ktor.server.routing.*

fun Application.configureRouting(
  userService: UserService
) {
  routing {

    route("/api/user") {
      userRoute(userService)
    }

  }
}

This way, we instruct Ktor that whenever a request is made to the /api/user**, it should look for a handler inside the userRoute (which we will add in a moment).

Following, let’s get back to the Application.kt and register our routing:

import com.codersee.plugins.configureSerialization
import com.codersee.repository.UserRepository
import com.codersee.routing.configureRouting
import com.codersee.service.UserService
import io.ktor.server.application.*

fun main(args: Array<String>) {
  io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {
  val userRepository = UserRepository()
  val userService = UserService(userRepository)

  configureSerialization()
  configureRouting(userService)
}

Nextly, let’s add the UserRoute.kt inside the routing package:

import com.codersee.model.User
import com.codersee.routing.request.UserRequest
import com.codersee.routing.response.UserResponse
import com.codersee.service.UserService
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import java.util.*

fun Route.userRoute(userService: UserService) {

  post {
    val userRequest = call.receive<UserRequest>()

    val createdUser = userService.save(
      user = userRequest.toModel()
    ) ?: return@post call.respond(HttpStatusCode.BadRequest)

    call.response.header(
      name = "id",
      value = createdUser.id.toString()
    )
    call.respond(
      message = HttpStatusCode.Created
    )
  }

  get {
    val users = userService.findAll()

    call.respond(
      message = users.map(User::toResponse)
    )
  }

  get("/{id}") {
    val id: String = call.parameters["id"]
      ?: return@get call.respond(HttpStatusCode.BadRequest)

    val foundUser = userService.findById(id)
      ?: return@get call.respond(HttpStatusCode.NotFound)

    call.respond(
      message = foundUser.toResponse()
    )
  }
}

private fun UserRequest.toModel(): User =
  User(
    id = UUID.randomUUID(),
    username = this.username,
    password = this.password
  )

private fun User.toResponse(): UserResponse =
  UserResponse(
    id = this.id,
    username = this.username,
  )

And to be on the same page, let’s rephrase what is going on here:

import com.codersee.model.User
import com.codersee.routing.request.UserRequest
import com.codersee.routing.response.UserResponse
import com.codersee.service.UserService
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import java.util.*

fun Route.userRoute(userService: UserService) {

  post {
    val userRequest = call.receive<UserRequest>()

    val createdUser = userService.save(
      user = userRequest.toModel()
    ) ?: return@post call.respond(HttpStatusCode.BadRequest)

    call.response.header(
      name = "id",
      value = createdUser.id.toString()
    )
    call.respond(
      message = HttpStatusCode.Created
    )
  }

}

Firstly, we inject the instance of UserService, which we will use to save and retrieve users.

Nextly, we specify a handler for POST requests.

Inside this handler, we get the JSON payload sent by the API consumer as an instance of UserRequest with the call.receive<T>() function. Then, we invoke the save function and pass the instance of the User class, which we obtain using the toModel() extension function. If the save returns a null value, we return 400 Bad Request with the call.respond() function.

On the other hand, if the user was saved successfully, we respond with a 201 Created status and pass its identifier as the id header value with call.response.header() function.

Then, we have another handler responsible for GET /api/user requests:

get {
  val users = userService.findAll()

  call.respond(
    message = users.map(User::toResponse)
  )
}

It is responsible for fetching all users and returning them after mapping with toResponse() extension functions.

Lastly, we have the handler answering to the GET /api/user/{id} requests:

get("/{id}") {
  val id: String = call.parameters["id"]
    ?: return@get call.respond(HttpStatusCode.BadRequest)

  val foundUser = userService.findById(id)
    ?: return@get call.respond(HttpStatusCode.NotFound)

  call.respond(
    message = foundUser.toResponse()
  )
}

This time, we read the path variable id using the call.paramaters. If is not present, we return a 400 Bad Request response.

Following, we try to find a user by ID and if we fail, then we simply return the 404 Not Found.

Ktor With JWT

Excellent! At this point, we have a working API, so it’s finally time to learn a bit more about how to secure it, and how to generate JWT tokens in our Ktor application so that we can use them later to access these endpoints.

Update Config File

As the first step, let’s navigate to the application.conf file.

Among other settings, we should see the following jwt:

jwt {
    domain = "https://jwt-provider-domain/"
    audience = "jwt-audience"
    realm = "ktor sample app"
}

Let’s slightly modify it:

jwt {
    audience = "my-audience"
    issuer = "http://localhost/"
    realm = "My realm"
    secret = ${SECRET}
}

Without going into too much detail, these values (except for the secret) will be claims in our JWT tokens:

• audience– which describes the recipient of the token,
• issuer– which is the entity that issues the token,
• realm– which is an optional parameter providing additional context or scope,
• secret– which is a secret key used for token signing and verification.

Please note that the secret value IS NOT hardcoded (and should never be). We will source it from the environment variable called SECRET.

Implement JwtService

With that done, we can navigate to the service package and add the JwtService:

import com.auth0.jwt.JWT
import com.auth0.jwt.JWTVerifier
import com.auth0.jwt.algorithms.Algorithm
import com.codersee.model.User
import io.ktor.server.application.*
import io.ktor.server.auth.jwt.*
import java.util.*

class JwtService(
  private val application: Application,
  private val userService: UserService,
) {

  private val secret = getConfigProperty("jwt.secret")
  private val issuer = getConfigProperty("jwt.issuer")
  private val audience = getConfigProperty("jwt.audience")

  val realm = getConfigProperty("jwt.realm")

  val jwtVerifier: JWTVerifier =
    JWT
      .require(Algorithm.HMAC256(secret))
      .withAudience(audience)
      .withIssuer(issuer)
      .build()

  fun createJwtToken(loginRequest: LoginRequest): String? {
    val foundUser: User? = userService.findByUsername(loginRequest.username)

    return if (foundUser != null && loginRequest.password == foundUser.password)
      JWT.create()
        .withAudience(audience)
        .withIssuer(issuer)
        .withClaim("username", loginRequest.username)
        .withExpiresAt(Date(System.currentTimeMillis() + 3_600_000))
        .sign(Algorithm.HMAC256(secret))
    else
      null
  }

  fun customValidator(
    credential: JWTCredential,
  ): JWTPrincipal? {
    val username: String? = extractUsername(credential)
    val foundUser: User? = username?.let(userService::findByUsername)

    return foundUser?.let {
      if (audienceMatches(credential))
        JWTPrincipal(credential.payload)
      else
        null
    }
  }

  private fun audienceMatches(
    credential: JWTCredential,
  ): Boolean =
    credential.payload.audience.contains(audience)

  private fun getConfigProperty(path: String) =
    application.environment.config.property(path).getString()

  private fun extractUsername(credential: JWTCredential): String? =
    credential.payload.getClaim("username").asString()
}

Again, let’s break it down into smaller chunks:

import com.auth0.jwt.JWT
import com.auth0.jwt.JWTVerifier
import com.auth0.jwt.algorithms.Algorithm
import com.codersee.model.User
import io.ktor.server.application.*
import io.ktor.server.auth.jwt.*
import java.util.*

class JwtService(
  private val application: Application,
  private val userService: UserService,
) {

  private val secret = getConfigProperty("jwt.secret")
  private val issuer = getConfigProperty("jwt.issuer")
  private val audience = getConfigProperty("jwt.audience")

  val realm = getConfigProperty("jwt.realm")

  val jwtVerifier: JWTVerifier =
    JWT
      .require(Algorithm.HMAC256(secret))
      .withAudience(audience)
      .withIssuer(issuer)
      .build()

  private fun getConfigProperty(path: String) =
    application.environment.config.property(path).getString()
}

Firstly, we inject the instance of Application and UserService classes.

Following we read the configuration properties we set in the previous step. 3 of them can be private, but the realm will be later used in another class to configure security.

After that, we must create an instance of the JwtVerifier and configure it. In simple words, this class holds the verify method which will later verify that a given token has not only a proper JWT format but also its signature matches.

And this is why we specify which algorithm, audience, and issuer a valid token must have.

With all of that done, we introduce the createJwtToken function:

fun createJwtToken(loginRequest: LoginRequest): String? {
  val foundUser: User? = userService.findByUsername(loginRequest.username)

  return if (foundUser != null && loginRequest.password == foundUser.password)
    JWT.create()
      .withAudience(audience)
      .withIssuer(issuer)
      .withClaim("username", loginRequest.username)
      .withExpiresAt(Date(System.currentTimeMillis() + 3_600_000))
      .sign(Algorithm.HMAC256(secret))
  else
    null
}

This one takes the username as an argument and tries to find a user with it.

If we succeed and the password matches, then we produce a new JWT access token with the appropriate audience, issuer, and username, expiring in 60 minutes and signed with the HMAC-SHA256 algorithm (with our secret key).

Lastly, we add the customValidator function, which we will later use to add an additional validation:

fun customValidator(
  credential: JWTCredential,
): JWTPrincipal? {
  val username: String? = extractUsername(credential)
  val foundUser: User? = username?.let(userService::findByUsername)

  return foundUser?.let {
    if (audienceMatches(credential))
      JWTPrincipal(credential.payload)
    else
      null
  }
}

private fun audienceMatches(
  credential: JWTCredential,
): Boolean =
  credential.payload.audience.contains(audience)

private fun extractUsername(credential: JWTCredential): String? =
  credential.payload.getClaim("username").asString()

As the first thing, we extract the username from the JWT token and we try to find a user by this value.

If we succeed, then we check if the audience from the token matches the audience set in our Ktor project. If that’s true, then we instantiate the JWTPrincipal, which we will use later to obtain the information.

Install Authentication Plugin

At this point, we have the JWT service ready, so it’s time to install the Authentication plugin.

To do so, let’s add the Security plugin inside the plugins package:

import com.codersee.service.JwtService
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.auth.jwt.*

fun Application.configureSecurity(
  jwtService: JwtService
) {
  authentication {
    jwt {
      realm = jwtService.realm
      verifier(jwtService.jwtVerifier)

      validate { credential ->
        jwtService.customValidator(credential, jwtService)
      }
    }
  }
}

But what exactly is going on here?

The above code installs the Authentication plugin (authentication) with JWT Authentication provider (jwt).

Additionally, we must specify the realm, verifier, and the custom validate function that we implemented previously.

And what if we would like to have multiple providers in our project?

Well, we can do that easily by simply specifying a new one with a name:

import com.codersee.service.JwtService
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.auth.jwt.*

fun Application.configureSecurity(
  jwtService: JwtService
) {
  authentication {
    jwt {
      realm = jwtService.realm
      verifier(jwtService.jwtVerifier)

      validate { credential ->
        jwtService.customValidator(credential, jwtService)
      }
    }

    jwt("another-auth") {
      realm = jwtService.realm
      verifier(jwtService.jwtVerifier)

      validate { credential ->
        jwtService.customValidator(credential, jwtService)
      }
    }
  }
}

Later, we will see how to make use of these JWT auth providers, but for now, let’s navigate to the Application.kt file and make use of our new config:

import com.codersee.plugins.configureSecurity
import com.codersee.plugins.configureSerialization
import com.codersee.repository.UserRepository
import com.codersee.routing.configureRouting
import com.codersee.service.JwtService
import com.codersee.service.UserService
import io.ktor.server.application.*

fun main(args: Array<String>) {
  io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {
  val userRepository = UserRepository()
  val userService = UserService(userRepository)
  val jwtService = JwtService(this, userService)

  configureSerialization()
  configureSecurity(jwtService)
  configureRouting(jwtService, userService)
}

Expose Login Endpoint

Perfect! At this point we have everything we need to expose a new endpoint- POST /api/auth– which we will use to get JWT access tokens for our Ktor app based on the passed username and password.

So as the first step, let’s go to the Routing file, inject the JwtService and prepare a new route:

import com.codersee.service.JwtService
import com.codersee.service.UserService
import io.ktor.server.application.*
import io.ktor.server.routing.*

fun Application.configureRouting(
  jwtService: JwtService,
  userService: UserService
) {
  routing {

    route("/api/auth") {
      authRoute(jwtService)
    }

    route("/api/user") {
      userRoute(userService)
    }

  }
}

Nextly, let’s implement the LoginRequest inside the routing.request:

import kotlinx.serialization.Serializable

@Serializable
data class LoginRequest(
  val username: String,
  val password: String,
)

No traps here this time, so let’s create the AuthRoute.kt file:

import com.codersee.routing.request.LoginRequest
import com.codersee.service.JwtService
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Route.authRoute(jwtService: JwtService) {

  post {
    val user = call.receive<LoginRequest>()

    val token: String? = jwtService.createJwtToken(user.username)

    token?.let {
      call.respond(hashMapOf("token" to token))
    } ?: call.respond(
      message = HttpStatusCode.Unauthorized
    )
  }

}

This time, we read the request payload to the LoginRequest instance and we try to create a new JWT access token based on the username.

If we succeed (meaning a user with the following username was found and the password matches), then we return a fresh JWT access token. Otherwise, we simply return 401 Unauthorized to the API consumer.

At this point, we can test the app, for example by using curl (and if you would like to get a full Postman collection with automated token handling, then please leave a comment for this article).

Let’s start by creating a new user:

curl --location --request POST 'http://localhost:8080/api/user' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "user", 
    "password": "password"
}'

As a response, we should get 201 Created with the id in the response header.

Following, let’s try to get a JWT access token:

curl --location --request POST 'http://localhost:8080/api/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "user", 
    "password": "password"
}'

// Response:

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteS1hdWRpZW5jZSIsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3QvIiwidXNlcm5hbWUiOiJ1c2VyIiwiZXhwIjoxNzAwMTU2Mzg4fQ.DG8SsNrQI5-VqrZeZMFL4IRuVSLeo9Zs9dEifti9nvQ"
}

Excellent! So far so good.

You can even take this token and check it out using the jwt.io page 🙂

Secure User Endpoint

Finally, let’s secure user API endpoints:

fun Route.userRoute(userService: UserService) {

  post {
    val userRequest = call.receive<UserRequest>()

    val createdUser = userService.save(
      user = userRequest.toModel()
    ) ?: return@post call.respond(HttpStatusCode.BadRequest)

    call.response.header(
      name = "id",
      value = createdUser.id.toString()
    )
    call.respond(
      message = HttpStatusCode.Created
    )
  }

  authenticate {
    get {
      val users = userService.findAll()

      call.respond(
        message = users.map(User::toResponse)
      )
    }
  }

  authenticate("another-auth") {
    get("/{id}") {
      val id: String = call.parameters["id"]
        ?: return@get call.respond(HttpStatusCode.BadRequest)

      val foundUser = userService.findById(id)
        ?: return@get call.respond(HttpStatusCode.NotFound)

      if (foundUser.username != extractPrincipalUsername(call))
        return@get call.respond(HttpStatusCode.NotFound)

      call.respond(
        message = foundUser.toResponse()
      )
    }
  }
}

private fun UserRequest.toModel(): User =
  User(
    id = UUID.randomUUID(),
    username = this.username,
    password = this.password
  )

private fun User.toResponse(): UserResponse =
  UserResponse(
    id = this.id,
    username = this.username,
  )

private fun extractPrincipalUsername(call: ApplicationCall): String? =
  call.principal<JWTPrincipal>()
    ?.payload
    ?.getClaim("username")
    ?.asString()

As we can see, after our changes, every GET /api/user request will be verified using the provider, which we specified without the name.

When we check logs, we should even see the confirmation:

Matched routes:
“” -> “api” -> “user” -> “(authenticate “default”)” -> “(method:GET)”

On the other hand, every request to GET /api/user/{id} will be handled by the another-auth provider:

“” -> “api” -> “user” -> “(authenticate another-auth)” -> “{id}” -> “(method:GET)”

Lastly, it’s worth mentioning that we changed one more thing:

authenticate("another-auth") {
  get("/{id}") {
    val id: String = call.parameters["id"]
      ?: return@get call.respond(HttpStatusCode.BadRequest)

    val foundUser = userService.findById(id)
      ?: return@get call.respond(HttpStatusCode.NotFound)

    if (foundUser.username != extractPrincipalUsername(call))
      return@get call.respond(HttpStatusCode.NotFound)

    call.respond(
      message = foundUser.toResponse()
    )
  }
}


private fun extractPrincipalUsername(call: ApplicationCall): String? =
  call.principal<JWTPrincipal>()
    ?.payload
    ?.getClaim("username")
    ?.asString()

In this handler, we obtain the JWTPrincipal (created inside the JwtService) in order to read the username. If it matches with the found user, then we simply return the user response. But if not, then we return 404 Not Found.

Summary

And that’s all for this tutorial on how to implement a REST API with Ktor and Kotlin and how to secure it with JWT access tokens.

If you would like to find the whole source code, then check out this GitHub repository.

Lastly, if you enjoyed this tutorial, then please do not forget to share it with other people on your social media (it will help me a lot) and check out the continuation for this post:

• how to implement a refresh token flow with Ktor,
• and how to add a role-based access control (RBAC) to the project.

The post Secure REST API with Ktor and JWT Access Tokens appeared first on Codersee blog- Kotlin on the backend.

In this, comprehensive guide I will show you step-by-step how to:

• authenticate and authorize users,
• assign and verify roles,
• generate JWT tokens,
• and implement a refresh token flow.

And everything that with our beloved Kotlin programming language!

Video Tutorial

If you prefer video content, then you can find this tutorial as a YouTube playlist right here.

Alternatively, you can start from the introduction:

If you find this content useful, please leave a subscription  😉

What Exactly Will We Implement?

Well, in our project we will implement a REST API for articles and users.

Articles will be visible to any user who successfully authenticates using the JWT access token.

Users endpoint, on the other hand, will be accessible only for admin users in our system (with one exception- a public endpoint for creating new users).

Of course, we will expose additional authentication endpoints, which will take data from users, like email and password and generate access and refresh tokens for our system.

Long story short- I believe this project will be simple enough to easily understand the topic, and comprehensive enough to cover the most popular real-life cases.

A Tiny Bit Of Theory

In this paragraph, I’d like to cover what exactly JWT tokens are, the difference between authorization and authentication, and present from a bird’s eye view how Spring Security works.

So, if you feel that you understand these and came here for the practice, then please skip to the next chapter 😉

Authentication vs Authorization

I am pretty sure that you heard both terms plenty of times already and even heard people using them alternately.

Nevertheless, although similar, these two terms refer to completely different things.

Imagine you’re at the entrance of a super-secret club:

Authentication is like showing your ID to prove you are who you say you are. It’s the process of confirming your identity. So, in our club scenario, it’s like showing your driver’s license to the bouncer.

Authorization, on the other hand, is like being allowed into different parts of the club based on your VIP status. Once you’re inside (thanks to authentication), authorization decides what you can and cannot do. For example, VIP members might access the VIP lounge, while regular guests can’t.

JWT Tokens

Among plenty of existing ways to authenticate users, JWTs (JSON Web Tokens) are one of the most popular ones.

They are like a digital secret handshake on the internet. When we log into a website, the server gives us a special JWT. This token is like a digital badge that says, “Hey, this person is legit!”

Why are they so cool? Well, they are safe, compact, and allow us to hold information.

JWTs consist of three parts separated by dots: header.payload.signature:

As we can see, the encoded value can be easily decoded and JWT token values can be read.

The header typically consists of two parts: the type of the token (missing above), and the signing algorithm being used (HMAC SHA512).

The second part of the token is the payload, which contains the claims. Claims, Claims are statements about an entity (typically, the user) and additional data.

Lastly, the signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn’t changed along the way.

Bird’s Eye View on Spring Security

At this point, we know the difference between authentication and authorization and also what JWT tokens are. Awesome!

So, now I’ll try to do the impossible- explain how Spring Security works in a few sentences 🙂

Spring Security is like the security team of a building. It manages authentication and authorization for our app with:

1. Filters– think of security filters as checkpoints at different doors in the building. When a request comes in, it goes through these filters. These filters handle tasks like authentication and authorization. For instance, there might be a filter that checks if you have a proper access card (authentication), and another that ensures you can enter specific rooms (authorization).
2. Authentication– when you log in, Spring Security checks your credentials (like username and password). If they match, you’re authenticated. Spring Security uses authentication providers, which can be a database, LDAP, or any other source, to verify your identity.
3. Security Context– once authenticated, your security details are stored in the Security Context. It’s like being given a special pass after passing through the checkpoint. This pass (security context) contains your roles and permissions.
4. Authorization– now, when you try to access a specific part of the application, Spring Security checks your roles and permissions stored in the security context. If you’re authorized (based on your roles), you’re allowed in. Otherwise, you might be denied access.
5. Customization– Spring Security allows you to customize the security filters, authentication providers, and access rules according to your application’s requirements. You can configure which URLs need authentication, what roles are required, etc.

And that’s basically what we’re gonna learn today.

Import Spring Boot 3 Project

As the first step, let’s generate a new Spring Boot 3 project.

To do so, we can use the Spring Initializr page:

As we can see, in this project, we will use Spring Boot 3.1.5, Kotlin as a programming language, and Kotlin DSL for our Gradle build config.

At this point, the only dependency required to expose a REST API is Spring Web. We will add Spring Security, and libraries necessary for JWT tokens later (and we will see why later, too).

With all of that done, we can hit the generate button, download the zip file, and import it to IntelliJ.

Expose Articles API

Following, let’s implement the logic necessary to expose our first endpoint- GET /api/article .

In the future, this endpoint will be accessible only to users with a valid JWT token.

Create Article Model

As the first step, let’s introduce a new package- model – and create a new data class- Article:

import java.util.*

data class Article(
  val id: UUID,
  val title: String,
  val content: String,
)

This class consists of three example fields simulating a real-life article.

Implement Article Repository

Secondly, we must introduce a new class responsible for article retrieval and storage.

Let’s add the repository package and implement ArticleRepository:

import com.codersee.jwtauth.model.Article
import org.springframework.stereotype.Repository
import java.util.UUID

@Repository
class ArticleRepository {

  private val articles = listOf(
    Article(id = UUID.randomUUID(), title= "Article 1", content= "Content 1"),
    Article(id = UUID.randomUUID(), title= "Article 2", content= "Content 2"),
  )

  fun findAll(): List<Article> =
    articles

}

In our example, articles are nothing else, than a hardcoded private list of items.

Additionally, we expose the findAll() method, which encapsulates the list and which we will be invoking from outside the class.

Of course, I did it this way to keep it simple and so that we do not lose focus on what matters in this tutorial- Spring Boot security with Kotlin and JWT tokens.

Nevertheless, you can easily adjust this project to your needs. In real life, this would be the class where you can put logic responsible for communication with your database.

Create Service

As the next step, let’s create the service package and introduce the ArticleService:

import com.codersee.jwtauth.model.Article
import com.codersee.jwtauth.repository.ArticleRepository
import org.springframework.stereotype.Service

@Service
class ArticleService(
  private val articleRepository: ArticleRepository
) {

  fun findAll(): List<Article> =
    articleRepository.findAll()
}

As we can see, this class exposes the findAll() function and does nothing else than invoking the findAll() method from our repository.

Again, this might look a bit like an overengineering. But trust me, keeping a well-organized project from the very beginning will pay off in the future.

Expose Article REST API

Lastly, let’s add the controller.article package and put two classes in it.

Let’s start with the ArticleResponse:

import java.util.*

data class ArticleResponse(
  val id: UUID,
  val title: String,
  val content: String,
)

Before returning any article from our REST API, we will map model objects into the response objects.

And with that done, let’s implement the ArticleController:

import com.codersee.jwtauth.model.Article
import com.codersee.jwtauth.service.ArticleService
import org.springframework.web.bind.annotation.*
import java.util.*

@RestController
@RequestMapping("/api/article")
class ArticleController(
  private val articleService: ArticleService
) {

  @GetMapping
  fun listAll(): List<ArticleResponse> =
    articleService.findAll()
      .map { it.toResponse() }

  private fun Article.toResponse(): ArticleResponse =
    ArticleResponse(
      id = this.id,
      title = this.title,
      content = this.content,
    )
}

As we can see, we must annotate our controller class with the @RestController annotation in order to expose a REST API in Spring Boot.

Additionally, we add the @RequestMapping annotation so that whenever we hit the /api/article endpoint, Spring knows that this is the class it should use to handle the request.

Lastly, we mark the listAll() function with @GetMapping, and convert all found Article instances to the ArticleResponse.

Later, when we add the JWT security to our Spring Boot Kotlin project, these endpoints will be accessible only for ADMIN users with one exception- the endpoint responsible for creating new users- which will be publicly exposed.

Add User Model

With that said, let’s add the User.kt file to the model package:

import java.util.*

data class User(
  val id: UUID,
  val email: String,
  val password: String,
  val role: Role
)

enum class Role {
  USER, ADMIN
}

As we can see, apart from the id, the User class contains three important fields: email, password, and role, which we will extensively when dealing with JWT tokens.

Implement UserRepository

Following, let’s create the UserRepository in the repository package:

import com.codersee.jwtauth.model.Role
import com.codersee.jwtauth.model.User
import org.springframework.stereotype.Repository
import java.util.*

@Repository
class UserRepository {

  private val users = mutableSetOf(
    User(
      id = UUID.randomUUID(),
      email = "email-1@gmail.com",
      password = "pass1",
      role = Role.USER,
    ),
    User(
      id = UUID.randomUUID(),
      email = "email-2@gmail.com",
      password = "pass2",
      role = Role.ADMIN,
    ),
    User(
      id = UUID.randomUUID(),
      email = "email-3@gmail.com",
      password = "pass3",
      role = Role.USER,
    ),
  )

  fun save(user: User): Boolean =
    users.add(user)

  fun findByEmail(email: String): User? =
    users
      .firstOrNull { it.email == email }

  fun findAll(): Set<User> =
    users

  fun findByUUID(uuid: UUID): User? =
    users
      .firstOrNull { it.id == uuid }

  fun deleteByUUID(uuid: UUID): Boolean {
    val foundUser = findByUUID(uuid)

    return foundUser?.let {
      users.removeIf {
        it.id == uuid
      }
    } ?: false
  }
}

Similarly to our previous repository- we simply introduce a mutable list, which we can edit with a bunch of util methods.

And don’t worry about the password stored in plain text- we will get back to that topic, too 🙂

Add UserService

Nextly, we must go to the service package and introduce this UserService:

import com.codersee.jwtauth.model.User
import com.codersee.jwtauth.repository.UserRepository
import org.springframework.stereotype.Service
import java.util.*

@Service
class UserService(
  private val userRepository: UserRepository
) {

  fun createUser(user: User): User? {
    val found = userRepository.findByEmail(user.email)

    return if (found == null) {
      userRepository.save(user)
      user
    } else null
  }

  fun findByUUID(uuid: UUID): User? =
    userRepository.findByUUID(uuid)

  fun findAll(): List<User> =
    userRepository.findAll()
      .toList()

  fun deleteByUUID(uuid: UUID): Boolean =
    userRepository.deleteByUUID(uuid)
}

Nothing spectacular here, so let’s move to the next step.

Expose User REST API

Just like with articles, let’s start with introducing request/response objects.

This time, we will need both the UserRequest:

data class UserRequest(
  val email: String,
  val password: String,
)

And the UserResponse, which will be serialized into JSON objects:

import java.util.*

data class UserResponse(
  val uuid: UUID,
  val email: String,
)

And with that done, we can add the UserController class:

import com.codersee.jwtauth.model.Role
import com.codersee.jwtauth.model.User
import com.codersee.jwtauth.service.UserService
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.*
import org.springframework.web.server.ResponseStatusException
import java.util.*

@RestController
@RequestMapping("/api/user")
class UserController(
  private val userService: UserService
) {

  @PostMapping
  fun create(@RequestBody userRequest: UserRequest): UserResponse =
    userService.createUser(userRequest.toModel())
      ?.toResponse()
      ?: throw ResponseStatusException(HttpStatus.BAD_REQUEST, "Cannot create user.")

  @GetMapping
  fun listAll(): List<UserResponse> =
    userService.findAll()
      .map { it.toResponse() }

  @GetMapping("/{uuid}")
  fun findByUUID(@PathVariable uuid: UUID): UserResponse =
    userService.findByUUID(uuid)
      ?.toResponse()
      ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User not found.")


  @DeleteMapping("/{uuid}")
  fun deleteByUUID(@PathVariable uuid: UUID): ResponseEntity<Boolean> {
    val success = userService.deleteByUUID(uuid)

    return if (success)
      ResponseEntity.noContent()
        .build()
    else
      throw ResponseStatusException(HttpStatus.NOT_FOUND, "User not found.")
  }

  private fun User.toResponse(): UserResponse =
    UserResponse(
      uuid = this.id,
      email = this.email,
    )

  private fun UserRequest.toModel(): User =
    User(
      id = UUID.randomUUID(),
      email = this.email,
      password = this.password,
      role = Role.USER,
    )
}

As we can see, the logic above is pretty similar to what we’ve done before.

We mark our class with @RestController and @RequestMapping, functions with annotations matching HTTP Methods they are gonna handle, and also our path variables and request bodies.

When converting between models/requests/responses, we make use of extension functions, which are my favorite approach for mappers in Kotlin.

Lastly, whenever we want to return anything else than 200 OK, we use the ResponseStatusException, which is a clean way to do so.

If you would like to test this API now, then check out the following Postman collection.

Import Spring Security and JWT Library

Wonderful. At this point, we have everything we need to finally add Spring Security to our Spring Boot Kotlin project, and start implementing JWT authentication and authorization.

Update build.gradle.kts

As the first step, let’s add the following to the build.gradle.kts file:

dependencies {
	// other imports
	implementation("io.jsonwebtoken:jjwt-api:0.12.3")
	implementation("io.jsonwebtoken:jjwt-impl:0.12.3")
	implementation("io.jsonwebtoken:jjwt-jackson:0.12.3")
	implementation("org.springframework.boot:spring-boot-starter-security")
	testImplementation("org.springframework.security:spring-security-test")
}

As we can see, in order to secure our Spring Boot 3 REST API, we must add not only the Spring Security but also an additional library to deal with JWT tokens.

Although the Spring security is a must-have, please feel free to choose whatever JWT library suits you best (you can find a full list here). I have decided to go with io.jsonwebtoken which is the most popular Java library.

Sync and Rerun Project

Following, let’s sync our Gradle project and rerun our application.

Among other logs, we will see the following lines:

Using generated security password: 52d7d5b8-ce49-4d93-a4e1-721780290e58

This generated password is for development use only. Your security configuration must be updated before running your application in production.

Moreover, when we try to query our endpoints, we will get 401 Unauthorized for each request.

But what happened?

Well, whenever we add Spring Security to our Spring Boot project, the authentication gets enabled by default.

In other words, we can query our endpoint now using the basic access authentication with user as a username and the randomly generated password as the password.

As a proof, when we update the Authorization in our Postman collection, we will start seeing results again:

Create JWT Tokens

Although basic auth may be a good choice in some cases, in this tutorial, I would like to show you how to authenticate and authorize requests using JWT access tokens.

So, let’s start everything by implementing a service responsible for token operations.

Edit application.yaml file

As the first step, let’s navigate to the resources folder and edit the application.yaml file:

Note: when generating a new Spring Boot project, the application.properties file is created automatically. So before we start, let’s change the extension to yaml.

jwt:
  key: ${JWT_KEY}
  access-token-expiration: 3600000
  refresh-token-expiration: 86400000

As we can see, we introduce 3 custom properties: the key and expiration time (in milliseconds) for both access and refresh tokens.

The key is value will be sourced from the JWT_TOKEN environment variable, which is nothing else than a randomly generated String value. Later, we will see where and why we need it.

Important: vulnerable values should never be hardcoded when implementing a Spring Boot (and not only) application.

Regardless of the environment the app is running in, values should be stored securely and sourced to our application using environment variables.

Make Use Of @ConfigurationProperties

As the next step, let’s make use of the @ConfigurationProperties to easily convert our properties into Kotlin objects.

Let’s start by adding the configuration package and the JwtProperties class:

import org.springframework.boot.context.properties.ConfigurationProperties

@ConfigurationProperties("jwt")
data class JwtProperties(
  val key: String,
  val accessTokenExpiration: Long,
  val refreshTokenExpiration: Long,
)

If you’d like to learn more about @ConfigurationProperties, then I have another article you might want to check out later.

Additionally, let’s add the Configuration class:

import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Configuration


@Configuration
@EnableConfigurationProperties(JwtProperties::class)
class Configuration

This way, we enable support for beans annotated with @ConfigurationProperties in our project.

Add TokenService

With all of that done, let’s add the TokenService class:

@Service
class TokenService(
  jwtProperties: JwtProperties
) {

  private val secretKey = Keys.hmacShaKeyFor(
    jwtProperties.key.toByteArray()
  )

  fun generate(
    userDetails: UserDetails,
    expirationDate: Date,
    additionalClaims: Map<String, Any> = emptyMap()
  ): String =
    Jwts.builder()
      .claims()
      .subject(userDetails.username)
      .issuedAt(Date(System.currentTimeMillis()))
      .expiration(expirationDate)
      .add(additionalClaims)
      .and()
      .signWith(secretKey)
      .compact()

  fun isValid(token: String, userDetails: UserDetails): Boolean {
    val email = extractEmail(token)

    return userDetails.username == email && !isExpired(token)
  }

  fun extractEmail(token: String): String? =
    getAllClaims(token)
      .subject

  fun isExpired(token: String): Boolean =
    getAllClaims(token)
      .expiration
      .before(Date(System.currentTimeMillis()))

  private fun getAllClaims(token: String): Claims {
    val parser = Jwts.parser()
      .verifyWith(secretKey)
      .build()

    return parser
      .parseSignedClaims(token)
      .payload
  }
}

As we can see, this class exposes functions, which we can use to deal with JWT access and refresh tokens.

Let’s walk quickly through our logic:

private val secretKey = Keys.hmacShaKeyFor(
  jwtProperties.key.toByteArray()
)

The secretKey is nothing else than an instance of SecretKey, which we will use to sign and verify JWT tokens in our system. In our case, we will use the HMAC-SHA algorithm based on the random key we provided to our project.

fun generate(
  userDetails: UserDetails,
  expirationDate: Date,
  additionalClaims: Map<String, Any> = emptyMap()
): String =
  Jwts.builder()
    .claims()
    .subject(userDetails.username)
    .issuedAt(Date(System.currentTimeMillis()))
    .expiration(expirationDate)
    .add(additionalClaims)
    .and()
    .signWith(secretKey)
    .compact()

The generate function is responsible for creating a serialized, URL-safe String with JWT tokens. We set the subject, expiration date, and additional claims based on the arguments passed to it.

Lastly, we sign the token using the SecretKey instance created in the previous step.

Additionally, we provide more functions which we will use later to extract values from tokens and validate them:

fun isValid(token: String, userDetails: UserDetails): Boolean {
  val email = extractEmail(token)

  return userDetails.username == email && !isExpired(token)
}

fun extractEmail(token: String): String? =
  getAllClaims(token)
    .subject

fun isExpired(token: String): Boolean =
  getAllClaims(token)
    .expiration
    .before(Date(System.currentTimeMillis()))

private fun getAllClaims(token: String): Claims {
  val parser = Jwts.parser()
    .verifyWith(secretKey)
    .build()

  return parser
    .parseSignedClaims(token)
    .payload
}

Implement Custom UserDetailsService

As the next step, let’s introduce a custom implementation of UserDetailsService.

But what exactly is UserDetailsService and UserDetails?

Well, the UserDetails represents the core user information. In our case, we will use the default implementation called User, which holds the default information, such as username, password, and a collection of granted authorities (roles).

The UserDetailsService is nothing else than an interface used to load user-specific data. It is used by Spring Security to interact with our data source and validate users during authentication.

With that said, let’s add a new class- CustomUserDetailsService– to the service package:

import com.codersee.jwtauth.repository.UserRepository
import org.springframework.security.core.userdetails.User
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.core.userdetails.UsernameNotFoundException
import org.springframework.stereotype.Service

typealias ApplicationUser = com.codersee.jwtauth.model.User

@Service
class CustomUserDetailsService(
  private val userRepository: UserRepository
) : UserDetailsService {

  override fun loadUserByUsername(username: String): UserDetails =
    userRepository.findByEmail(username)
      ?.mapToUserDetails()
      ?: throw UsernameNotFoundException("Not found!")

  private fun ApplicationUser.mapToUserDetails(): UserDetails =
    User.builder()
      .username(this.email)
      .password(this.password)
      .roles(this.role.name)
      .build()
}

As we can see, both the username and email in our system refer to the same thing, which is used to uniquely identify users.

And in order to fetch UserDetails we must find the user in our repository and map it to the User instance.

Additionally, we make use of the typealias which is a great way to avoid fully qualified name (we have both User in our model package and User from Spring Security

Update Configuration

With that done, let’s get back to the Configuration class and register a few beans:

import com.codersee.jwtauth.repository.UserRepository
import com.codersee.jwtauth.service.CustomUserDetailsService
import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.AuthenticationProvider
import org.springframework.security.authentication.dao.DaoAuthenticationProvider
import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder
import org.springframework.security.crypto.password.PasswordEncoder

@Configuration
@EnableConfigurationProperties(JwtProperties::class)
class Configuration {

  @Bean
  fun userDetailsService(userRepository: UserRepository): UserDetailsService =
    CustomUserDetailsService(userRepository)

  @Bean
  fun encoder(): PasswordEncoder = BCryptPasswordEncoder()

  @Bean
  fun authenticationProvider(userRepository: UserRepository): AuthenticationProvider =
    DaoAuthenticationProvider()
      .also {
        it.setUserDetailsService(userDetailsService(userRepository))
        it.setPasswordEncoder(encoder())
      }

  @Bean
  fun authenticationManager(config: AuthenticationConfiguration): AuthenticationManager =
    config.authenticationManager
}

Firstly, we must register the bean of type UserDetailsService, which we introduced in the previous step.

Following, we register a PasswordEncoder. To put it simply, we should never store passwords in plain text. They should be always encrypted, or hashed. In this tutorial, we will use the BCrypt strong hashing function for that purpose.

Following, we must provide the AuthenticationProvider and configure which UserDetailsService we will use and the password encoder.

Update UserRepository

In the previous step, I mentioned that we should never store passwords in plain text.

So, to fix that, let’s get back to the UserRepository and make the necessary changes:

@Repository
class UserRepository(
  private val encoder: PasswordEncoder
) {

  private val users = mutableSetOf(
    User(
      id = UUID.randomUUID(),
      email = "email-1@gmail.com",
      password = encoder.encode("pass1"),
      role = Role.USER,
    ),
    User(
      id = UUID.randomUUID(),
      email = "email-2@gmail.com",
      password = encoder.encode("pass2"),
      role = Role.ADMIN,
    ),
    User(
      id = UUID.randomUUID(),
      email = "email-3@gmail.com",
      password = encoder.encode("pass3"),
      role = Role.USER,
    ),
  )

  fun save(user: User): Boolean {
    val updated = user.copy(password = encoder.encode(user.password))

    return users.add(updated)
  }
}

As we can see, after this step both our predefined users and all users which we will create will have their passwords hashed.

Implement AuthenticationFilter

Uff, quite a lot of preparation must be done before we secure our Spring Boot 3 Kotlin app with JWT tokens, isn’t it?

But don’t worry, we’re almost there.

As the next step, let’s navigate to the config package and introduce our custom Filter:

import com.codersee.jwtauth.service.CustomUserDetailsService
import com.codersee.jwtauth.service.TokenService
import jakarta.servlet.FilterChain
import jakarta.servlet.http.HttpServletRequest
import jakarta.servlet.http.HttpServletResponse
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource
import org.springframework.stereotype.Component
import org.springframework.web.filter.OncePerRequestFilter

@Component
class JwtAuthenticationFilter(
  private val userDetailsService: CustomUserDetailsService,
  private val tokenService: TokenService,
) : OncePerRequestFilter() {

  override fun doFilterInternal(
    request: HttpServletRequest,
    response: HttpServletResponse,
    filterChain: FilterChain
  ) {
    val authHeader: String? = request.getHeader("Authorization")

    if (authHeader.doesNotContainBearerToken()) {
      filterChain.doFilter(request, response)
      return
    }

    val jwtToken = authHeader!!.extractTokenValue()
    val email = tokenService.extractEmail(jwtToken)

    if (email != null && SecurityContextHolder.getContext().authentication == null) {
      val foundUser = userDetailsService.loadUserByUsername(email)

      if (tokenService.isValid(jwtToken, foundUser))
        updateContext(foundUser, request)

      filterChain.doFilter(request, response)
    }
  }

  private fun String?.doesNotContainBearerToken() =
    this == null || !this.startsWith("Bearer ")

  private fun String.extractTokenValue() =
    this.substringAfter("Bearer ")

  private fun updateContext(foundUser: UserDetails, request: HttpServletRequest) {
    val authToken = UsernamePasswordAuthenticationToken(foundUser, null, foundUser.authorities)
    authToken.details = WebAuthenticationDetailsSource().buildDetails(request)
    SecurityContextHolder.getContext().authentication = authToken
  }

}

I know, quite a lot of logic, but I’ll explain it step-by-step in a moment.

But before that, let’s understand what are Filters in Spring Framework.

Well, every request made to our Spring Framework application goes through the filter chain, where each filter in the chain can perform some operations on the request or response.

In our case, we want to use this feature to authenticate requests made to our REST API. We want to check whether a user sent a JWT token and validate it, and if everything is fine, we want to update the Spring Security Context.

And that’s exactly what’s happening in the code above.

Firstly, we check if the request contains an Authorization header. If no, we do not proceed with this function and we simply pass the request down the filter chain.

Nextly, we extract the JWT token. A valid Authorization header value consists of the Bearer <JWT>, so we must extract the token itself.

Following, we read the email value from the token. And when we make sure it is not null and there’s no previously authenticated principal in the security context, we fetch the UserDetails, which we then use to validate them with the token.

Lastly, we simply update the security context in our system with foundUser (which is UserDetails) and authorities (which, in our case will be either ADMIN or USER).

To sum up, this function will be invoked once per each request. In simple terms, it will check the JWT token and if everything is fine, it will update the Spring Security context with information about user and its roles.

Add Security Configuration

At this point, we did everything we needed to to in order to authenticate the user.

In this step, we will learn how to authorize him.

And to do so, let’s introduce a new class- SecurityConfiguration – in the config package:

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.http.HttpMethod
import org.springframework.security.authentication.AuthenticationProvider
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity
import org.springframework.security.config.http.SessionCreationPolicy
import org.springframework.security.web.DefaultSecurityFilterChain
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter

@Configuration
@EnableWebSecurity
class SecurityConfiguration(
  private val authenticationProvider: AuthenticationProvider
) {

  @Bean
  fun securityFilterChain(
    http: HttpSecurity,
    jwtAuthenticationFilter: JwtAuthenticationFilter
  ): DefaultSecurityFilterChain {
    http
      .csrf { it.disable() }
      .authorizeHttpRequests {
        it
          .requestMatchers("/api/auth", "api/auth/refresh", "/error")
          .permitAll()
          .requestMatchers(HttpMethod.POST, "/api/user")
          .permitAll()
          .requestMatchers("/api/user**")
          .hasRole("ADMIN")
          .anyRequest()
          .fullyAuthenticated()
      }
      .sessionManagement {
        it.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
      }
      .authenticationProvider(authenticationProvider)
      .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter::class.java)

    return http.build()
  }
}

As we can see, the above config exposes a new bean of type DefaultSecurityFilterChain.

To put it simply, this is the way we can modify the default chain by adding, removing, or replacing filters to tailor the security configuration according to our needs.

The first thing we do is disable the CSRF protection. It’s enabled by default, and in most cases not needed (but in real-life projects, please learn a bit more about CSRF attacks and whether your codebase is vulnerable).

Following, we configure the authorization. We can clearly see that requests to “/api/auth”, “api/auth/refresh”, “/error”, and POST requests to “/api/user” will be accessible without a token. And that’s correct- we cannot require a valid access token for users, who want to sign in, who want to create a new account, and when the API client wants to refresh the token.

And if you are wondering why is the “/error” in this list, too, then here comes the answer. It is because of the way Spring handles errors internally. Without that, every exception we throw in our codebase will return 403 Forbidden, instead of the HTTP status code we provided.

When it comes to the rest of the “/api/user” requests- we want to allow only users with role ADMIN.

And what with the rest of the requests? Well, we want them to be accessed only by fully authenticated users. But what does it mean? In our, stateless REST API, it means simply that every user with a valid JWT token will be able to access them (regardless of his role).

After that, we informed Spring that it should never create a HttpSession (we want our security to be stateless) and that it should never use it to obtain the SecurityContext.

And lastly, we register our CustomAuthenticationProvider and let Spring Security know that JwtAuthenticationFilter we implemented previously should be added before the default UsernamePasswordAuthenticationFilter (the one that required us to specify basic auth).

Expose Login Endpoint – Generate Access Token

With all of that done, we can finally expose the endpoint, which will be used by our REST API consumers to get the JWT access token.

Let’s create the config.auth package and add a new controller class:

import com.codersee.jwtauth.service.AuthenticationService
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/api/auth")
class AuthController(
  private val authenticationService: AuthenticationService
) {

  @PostMapping
  fun authenticate(
    @RequestBody authRequest: AuthenticationRequest
  ): AuthenticationResponse =
    authenticationService.authentication(authRequest)

}

As we can see, this controller uses AuthenticationService which we will implement in a moment.

But before we do so, let’s add the AuthenticationRequest:

data class AuthenticationRequest(
  val email: String,
  val password: String,
)

And the response class:

data class AuthenticationResponse(
  val accessToken: String,
)

After that, let’s get back to the service package and implement a service, which will be responsible for authentication and token generation:

import com.codersee.jwtauth.controller.auth.AuthenticationRequest
import com.codersee.jwtauth.controller.auth.AuthenticationResponse
import com.codersee.jwtauth.controller.config.JwtProperties
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.stereotype.Service
import java.util.*

@Service
class AuthenticationService(
  private val authManager: AuthenticationManager,
  private val userDetailsService: CustomUserDetailsService,
  private val tokenService: TokenService,
  private val jwtProperties: JwtProperties,
) {

  fun authentication(authenticationRequest: AuthenticationRequest): AuthenticationResponse {
    authManager.authenticate(
      UsernamePasswordAuthenticationToken(
        authenticationRequest.email,
        authenticationRequest.password
      )
    )

    val user = userDetailsService.loadUserByUsername(authenticationRequest.email)

    val accessToken = createAccessToken(user)

    return AuthenticationResponse(
      accessToken = accessToken,
    )
  }

  private fun createAccessToken(user: UserDetails) = tokenService.generate(
    userDetails = user,
    expirationDate = getAccessTokenExpiration()
  )

  private fun getAccessTokenExpiration(): Date =
    Date(System.currentTimeMillis() + jwtProperties.accessTokenExpiration)

}

As we can see, the first thing we do is invoke the authenticate method from AuthenticationManager.

If the email and password values don’t match with any of the users in our system, the authenticate method will throw AuthenticationException and the API will return 403 Forbidden.

On the other hand, when they match, we will fetch the UserDetails and use it to generate a JWT token with an expiration time set in application.yaml

At the moment, I highly encourage you to run our application and try to call endpoints with different cases. If you would like to use a ready-to-go Postman collection, then you can find one with all endpoints in the next chapter about refresh tokens.

JWT Refresh Token

Excellent! At this point, our REST API is properly secured and utilizing the JWT access tokens.

But depending on your needs, you may want to introduce the JWT refresh tokens to the system.

Introduce New Endpoint

Firstly, let’s introduce a new endpoint and update our response classes.

Let’s start by adding a new TokenResponse:

data class TokenResponse(
  val token: String
)

We will use this class to return the refreshed access token.

Following, let’s make the necessary changes to the AuthenticationResponse:

data class AuthenticationResponse(
  val accessToken: String,
  val refreshToken: String,
)

As we can see, the refreshToken value will be returned when a user authenticates successfully along with the JWT token value.

After that, let’s add the RefreshTokenRequest, which will be used to deserialize refresh token sent by a user:

data class RefreshTokenRequest(
  val token: String
)

Great!

At this point, we can add a new endpoint:

  @PostMapping("/refresh")
  fun refreshAccessToken(
    @RequestBody request: RefreshTokenRequest
  ): TokenResponse =
    authenticationService.refreshAccessToken(request.token)
      ?.mapToTokenResponse()
      ?: throw ResponseStatusException(HttpStatus.FORBIDDEN, "Invalid refresh token.")

  private fun String.mapToTokenResponse(): TokenResponse =
    TokenResponse(
      token = this
    )

Don’t worry about the missing refreshAccessToken method, we will get back to it in a moment.

Implement Refresh Token Repository

As the next step, let’s go to the repository package and introduce the RefreshTokenRepository:

import org.springframework.security.core.userdetails.UserDetails
import org.springframework.stereotype.Component

@Component
class RefreshTokenRepository {

  private val tokens = mutableMapOf<String, UserDetails>()

  fun findUserDetailsByToken(token: String) : UserDetails? =
    tokens[token]

  fun save(token: String, userDetails: UserDetails) {
    tokens[token] = userDetails
  }

}

As we can see, this class will be responsible for persisting and retrieving refresh tokens.

Along with our tokens, we will store the associated UserDetails instances, so that later we could match the associated subject (email).

Edit AuthenticationService

As the last thing, we must get back to the AuthenticationService and make the necessary changes:

import com.codersee.jwtauth.controller.auth.AuthenticationRequest
import com.codersee.jwtauth.controller.auth.AuthenticationResponse
import com.codersee.jwtauth.controller.config.JwtProperties
import com.codersee.jwtauth.repository.RefreshTokenRepository
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.stereotype.Service
import java.util.*

@Service
class AuthenticationService(
  private val authManager: AuthenticationManager,
  private val userDetailsService: CustomUserDetailsService,
  private val tokenService: TokenService,
  private val jwtProperties: JwtProperties,
  private val refreshTokenRepository: RefreshTokenRepository,
) {

  fun authentication(authenticationRequest: AuthenticationRequest): AuthenticationResponse {
    authManager.authenticate(
      UsernamePasswordAuthenticationToken(
        authenticationRequest.email,
        authenticationRequest.password
      )
    )

    val user = userDetailsService.loadUserByUsername(authenticationRequest.email)

    val accessToken = createAccessToken(user)
    val refreshToken = createRefreshToken(user)

    refreshTokenRepository.save(refreshToken, user)

    return AuthenticationResponse(
      accessToken = accessToken,
      refreshToken = refreshToken
    )
  }

  fun refreshAccessToken(refreshToken: String): String? {
    val extractedEmail = tokenService.extractEmail(refreshToken)

    return extractedEmail?.let { email ->
      val currentUserDetails = userDetailsService.loadUserByUsername(email)
      val refreshTokenUserDetails = refreshTokenRepository.findUserDetailsByToken(refreshToken)

      if (!tokenService.isExpired(refreshToken) && refreshTokenUserDetails?.username == currentUserDetails.username)
        createAccessToken(currentUserDetails)
      else
        null
    }
  }

  private fun createAccessToken(user: UserDetails) = tokenService.generate(
    userDetails = user,
    expirationDate = getAccessTokenExpiration()
  )

  private fun createRefreshToken(user: UserDetails) = tokenService.generate(
    userDetails = user,
    expirationDate = getRefreshTokenExpiration()
  )

  private fun getAccessTokenExpiration(): Date =
    Date(System.currentTimeMillis() + jwtProperties.accessTokenExpiration)

  private fun getRefreshTokenExpiration(): Date =
    Date(System.currentTimeMillis() + jwtProperties.refreshTokenExpiration)
}

Let’s summarize what exactly has changed here.

Firstly, we imported the RefreshTokenRepository, so that we could persist new tokens and retrieve the saved ones.

Moreover, we must generate a new refresh token whenever a user authenticates successfully. And that’s why we added the getRefreshTokenExpiration function and two additional lines in the authentication method.

When it comes to the refresh token flow, it can be summarized in the following steps:

1. We extract the user email from the passed refresh token.
2. If this step is completed successfully, we fetch the current user details by the value.
3. After that, we look for the persisted user details with the refresh token.
4. Lastly, if the refresh token is not expired and the email from JWT subject matches the current user details, then a new access token is generated for that user.
5. Otherwise, we return null, which will be translated to 403 Forbidden in our controller.

And basically, that’s all 🙂

If you would like to use a ready-to-go Postman collection with auh headers, then you can find it right here.

Summary

And that’s all for this tutorial in which we have learned how to secure the REST API with Spring Boot 3 (Spring Security 6) with JWT access and refresh tokens and Kotlin. Good job!

If you would like to get the source code for this lesson, then check out this GitHub repository.

Lastly, if you enjoyed this one, then do not forget to leave a comment and check out my Complete Kotlin Course 🙂

The post Spring Boot 3 (Spring Security 6) with Kotlin & JWT appeared first on Codersee blog- Kotlin on the backend.