Welcome to this lesson on Session-Based Authentication. In the previous lesson, we delved into API authentication using API keys, focusing on how these keys act as a passcode for gaining access to protected endpoints. Here, we take a step further and explore 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 provides a user-friendly way to manage active sessions, track user interactions, and facilitate access to resources. In stateless authentication (such as API keys), every request must contain the necessary credentials, and the server does not retain any information about previous interactions. In contrast, session-based authentication creates and maintains state between requests. This means that once a user logs in, the server assigns a session ID, which the client must include in subsequent requests. The session ID acts as a temporary authentication token, allowing users to stay logged in without re-entering credentials. 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 is a process that 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 Swift 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 Swift 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 Swift-based client:

• 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 Swift client, with the help of URLSession, can manage cookies automatically, including the 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 URLSession in Swift, you can manage cookies and session data seamlessly, enabling effective interaction with RESTful API endpoints while maintaining user state securely.

Cookies are small pieces of data stored on the client side and sent to the server with each request. In session-based authentication, the server typically returns a Set-Cookie header containing a session ID when a user logs in. This header instructs the client to store the session ID as a cookie and send it back in subsequent requests.

Before diving into the authentication steps, it is crucial to understand how to manage sessions using URLSession in Swift. URLSession is a powerful API for making HTTP requests. A pivotal feature of this API is its ability to manage cookies and session data across multiple requests effortlessly.

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

Swift
Copy to clipboard
1import Foundation
2#if canImport(FoundationNetworking)
3import FoundationNetworking
4#endif
5
6// Create a URLSession configuration that handles cookies
7let sessionConfig = URLSessionConfiguration.default
8sessionConfig.httpCookieAcceptPolicy = .always
9sessionConfig.httpShouldSetCookies = true
10
11// Create a URLSession with the configuration
12let session = URLSession(configuration: sessionConfig)
13
14// Base URL for the API
15let baseURL = URL(string: "http://localhost:8000")!
16
17// Create a DispatchGroup to manage asynchronous tasks
18let dispatchGroup = DispatchGroup()

Why Use URLSession?

• Stateful Interactions: URLSession 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 session 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 session object share the same persistent storage, ensuring consistent behavior throughout your API interactions.

A session object is particularly useful when implementing session-based authentication. After creating a session, 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.

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 using Swift:

Swift
Copy to clipboard
1dispatchGroup.enter()
2let authDetails: [String: Any] = [
3    "username": "testuser",
4    "password": "testpass123"
5]
6let jsonData = try! JSONSerialization.data(withJSONObject: authDetails)
7var request = URLRequest(url: baseURL.appendingPathComponent("/auth/signup"))
8request.httpMethod = "POST"
9request.setValue("application/json", forHTTPHeaderField: "Content-Type")
10request.httpBody = jsonData
11
12let task = session.dataTask(with: request) { data, response, error in
13    defer { dispatchGroup.leave() }
14    if let error = error {
15        print("An error occurred: \(error)")
16        return
17    }
18    
19    guard let httpResponse = response as? HTTPURLResponse, (200...299).contains(httpResponse.statusCode) else {
20        print("Server error!")
21        return
22    }
23    
24    if let data = data, let jsonResponse = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
25        print("Signed up successfully!")
26        print(jsonResponse)
27    }
28}
29task.resume()

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; otherwise, error details are provided. Upon successful signup, you would see the following output, confirming that the account has been created:

Plain text
Copy to clipboard
1Signed up successfully!
2{"message": "Signup successful. Please log in to continue."}

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 URLSession to maintain session state. Here's an example of how this is implemented in Swift:

Swift
Copy to clipboard
1dispatchGroup.enter()
2var loginRequest = URLRequest(url: baseURL.appendingPathComponent("/auth/login"))
3loginRequest.httpMethod = "POST"
4loginRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
5loginRequest.httpBody = jsonData
6
7let loginTask = session.dataTask(with: loginRequest) { data, response, error in
8    defer { dispatchGroup.leave() }
9    if let error = error {
10        print("An error occurred: \(error)")
11        return
12    }
13    
14    guard let httpResponse = response as? HTTPURLResponse, (200...299).contains(httpResponse.statusCode) else {
15        print("Server error!")
16        return
17    }
18    
19    if let data = data, let jsonResponse = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
20        print("Logged in successfully!")
21        print(jsonResponse)
22        
23        if let cookies = HTTPCookieStorage.shared.cookies {
24            for cookie in cookies {
25                if cookie.name == "session" {
26                    print("Session ID: \(cookie.value)")
27                }
28            }
29        }
30    }
31}
32loginTask.resume()

In this code snippet, after signing up, you proceed to log in via a POST request to /auth/login, re-using the session object 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; otherwise, error details are displayed. Successful login results in the following output:

Plain text
Copy to clipboard
1Logged in successfully!
2{"message": "Login successful"}
3
4Session ID: eyJhdXRoZW50aWNhdGVkIjp0cnVlLCJ1c2VybmFtZSI6InRlc3R1c2VyMjIyIn0.Z5JFJQ.sF2NX5wOgSF5GVqEmuS2YAawIWM

Once logged in, the session cookie is stored automatically by HTTPCookieStorage.shared. This means that every subsequent request made using the same URLSession instance will include the session ID in the Cookie header. This allows the API to recognize and authenticate the user without requiring additional login steps.

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

Swift
Copy to clipboard
1dispatchGroup.enter()
2var todosRequest = URLRequest(url: baseURL.appendingPathComponent("/todos"))
3todosRequest.httpMethod = "GET"
4
5let todosTask = session.dataTask(with: todosRequest) { data, response, error in
6    defer { dispatchGroup.leave() }
7    if let error = error {
8        print("An error occurred: \(error)")
9        return
10    }
11    
12    guard let httpResponse = response as? HTTPURLResponse, (200...299).contains(httpResponse.statusCode) else {
13        print("Server error!")
14        return
15    }
16    
17    if let data = data, let jsonResponse = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] {
18        print("Accessed todos successfully!")
19        print(jsonResponse)
20    }
21}
22todosTask.resume()

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; otherwise, error responses are provided in case of a failure. Accessing the protected resource successfully will produce the following output:

Plain text
Copy to clipboard
1Accessed todos successfully!
2[{"description": "Milk, eggs, bread, and coffee", "done": false, "id": 1, "title": "Buy groceries"}, {"description": "Check in and catch up", "done": true, "id": 2, "title": "Call mom"}, {"description": "Summarize Q4 performance metrics", "done": false, "id": 3, "title": "Finish project report"}, {"description": "30 minutes of cardio", "done": true, "id": 4, "title": "Workout"}]

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 Swift code:

Swift
Copy to clipboard
1dispatchGroup.enter()
2var logoutRequest = URLRequest(url: baseURL.appendingPathComponent("/auth/logout"))
3logoutRequest.httpMethod = "POST"
4
5let logoutTask = session.dataTask(with: logoutRequest) { data, response, error in
6    defer { dispatchGroup.leave() }
7    if let error = error {
8        print("An error occurred: \(error)")
9        return
10    }
11    
12    guard let httpResponse = response as? HTTPURLResponse, (200...299).contains(httpResponse.statusCode) else {
13        print("Server error!")
14        return
15    }
16    
17    if let data = data, let jsonResponse = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
18        print("Logged out successfully!")
19        print(jsonResponse)
20    }
21}
22logoutTask.resume()
23
24// Wait for all tasks to complete
25dispatchGroup.wait()

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; otherwise, error responses are provided if the request fails. After logging out, you will see the following message as confirmation:

Plain text
Copy to clipboard
1Logged out successfully!
2{"message": "Logout successful"}

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.