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.

Hello and welcome to the first article in a series showing how to use Keycloak with Spring Boot applications.

In this step by step guide, I will show you how to set up a Keycloak server and connect to it using Spring Boot and Kotlin. Additionally, you will learn how to secure REST endpoints with Keycloak combined with the @PreAuthorize annotation.

2. What is Keycloak?

According to the documentation, Keycloak is the Open Source Identity and Access Management solution. In simple terms, it allows us to add authentication and secure our applications with minimum effort. With Keycloak, plenty of topics, like user storage, authentication, and many many more, are available out of the box.

In addition, the keycloak-spring-boot-starter makes all the process of configuration really straightforward, thus saving our precious time.

3. Install Keycloak

As the first step in this tutorial will be the installation of the Keycloak server. There are plenty of ways to achieve that, and I highly recommend you visit the official documentation to choose the most suitable one for you.

To keep this tutorial as simple as possible, I’ve decided to deploy it as a Docker container. If you have the Docker environment already installed on your machine, all you need to do is to type the following command:

docker run -p 8090:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -e DB_VENDOR=h2 quay.io/keycloak/keycloak:11.0.3

With this command, we create a container using the keycloak:11.0.3 image and publish it’s 8080 port to the 8180 port of the host. Additionally, we pass the KEYCLOAK_USER and KEYCLOAK_PASSWORD environment variables for the initial admin user (root).

However, the simplicity comes with its own restrictions. By default, the Keycloak server runs using the H2 database, so all the configuration will be lost after the container is terminated. To prevent that we can export a realm configuration to the JSON file (I will show you this step later).

3. Configure Keycloak

Once the Keycloak server is up and running, let’s head to the administration console. All we need to do is to type http://localhost:8090 in the address bar of the browser. We should see the following page:

On the next page, we should see the login form. Let’s enter the credentials for the admin account we’ve already configured:

3.1. Create Realm

After we’ve authenticated successfully, we can create a new realm. In Keycloak, realms manage a set of users, credentials, roles, and groups. Each user belongs to and logs into some realm. Moreover, they are completely isolated environments, which introduce an additional layer of security to our application.

As the next step, let’s navigate to the Add realm button:

On the next page, let’s type the name for the new realm and hit the create button:

Please remember this name, we will need it to configure the Spring Boot application later.

3.2. Create Roles

Nextly, let’s create some roles for our future users. Let’s navigate to the Roles tab on the left sidebar. On the next screen, we should see the list of already existing roles. Let’s click the Add role button placed in the right part of the screen.

Firstly, let’s type the ROLE_USER and click save. After that, let’s add the ROLE_ADMIN which will be a composite role associated with the previous one:

Please notice two important things here:

• A composite role combines together multiple roles. To put it simply- a user with the ROLE_ADMIN will be able to access all endpoints restricted for ROLE_USER. It helps to clean the architecture of the security a lot, however, please be careful not to introduce an additional gap to the system when using it.
• Both roles have been prefixed with a ROLE_. Spring Security will automatically prefix hasRole checks with the same value.

3.3. Create Clients

As the next step, let’s create clients. Most often, Keycloak clients are the applications and services we would like to secure, or which are obtaining tokens to access other applications.

For the purpose of this tutorial, we will create two clients. Let’s start the one, we will use to configure our Spring Boot application:

Please notice, that we’ve set the Access Type to bearer-only. It means, that our application will not initiate a login, it’ll just pass received tokens to verify them with Keycloak. Most of the time, you will set this type of access type for the Spring Boot backends, which don’t need to call another microservices secured by Keycloak, or to use a service account.

Nextly, let’s create the public client, which will be used to get access tokens on behalf of the user:

This time, only the Direct Access Grants flow is enabled and the Access Type is set to public.
The public access type is used for clients, which cannot keep secrets securely, like frontend applications for instance.

3.4. Create Users

As the last step for Keycloak configuration, we will create users. Let’s head to the Users page, and create a user names example_user:

Let’s mark him enabled and his email verified as well.

The next important thing we need to do is to set the password for the user in the Credentials tab:

And as the last step, let’s add the desired role to the user. Let’s select the ROLE_USER and hit the Add selected button, just like below:

Please repeat the same steps for the admin user. The only difference will be the selection of the ROLE_ADMIN instead.

4. Configure Spring Boot App

4.1. Imports

As usual, we will start the configuration of our Spring Boot application with imports. Let’s head to the build.gradle.kts file and add the following dependencies:

implementation("org.springframework.boot:spring-boot-starter-web")
implementation("org.keycloak:keycloak-spring-boot-starter:11.0.3")
implementation("org.springframework.boot:spring-boot-starter-security:2.4.0")

4.2. Configure Application Properties

As the next step, let’s open the /resources/application.yaml file and paste the following config:

keycloak:
  realm: example
  resource: spring-boot
  bearer-only: true
  auth-server-url: http://localhost:8090/auth

Let’s see what each of the above configs mean:

• realm– as the name suggests, it is the name of the created realm,
• resource– matches the name of the created client,
• bearer-only– this flag indicates, that our service has been created as a bearer-only, by default it is set to false,
• auth-server-url– it is the URL of our Keycloak server

4.3. Configure Spring Security

As the next step, let’s create the WebSecurityConfig class:

@KeycloakConfiguration
@EnableGlobalMethodSecurity(prePostEnabled = true)
class WebSecurityConfig : KeycloakWebSecurityConfigurerAdapter() {

    @Autowired
    fun configureGlobal(auth: AuthenticationManagerBuilder) {
        val keycloakAuthenticationProvider = keycloakAuthenticationProvider()
        keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(SimpleAuthorityMapper())
        auth.authenticationProvider(keycloakAuthenticationProvider)
    }

    @Bean
    override fun sessionAuthenticationStrategy(): SessionAuthenticationStrategy {
        return NullAuthenticatedSessionStrategy()
    }

    @Bean
    fun keycloakConfigResolver(): KeycloakConfigResolver {
        return KeycloakSpringBootConfigResolver()
    }

    override fun configure(http: HttpSecurity) {
        super.configure(http)
        http
            .authorizeRequests()
            .antMatchers("/api/public/**").permitAll()
            .anyRequest().fullyAuthenticated()
    }
}

I totally understand that this config might be a little overwhelming, so let’s just break it down:

@KeycloakConfiguration
@EnableGlobalMethodSecurity(prePostEnabled = true)
class WebSecurityConfig : KeycloakWebSecurityConfigurerAdapter()

@KeycloakConfiguration annotation provides a Keycloak based Spring security configuration. It is used with classes extending KeycloakWebSecurityConfigurerAdapter, just like in our case. The @EnableGlobalMethodSecurity with prePostEnabled set to true enables the Spring Security global method security and @PreAuthorize annotations.

@Autowired
fun configureGlobal(auth: AuthenticationManagerBuilder) {
    val keycloakAuthenticationProvider = keycloakAuthenticationProvider()
    keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(SimpleAuthorityMapper())
    auth.authenticationProvider(keycloakAuthenticationProvider)
}

The configureGlobal function takes the AuthenticationManagerBuilder bean as a parameter and sets the KeycloakAuthenticationProvider as the authentication provider. Additionally, it sets the SimpleAuthorityMapper as the authority mapper.

@Bean
override fun sessionAuthenticationStrategy(): SessionAuthenticationStrategy {
    return NullAuthenticatedSessionStrategy()
}

@Bean
fun keycloakConfigResolver(): KeycloakConfigResolver {
    return KeycloakSpringBootConfigResolver()
}

With these two functions, we declare the KeycloakSpringBootConfigResolver bean and that we do not want the session to be created, as well.

override fun configure(http: HttpSecurity) {
    super.configure(http)
    http
        .authorizeRequests()
        .antMatchers("/api/public/**").permitAll()
        .anyRequest().fullyAuthenticated()
}

Finally, we override the configure method derived from the KeycloakWebSecurityConfigurerAdapter. With this config, all requests except the /api/public/** need to be fully authenticated.

5. Create Rest Controller

With all the above being done, we can create an ExampleController class, which consists of three endpoints:

@RestController
@RequestMapping("/api")
class ExampleController {

    @GetMapping("/example")
    @PreAuthorize("hasRole('USER')")
    fun getUserInfo(): ResponseEntity<String> =
        ResponseEntity.ok("User info")

    @GetMapping("/example/admin")
    @PreAuthorize("hasRole('ADMIN')")
    fun getAdminInfo(): ResponseEntity<String> =
        ResponseEntity.ok("Admin info")

    @GetMapping("/public/example")
    fun getPublicInfo(): ResponseEntity<String> =
        ResponseEntity.ok("Public info")
}

The first two of them require the user to either have the ROLE_USER or ROLE_ADMIN assigned to him. Nevertheless, the last endpoint permits anyone, even without the token.

6. Testing with cURL

Finally, we can validate if everything is working as expected.

Let’s start by obtaining the access token:

curl --location --request POST 'http://localhost:8090/auth/realms/example/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=some_user' \
--data-urlencode 'password=password' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=public'

As the result we should get the following JSON object:

{
    "access_token":  [TOKEN],
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": [TOKEN],
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "7981f2e1-4e50-44d6-ac81-2ba508a59680",
    "scope": "email profile"
}

The most important part of the response for us is the JWT access token, which we will use to query our endpoints. If you would like to see, how many informations are encoded within it, I highly recommend to visit jwt.io and check it out.

To fully validate our endpoints, let’s query all of them with different tokens and see if results correspond to our assumptions:

curl --location --request GET 'http://localhost:8080/api/example' \
--header 'Authorization: Bearer [TOKEN]' 

## Result for both admin and user:
User info

curl --location --request GET 'http://localhost:8080/api/example/admin' \
--header 'Authorization: Bearer [TOKEN]' 

## Result only for admin:
Admin info

curl --location --request GET 'http://localhost:8080/api/public/example' 

## Result for any request:
Public info

7. Export Realm Configuration

In the beginning, I’ve promised to show you how to export the realm configuration. The only thing we need to do is to click the Export tab on the left sidebar and nextly the Export button on the next page:

As a result, a JSON file will be generated.

If we would like to import the configuration, all we need is to head to the Import section:

8. Conclusion

And that would be all for this article. We’ve covered step by step, how to set up the Keycloak server with Spring Boot and Kotlin. Moreover, we’ve had a chance to see how to use it to secure Spring Boot REST endpoints with @PreAuthorize.

As I have written in the beginning, this is the first article in a series. If you would like me to cover some special aspects of the Keycloak/Spring Boot integration, please let me know in the comments, or by the contact form.

Also, to see the fully working project, please refer to this GitHub repository.

The post Keycloak with Spring Boot and Kotlin- Introduction appeared first on Codersee blog- Kotlin on the backend.