Welcome to this lesson on refreshing JWTs and signing out from APIs. Building on our previous discussion about JWT Authentication, where we focused on obtaining and utilizing JSON Web Tokens (JWTs) for stateless API authentication, we now explore more advanced aspects. In particular, we'll focus on refresh tokens, a crucial component in maintaining session continuity and providing seamless user experiences. Refresh tokens allow clients to obtain new access tokens without requiring user reauthentication, thereby ensuring uninterrupted access to protected resources. Our objectives today include learning how to refresh JWTs and securely sign out, all to ensure a robust and secure authentication workflow. Let's get started on mastering these important concepts.

As a reminder, JWTs are integral to stateless authentication, often chosen for their scalability and flexibility. Access tokens, a key part of JWT-based systems, are short-lived to minimize the risk of unauthorized access if they are ever leaked. Before diving into refreshing tokens, let's revisit the process of logging in to obtain both access and refresh tokens.

In this example, we'll send a POST login request and extract tokens from the response. Here’s how it unfolds:

Kotlin
Copy to clipboard
1import okhttp3.*
2import kotlinx.serialization.*
3import kotlinx.serialization.json.*
4import java.io.IOException
5
6val client = OkHttpClient()
7val baseUrl = "http://localhost:8000"
8
9@Serializable
10data class AuthDetails(val username: String, val password: String)
11
12@Serializable
13data class TokenResponse(val access_token: String, val refresh_token: String)
14
15val authDetails = AuthDetails(username = "testuser", password = "testpass123")
16val jsonAuthDetails = Json.encodeToString(authDetails)
17
18val request = Request.Builder()
19    .url("$baseUrl/auth/login")
20    .post(jsonAuthDetails.toRequestBody("application/json".toMediaType()))
21    .build()
22
23client.newCall(request).enqueue(object : Callback {
24    override fun onFailure(call: Call, e: IOException) {
25        println("An error occurred: ${e.message}")
26    }
27
28    override fun onResponse(call: Call, response: Response) {
29        if (!response.isSuccessful) {
30            println("An HTTP error occurred: ${response.code}")
31            println("Error: ${response.body?.string()}")
32        } else {
33            val responseBody = response.body?.string()
34            val tokenResponse = Json.decodeFromString<TokenResponse>(responseBody!!)
35            val accessToken = tokenResponse.access_token
36            val refreshToken = tokenResponse.refresh_token
37            println("Access Token: $accessToken")
38            println("Refresh Token: $refreshToken")
39        }
40    }
41})

In this snippet, we've sent a login request and successfully extracted the access and refresh tokens. These tokens are vital for interacting with protected endpoints and setting the stage for the refreshing process.

To maintain continuous access without forcing users to sign in repeatedly, we employ refresh tokens. These longer-lived tokens enable applications to request a fresh access token once the previous one expires.

With our previously obtained refresh token, we can request a new access token through the refresh process using the /auth/refresh route. It is a common practice to send the refresh token in the body of the request for security reasons, minimizing exposure in URLs or headers:

Kotlin
Copy to clipboard
1val refreshRequest = Request.Builder()
2    .url("$baseUrl/auth/refresh")
3    .post(JSONObject().put("refresh_token", refreshToken).toString().toRequestBody("application/json".toMediaType()))
4    .build()
5
6client.newCall(refreshRequest).enqueue(object : Callback {
7    override fun onFailure(call: Call, e: IOException) {
8        println("An error occurred: ${e.message}")
9    }
10
11    override fun onResponse(call: Call, response: Response) {
12        if (!response.isSuccessful) {
13            println("An HTTP error occurred: ${response.code}")
14            println("Error: ${response.body?.string()}")
15        } else {
16            val responseBody = response.body?.string()
17            val jsonResponse = JSONObject(responseBody)
18            val newAccessToken = jsonResponse.getString("access_token")
19            val newRefreshToken = jsonResponse.getString("refresh_token")
20            println("Tokens refreshed successfully!")
21            println("Access Token: $newAccessToken")
22            println("Refresh Token: $newRefreshToken")
23        }
24    }
25})

Upon executing the refresh request, we receive a new access token, and in our case, the refresh token is also updated by the server for enhanced security. Upon successful token refresh, you should see an output like the following, confirming that the tokens have been updated successfully:

Plain text
Copy to clipboard
1Tokens refreshed successfully!
2Access Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0dXNlciIsImlhdCI6MTczNzczMTYwMCwiZXhwIjoxNzM3NzMyNTAwfQ.Jw6otd6c717EcuLQtUiO4DxNHg_cBTtKvtYyE-9BK_M
3Refresh Token: 3f283c147c54889916250fa90ed208406f8750b90fede0682f7676c9f2432acc

With the new access token obtained, we continue to interact securely with protected API endpoints. This process repeats what we discussed earlier — attaching the access token in the Authorization header of requests. This time, we're utilizing the freshly acquired token to ensure the request is authorized.

Incorporating the updated token, here's how you can access a "todos" endpoint:

Kotlin
Copy to clipboard
1val headers = Headers.Builder()
2    .add("Authorization", "Bearer $accessToken")
3    .build()
4
5val todosRequest = Request.Builder()
6    .url("$baseUrl/todos")
7    .headers(headers)
8    .build()
9
10client.newCall(todosRequest).enqueue(object : Callback {
11    override fun onFailure(call: Call, e: IOException) {
12        println("An error occurred: ${e.message}")
13    }
14
15    override fun onResponse(call: Call, response: Response) {
16        if (!response.isSuccessful) {
17            println("An HTTP error occurred: ${response.code}")
18            println("Error: ${response.body?.string()}")
19        } else {
20            println("Accessed todos successfully!")
21            println(response.body?.string())
22        }
23    }
24})

The inclusion of the access token in the authorization header ensures that your requests to resources like /todos are properly authenticated, facilitating secure data transactions. This secure request highlights how refreshed access tokens uphold the integrity of session-based activities while maintaining a streamlined user experience.

Beyond refreshing tokens, signing out from an application is equally crucial as it invalidates current tokens, preventing unauthorized access if they fall into the wrong hands. Signing out serves as an integral part of maintaining security and ending a user session.

By issuing a POST request to the logout endpoint, we revoke access tokens on the server, often using the refresh token to identify the session:

Kotlin
Copy to clipboard
1val logoutRequest = Request.Builder()
2    .url("$baseUrl/auth/logout")
3    .post(JSONObject().put("refresh_token", refreshToken).toString().toRequestBody("application/json".toMediaType()))
4    .headers(headers)
5    .build()
6
7client.newCall(logoutRequest).enqueue(object : Callback {
8    override fun onFailure(call: Call, e: IOException) {
9        println("An error occurred: ${e.message}")
10    }
11
12    override fun onResponse(call: Call, response: Response) {
13        if (!response.isSuccessful) {
14            println("An HTTP error occurred: ${response.code}")
15            println("Error: ${response.body?.string()}")
16        } else {
17            println("Logged out successfully!")
18            println(response.body?.string())
19        }
20    }
21})

Upon successful logout, the application invalidates the session both client-side and server-side. This prevents any further use of revoked tokens, ensuring security. Recognizing what happens server-side during logout supports a comprehensive grasp of session management and security protocols, reinforcing the importance of this step in secure authentication practices.

After executing a logout, the access token is invalidated. Consequently, any attempt to access protected endpoints using the invalid token will fail. Let's illustrate this by attempting to access the "todos" endpoint using the access token post-logout:

Kotlin
Copy to clipboard
1client.newCall(todosRequest).enqueue(object : Callback {
2    override fun onFailure(call: Call, e: IOException) {
3        println("An error occurred: ${e.message}")
4    }
5
6    override fun onResponse(call: Call, response: Response) {
7        if (!response.isSuccessful) {
8            println("An HTTP error occurred: ${response.code}")
9            println("Error: ${response.body?.string()}")
10        }
11    }
12})

As expected, the server will reject the request since the token is no longer valid. This secures the application by ensuring that invalid tokens cannot be used to access resources. The output from this attempt will be as follows:

Plain text
Copy to clipboard
1An HTTP error occurred: 401 Client Error: UNAUTHORIZED for url: http://localhost:8000/todos
2Error: You have been logged out. Please log in again.

This error emphasizes the necessity of re-authentication for continued access, thereby safeguarding sensitive data and maintaining session integrity.

In a similar manner, the refresh token becomes invalid after logout, effectively blocking any request to refresh tokens. Here's how the system responds when we attempt to refresh tokens using the invalid refresh token:

Kotlin
Copy to clipboard
1client.newCall(refreshRequest).enqueue(object : Callback {
2    override fun onFailure(call: Call, e: IOException) {
3        println("An error occurred: ${e.message}")
4    }
5
6    override fun onResponse(call: Call, response: Response) {
7        if (!response.isSuccessful) {
8            println("An HTTP error occurred: ${response.code}")
9            println("Error: ${response.body?.string()}")
10        }
11    }
12})

The server detects the invalid token and denies the refresh request, providing the following output:

Plain text
Copy to clipboard
1An HTTP error occurred: 401 Client Error: UNAUTHORIZED for url: http://localhost:8000/auth/refresh
2Error: Invalid refresh token

This output confirms that once a user logs out, subsequent token refresh attempts fail, reinforcing the logging out process's role in invalidating session credentials. By doing so, it ensures that no unauthorized sessions can regain access inadvertently, cementing application security.

In this lesson, you learned about refreshing JWT tokens and effectively signing out to secure API interactions. We explored the vital role of refresh tokens in retaining session continuity and reducing frequent reauthentication burdens. From refreshing tokens and accessing secured endpoints to signing out, you have gained robust skills in managing API authentication workflows confidently.

With these lessons complete, I commend your progress through the course! The techniques covered empower you to handle API security challenges with proficiency. As you proceed to practice exercises, reinforce these concepts by experimenting with different endpoints and error scenarios. Remember, the skills honed here will serve your applications well, ensuring scalable and secure interactions within the API landscape.