Welcome to this lesson on Session-Based Authentication. In the previous lesson, we explored API authentication using API keys, focusing on how these keys act as a passcode for accessing protected endpoints. Here, we delve into session-based authentication, a method where the server maintains user session information, providing a stateful experience. Unlike API keys, which are stateless, session-based authentication offers a user-friendly way to manage active sessions, track user interactions, and facilitate access to resources. By the end of this lesson, you will be capable of signing up, logging in, accessing protected resources, and logging out using session-based authentication.

Session-based authentication allows users to stay logged into a system as they interact with different endpoints in an application. Whether you are using a web browser or a client like a Kotlin application to interact with a RESTful API, session-based authentication involves maintaining user session information on the server, creating a stateful experience.

When you log in to a RESTful API using your Kotlin client, the server starts a "session" for you. This session is like a temporary ID card that validates your identity during your interactions with the API. A critical part of this process involves a "cookie", which is a small piece of data sent from the server and stored by your client.

In the context of a Kotlin-based client using OkHttp:

• Session Creation: After logging in by sending a POST request with your username and password, the server creates a unique session ID, often returned in a cookie.
• Ongoing Requests: Your Kotlin client, with the help of OkHttp, can include this session ID in subsequent requests to the API. This allows the server to recognize the session without needing to re-enter your credentials.
• Session Termination: When your client logs out by sending a logout request, the server invalidates the session, stopping further requests with the old session ID from succeeding, safeguarding your session integrity.

By using OkHttp in Kotlin, you can manage cookies and session data seamlessly, enabling effective interaction with RESTful API endpoints while maintaining user state securely.

Before diving into the authentication steps, it is crucial to understand how to manage sessions using OkHttp in Kotlin. OkHttp is renowned for its simplicity and ease of use when making HTTP requests. A pivotal feature of this library is its ability to manage cookies, which helps persist session data across multiple requests effortlessly.

Here’s how you can establish a session using OkHttp:

Kotlin
Copy to clipboard
1import okhttp3.OkHttpClient
2import okhttp3.Request
3
4// Creating an OkHttpClient with cookie management
5val client = OkHttpClient.Builder()
6    .cookieJar(JavaNetCookieJar(CookieManager()))
7    .build()

Why Use OkHttp with Cookie Management?

• Stateful Interactions: OkHttp maintains session information such as cookies between requests. Once you log in to an API, it stores the session ID and includes it automatically in subsequent requests.
• Efficiency: Using a client with cookie management can reduce the overhead of establishing new connections for each request, making your interactions with the API more efficient.
• Consistency: All requests made from a client with cookie management share the same persistent storage, ensuring consistent behavior throughout your API interactions.

A client with cookie management is particularly useful when implementing session-based authentication. After creating a client, you can perform all authentication steps – signing up, logging in, accessing resources, and logging out – all within this persistent context. The continuity offered by sessions assures that user state and authorization are maintained seamlessly across multiple API requests, providing a cohesive user experience. Here is a generic example of how you can use it for requests:

Kotlin
Copy to clipboard
1// Similar to requests.get(), but maintains session data
2val request = Request.Builder()
3    .url("http://example.com")
4    .build()
5
6val response = client.newCall(request).execute()

Having understood the basics of session management, let's proceed to the practical implementation of session-based authentication using OkHttp.

In the first step of session-based authentication, you need to create a user account. This action is performed by sending a POST request to the API's signup endpoint. Below is the code example showing how this can be accomplished:

Kotlin
Copy to clipboard
1import okhttp3.MediaType.Companion.toMediaType
2import okhttp3.RequestBody.Companion.toRequestBody
3import okhttp3.Request
4import java.io.IOException
5
6// Base URL for the API
7val baseUrl = "http://localhost:8000"
8
9// Signup details with a username and password
10val authDetails = """
11    {
12        "username": "testuser",
13        "password": "testpass123"
14    }
15""".trimIndent()
16
17// Attempt to sign up to the API
18val requestBody = authDetails.toRequestBody("application/json".toMediaType())
19val request = Request.Builder()
20    .url("$baseUrl/auth/signup")
21    .post(requestBody)
22    .build()
23
24client.newCall(request).execute().use { response ->
25    if (!response.isSuccessful) throw IOException("Unexpected code $response")
26
27    println("Signed up successfully!")
28    println(response.body?.string())
29}

In this example, a user account is created by submitting a POST request to the /auth/signup endpoint, along with a username and password. If the request is successful, a confirmation message and the server’s response are displayed. Since the API doesn't establish or return a session during signup, you have the option to use a simple OkHttp client. However, using a client with cookie management from the outset ensures code consistency and prepares you for future steps where session persistence becomes crucial.

After signing up, the next step is to log in and initiate a session. This involves posting login credentials to an authentication endpoint and leveraging the OkHttp client to maintain session state. Here's an example of how this is implemented:

Kotlin
Copy to clipboard
1// Attempt to log in to the API
2val loginRequest = Request.Builder()
3    .url("$baseUrl/auth/login")
4    .post(requestBody)
5    .build()
6
7client.newCall(loginRequest).execute().use { response ->
8    if (!response.isSuccessful) throw IOException("Unexpected code $response")
9
10    println("Logged in successfully!")
11    println(response.body?.string())
12
13    // Retrieve and print the session ID
14    val sessionId = client.cookieJar.loadForRequest(HttpUrl.get("$baseUrl/auth/login"))
15        .find { it.name == "session" }?.value
16    println("\nSession ID: $sessionId")
17}

In this code snippet, after signing up, you proceed to log in via a POST request to /auth/login, re-using the client to keep the session active. Successful login messages are shown if the credentials are accepted and the session is active, and the session ID is printed.

With an active session established, you can simply use your client to make requests to protected endpoints of the API. Here's an example of how to achieve this:

Kotlin
Copy to clipboard
1// Attempt to access a protected endpoint
2val todosRequest = Request.Builder()
3    .url("$baseUrl/todos")
4    .build()
5
6client.newCall(todosRequest).execute().use { response ->
7    if (!response.isSuccessful) throw IOException("Unexpected code $response")
8
9    println("Accessed todos successfully!")
10    println(response.body?.string())
11}

Here, a GET request is used to access the /todos endpoint, assuming it's protected and requires an active session. When access is granted, it indicates that your session is valid and active.

To end the session and log out by targeting the /auth/logout endpoint, ensuring that the session is cleanly terminated, you can use the following:

Kotlin
Copy to clipboard
1// Attempt to log out from the API
2val logoutRequest = Request.Builder()
3    .url("$baseUrl/auth/logout")
4    .post("".toRequestBody()) // Empty body for logout
5    .build()
6
7client.newCall(logoutRequest).execute().use { response ->
8    if (!response.isSuccessful) throw IOException("Unexpected code $response")
9
10    println("Logged out successfully!")
11    println(response.body?.string())
12}

To log out, a POST request is made to /auth/logout, notifying the server to terminate the session. A successful logout message is displayed upon completion.

After ending the session and logging out, any attempt to access protected endpoints without logging back in will fail. This is because the session is no longer active, and the server won't recognize your session ID. Here’s the output you can expect when trying to access a protected endpoint after logging out:

Plain text
Copy to clipboard
1An HTTP error occurred: 401 Client Error: UNAUTHORIZED for url: http://localhost:8000/todos
2Error: Valid session required

In this lesson, we journeyed through the process of session-based authentication, covering signing up, logging in, accessing secure resources, and logging out. By maintaining an active session, you have learned to manage user states effectively and securely — an important aspect of API interaction. As you transition to the practice exercises, these methods will form the backbone of your hands-on experience in securing endpoints. The upcoming practices are designed to reinforce your understanding and mastery of session-based authentication, preparing you for subsequent lessons that explore even more advanced methods like JSON Web Tokens (JWT). Dive into these exercises with confidence, applying what you've learned in a practical, results-oriented way.