Session-based Authentication

Authentication is the security layer implemented to prevent access to personal or sensitive information. It is a way to confirm identity before granting access to information. There are multiple approaches to confirming an identity, but, for the first phase of my experiment, I’ll be focusing on the popular ones used in web applications.

Features

In order to make it more practical, I’ll be building a basic web application with the following features:

• Login: Accept user name and password
• Log out: Invalidate the session ID
• Home: An endpoint that requires authentication to be accessed

How it works

With this method, the credential, typically the username and password, is provided for validation. On a successful validation of the credential, a session ID is generated, stored and added to the cookie header of the response. The client saves this session ID (in Cookies storage) and passes it along for every request. This is also known as a cookie-based authentication because of the use of cookies.

Session-based authentication is a stateful authentication method because the means of authorization (session ID) is persisted in a storage (DB and/or Cache). The session ID is persisted because the server uses it to validate the request from the client. Session IDs are invalidated and deleted either when they expire or when a logout request is initiated.

Implementation

Go is the language of choice for implementation harnessing the standard libraries with little to no third-party library. As much as possible, I'd also like to use a TDD approach to help with validating my thought before implementing the feature.

The project set up is straight forward:

mkdir session
cd session
go mod init authentication/session

Login

The /login endpoint is a POST request accepting a username and password. Generally, the authentication requirements are:

• Return an unauthorized access error (HTTP 401) when either the username or password isn’t provided
• Return a user not found error (HTTP 404) when the username doesn’t exist
• Return an unauthorized access error (HTTP 401) when the username and password don’t match
• Return a session ID (with a 200 OK code) on a successful validation

With a TDD approach, a test file (server_test.go) is created to capture these requirements:

1
package main
2

3
import (
4
  "bytes"
5
  "fmt"
6
  "net/http"
7
  "net/http/httptest"
8
  "testing"
9
)
10

11
func TestLogin(t *testing.T) {
12

13
   t.Run("return error for missing username", func(t *testing.T) {
14
    credentials := []byte(`{"username": "", "password": "admin"}`)
15
    request, _ := http.NewRequest(http.MethodPost, "/login", bytes.NewBuffer(credentials))
16
    response := httptest.NewRecorder()
17

18
    Login(response, request)
19

20
    got := response.Body.String()
52 collapsed lines
21
    expected := fmt.Sprint(ErrRequiredUsername, "\n")
22

23
    if got != expected {
24
      t.Errorf("expected %q, got %q", expected, got)
25
    }
26
  })
27

28
  t.Run("return error for non-existent user", func(t *testing.T) {
29
    credentials := []byte(`{"username": "admin1", "password": "admin"}`)
30
    request, _ := http.NewRequest(http.MethodPost, "/login", bytes.NewBuffer(credentials))
31
    response := httptest.NewRecorder()
32

33
    Login(response, request)
34

35
    got := response.Body.String()
36
    expected := fmt.Sprint(ErrUserNotFound, "\n")
37

38
    if got != expected {
39
      t.Errorf("expected %q, got %q", expected, got)
40
    }
41
  })
42

43
  t.Run("return error for for credential mismatch", func(t *testing.T) {
44
    credentials := []byte(`{"username": "admin", "password": "admin1"}`)
45
    request, _ := http.NewRequest(http.MethodPost, "/login", bytes.NewBuffer(credentials))
46
    response := httptest.NewRecorder()
47

48
    Login(response, request)
49

50
    got := response.Body.String()
51
    expected := fmt.Sprint(ErrCredentialMismatch, "\n")
52

53
    if got != expected {
54
      t.Errorf("expected %q, got %q", expected, got)
55
    }
56
  })
57

58
  t.Run("return a session ID", func(t *testing.T) {
59
    credentials := []byte(`{"username": "admin", "password": "admin"}`)
60
    request, _ := http.NewRequest(http.MethodPost, "/login", bytes.NewBuffer(credentials))
61
    response := httptest.NewRecorder()
62

63
    Login(response, request)
64

65
    cookie := response.Result().Cookies()
66
    sessionId := cookie[0].Value
67

68
    if len(sessionId) <= 0 {
69
      t.Errorf("expected a session id, got %q", sessionId)
70
    }
71
  })
72
}

Ideally, the test for each requirement will be written, then the most minimal amount of code required to make the test pass is written. Finally, a refactor is done to tidy things up. However, that’s outside the scope of this topic.

To implement the requirements, another file, server.go, is created:

1
package main
2

3
import (
4
  "encoding/json"
5
  "fmt"
6
  "net/http"
7
  "sync"
8
  "time"
9

10
  "github.com/google/uuid"
11
)
12

13
type Credential struct {
14
  Username string `json:"username"`
15
  Password string `json:"password"`
16
}
17

18
const (
19
  ErrRequiredUsername   = "username is required"
20
  ErrRequiredPassword   = "password is required"
63 collapsed lines
21
  ErrUserNotFound       = "user not found"
22
  ErrCredentialMismatch = "username and password don't match"
23
  ErrCookieNotFound     = "cookie not found"
24
  ErrMissingSessionID   = "session id is missing"
25
  ErrInvalidSessionID   = "Invalid session ID. Try logging in"
26
  ErrNoSession          = "Already logged out"
27
)
28

29
var users = map[string]string{
30
  "admin": "admin",
31
  "user1": "user1",
32
}
33

34
const MY_SESSION_ID = "MY_SESSION_ID"
35

36
var Sessions = make(map[string]string)
37
var sessionMutex sync.Mutex
38

39
func Login(w http.ResponseWriter, r *http.Request) {
40
  var credential Credential
41
  err := json.NewDecoder(r.Body).Decode(&credential)
42

43
  if err != nil {
44
    http.Error(w, err.Error(), http.StatusBadRequest)
45
  }
46

47
  if credential.Username == "" {
48
    http.Error(w, ErrRequiredUsername, http.StatusBadRequest)
49
    return
50
  }
51

52
  if credential.Password == "" {
53
    http.Error(w, ErrRequiredPassword, http.StatusBadRequest)
54
    return
55
  }
56

57
  if _, ok := users[credential.Username]; !ok {
58
    http.Error(w, ErrUserNotFound, http.StatusNotFound)
59
    return
60
  }
61

62
  if users[credential.Username] != credential.Password {
63
    http.Error(w, ErrCredentialMismatch, http.StatusUnauthorized)
64
    return
65
  }
66

67
  sessionId := uuid.NewString()
68

69
  sessionMutex.Lock()
70
  Sessions[sessionId] = credential.Username
71
  sessionMutex.Unlock()
72

73
  cookie := http.Cookie{
74
    Name:    MY_SESSION_ID,
75
    Value:   sessionId,
76
    Expires: time.Now().Add(time.Hour),
77
    MaxAge:  3600,
78
    Secure:  true,
79
  }
80

81
  http.SetCookie(w, &cookie)
82
  w.WriteHeader(http.StatusOK)
83
}

A lot seems to be going on for the login feature but it’s straightforward:

• Packages: Keeping to the implementation constraint, we are using the standard libraries except for the UUID library (github.com/google/uuid) which is used for generating unique session IDs.
• Credential struct: A custom type was created for the login details. The login details will be sent via JSON, so we need to export the fields to allow encoding/decoding in JSON.
• Map of users: In keeping the implementation simple, a map was used as store for existing users. Ideally, this should be read from storage.
• Map of sessions: Like users, a map is also used to store the created sessions.
• Mutex: This was added to guard the map of sessions against a race condition when writing to it.
• Constants and variables: These consists of all identifiers that are used within the package.

With the setup in place, the login function starts by decoding the JSON request into the Credential type. By using a pointer, the decoder can write the decoded result into the memory address of the credential variable. The major part of the function are checks from the requirements. Once all negative path have been covered, the session ID is created, using the uuid package. The session ID is then mapped to the username and used to create the cookie. The cookie is set on the response header and a 200 Ok response is returned.

Home

With the login implemented, I can now add a path that requires authentication to access. Again, the requirements are:

• Return an unauthorized access (401) if a cookie is missing
• Return an unauthorized access (401) for an invalid cookie
• Return a success response if session exists and is valid

The server_test.go file can be updated to capture these requirements and the feature can be implemented to make the test pass:

Logout

A session ID can becomes invalid when it either expires or when the user initiates a logout request. The client typically takes care of the former. Handling the latter involves removing the session ID from the store, in this case, the map:

Router

Each created function cannot be used by a client yet because they haven’t been tied to a route. The implementation of the router will be done in a new file, main.go, inside the main() function:

1
package main
2

3
import (
4
  "fmt"
5
  "log"
6
  "net/http"
7
)
8

9
func main() {
10
  mux := http.NewServeMux()
11
  mux.HandleFunc("POST /login", Login)
12
  mux.HandleFunc("GET /home", Home)
13
  mux.HandleFunc("DELETE /logout", Logout)
14

15
  fmt.Println("Server listening on port 9009")
16
  log.Fatal(http.ListenAndServe(":9009", mux))
17
}

A request router (multiplexer to be precise) is created with the NewServeMux() function in the http package. The routes are defined but specifying a string with an HTTP method, a space then the path and the handler for the route. The server can be configured with a port and the router.

Concerns

Session-based authentication benefits from an ease of implementation, however, because of the reliance on the client, it poses some concerns:

• Cross Site Request Forgery (CSRF): Cookies are on the client side which creates the room for bad actors to retrieve them through fake requests
• Privacy: With cookies usage for state managment, it can be easily used to track the activities of a user.
• Implementation: Some clients have limitations on the cookies such as: maximum number of bytes, maximum number of cookies per domain and the total number of cookies.

Lessons

Here are some things I can do better:

1. Write and implement to allow for a more natural flow
2. There are still rough edges with TDD, particularly around mocking and stubbing
3. For the logout implementation, I didn’t consider how to invalidate expired session IDs

References

• Cookie-based HTTP Authentication (draft-broyer-http-cookie-auth-00)
• RFC 6265: HTTP State Management Mechanism
• Using HTTP Cookie - MDN