HTTP Basic Authentication and Session Management With Golang's OAPI-Codegen

Ryan Michael

11 Mar 2025 — 10 min read

While working on my REST API game Webdrones I needed a way to authenticate users. Although OAPI-Codegen has examples on how to do this with JSON Web Tokens, I was led by additional research including this influential blog post to use HTTP Basic Authentication and cookie based sessions as my authentication method. Since I wasn't able to find any tutorials or examples of how to do this I ended up writing my own solution, and I want to share it for anyone else that may come across a similar use case. This tutorial has a lot of code samples, all pulled from my Webdrones codebase. To turn these snippets into a running project you will need experience with the following:

Golang
oapi-codgen
running and administering a Postgres database
Golang's http standard library
The Jet SQL generation library
Gorilla's session library

If this tutorial gains enough interest I will update it to contain a fully running project with less dependencies.

I am using oapi-codegen to generate server code using Golang's http library. I have a /newUser endpoint for users to create a new account with a username and password. Users can send a POST to this endpoint with a basic authentication HTTP header which will add their username and hashed password to a database. On success the endpoint returns a response with an authentication cookie in its header and a string indicating the user creation in the body. Users can hit the /login endpoint with their username and password in the Basic Authentication field of their HTTP headers to retrieve this cookie. runBusinessLogic is a stand in for any endpoints a user should only be allowed to access once authenticated.

Let's look at the API spec we will be implementing.

openapi: 3.0.0
info:
  version: 1.0.0
  title: Web Drones
  description: Api to play Web Drones!
paths:
  /login:
    post:
    description: Log in with username and password.
    security:
      - basicAuth: []
    responses:
    '200':
      description: Returns login cookie on success
      content:
        text/plain:
          schema:
            type: string
    '401':
      description: Returns when login fails from bad username/password combo
      content:
        text/plain:
          schema:
            type: string
  /newUser:
    post:
      description: Creates new user with associated password
      security:
        - basicAuth: []
      responses:
        '200':
          description: Creates new user and logs them in on success 
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: Returns when login fails from bad username/password combo
          content:
            text/plain:
              schema:
                type: string
  /runBusinessLogic:
    post:
      description: Run business logic as an authenticated user
      responses:
        '200':
          description: returns starting bots and mines
          content:
            text/plain:
              schema:
                type: string
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    cookieAuth:
      type: apiKey
      in: cookie
      name: SESSIONID

security:
  - cookieAuth: []

We will use the following configuration to generate our code from the above spec:

package: api
output: api.gen.go
generate:
  models: true
  std-http-server: true
  strict-server: true

After generating our web server boilerplate with the oapi-codegen utility we can implement the generated interface:

type Server struct{}

// (POST /newUser)
func (Server) PostNewUser(
  ctx context.Context, 
  request api.PostNewUserRequestObject) (api.PostNewUserResponseObject, error) {
  return api.PostNewUser200TextResponse("New User Created"), nil
}
// (POST /login)
func (Server) PostLogin(
  ctx context.Context, 
  request api.PostLoginRequestObject) (api.PostLoginResponseObject, error) {
  return api.PostLogin200TextResponse("Login Successful"), nil
}
  // (POST /runBusinessLogic)
func (Server) PostRunBusinessLogic(
  ctx context.Context, 
  request PostRunBusinessLogicRequestObject) (PostRunBusinessLogicResponseObject, error) {
  return api.PostRunBusinessLogic200TextResponse("TODO: Print authenticated username"), nil
}

We will use middleware to completely separate our auth logic out from our business logic. oapi-codegen generates the following function that we can use to create our server with middleware:

func NewStrictHandlerWithOptions(ssi StrictServerInterface, middlewares []StrictMiddlewareFunc, 
                 options StrictHTTPServerOptions) ServerInterface {
  return &strictHandler{ssi: ssi, middlewares: middlewares, options: options}
}

We will be spending some time looking at the middlewares and options parameters. Let's look at the type for middlewares, which is []StrictMiddleWareFunc. In our generated boilerplate, oapi-codegen has created the following alias:

type StrictMiddlewareFunc = strictnethttp.StrictHTTPMiddlewareFunc

We can check oapi-codegen's source code to find the full declaration:

type StrictHTTPHandlerFunc func(ctx context.Context, w http.ResponseWriter, 
                r *http.Request, request interface{}) (response interface{}, err error)
type StrictHTTPMiddlewareFunc func(f StrictHTTPHandlerFunc, operationID string) StrictHTTPHandlerFunc

In other words, we can write functions that directly access Golang's http.ResponseWriter and http.Request structs and oapi-codegen's boilerplate will run those functions as middleware before calling its type safe interface methods where our business logic resides. If you want, you can examine your generated code to fully verify how this works.

Now that we have a general idea of how writing middleware works, let's sketch out a template for it:

func AuthMiddleWare(f nethttp.StrictHTTPHandlerFunc, operationID string) nethttp.StrictHTTPHandlerFunc {
  return func(ctx context.Context, w http.ResponseWriter, 
              r *http.Request, request interface{}) (response interface{}, err error) {
    if operationID == "PostLogin" {
      // Check if user/pw combo exists and make new session if it does 
    } else if operationID == "PostNewUser" {
      // Add a new user/pw combo to DB and create a new session
    } else {
      // Run business logic endpoints ONLY if there is a valid session
    }
  }
}

oapi-codegen automatically sets operationID to the method name corresponding to the route an HTTP request is trying to access. This value can be overridden but that is outside this tutorial's scope.

First we are going to implement the /newUser endpoint (with operationID PostNewUser). Let's create a database table for usernames and passwords:

CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    created_at TIMESTAMP WITH TIME ZONE,
    updated_at TIMESTAMP WITH TIME ZONE,
    username TEXT NOT NULL UNIQUE,
    password TEXT NOT NULL
);

Next we'll write a function to add a user and a bcrypt hashed password to a Postgres database. If the name already exists our Postgres client will return an error.

func GetDBString() string {
  hostname, present := os.LookupEnv("DB_HOSTNAME")
  if !present || hostname == "" {
    hostname = "localhost"
  }
  dbString := fmt.Sprintf("postgres://user:password@%s:5432/webdrones?sslmode=disable", hostname)
  return dbString
}

func CreateNewUser(username string, password string) error {
  hashedPassword, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
  if err != nil {
    return &AuthError{OriginalError: err}
  }
  // add new user to db
  stmt := Users.INSERT(
    Users.CreatedAt, Users.UpdatedAt, Users.Username, Users.Password,
  ).VALUES(
    NOW(), NOW(), String(username), String(string(hashedPassword)),
  )
  _, err = stmt.Exec(DB)
  if err != nil {
    if err.(*pgconn.PgError).Code == "23505" {
      return &AuthError{OriginalError: err, NewError: errors.New("username already exists")}
    } else {
      return &AuthError{OriginalError: err}
    }
  }
  return nil
}

func OpenDB() *sql.DB {
  db, err := sql.Open(
    "pgx", GetDBString(),
  )
  if err != nil {
    log.Fatal(err)
  }

  // make sure the database is up and running
  err = db.Ping()
  if err != nil {
    log.Fatal(err)
  }
  return db
}

var DB = OpenDB()

I'm using Jet to build my SQL queries and set my models, which are not included for brevity. See the Jet documentation for details.

Be mindful of the security risks with a database connection string that has the username and password in plaintext. Distributed secret management is outside of the scope of this tutorial.

We can implement our middleware logic now. We will create a session using gorilla's session management, parse the username and password out of the request's HTTP header, and pass those into our CreateNewUser function. If the new user is successfully created, we will add the username to the session variable (we will read this value from the session store later).

var sessionStore = sessions.NewCookieStore([]byte("Super secure plz no hax"))

func AuthMiddleWare(f nethttp.StrictHTTPHandlerFunc, operationID string) nethttp.StrictHTTPHandlerFunc {
  return func(ctx context.Context, w http.ResponseWriter, 
              r *http.Request, request interface{}) (response interface{}, err error) {
    session, err := sessionStore.Get(r, "SESSION")
    if err != nil {
      return "Authentication Error", &utils.AuthError{OriginalError: err}
    }
    if operationID == "PostLogin" {
      // Check if user/pw combo exists and make new session if it does 
    } else if operationID == "PostNewUser" {
      // Add a new user/pw combo to DB and create a new session
      username, password, ok := r.BasicAuth()
      if !ok {
        return "Authentication Error", 
                &utils.AuthError{NewError: errors.New("invalid basic auth header")}
      }
      err = CreateNewUser(username, password)
      if err != nil {
        return "Authentication Error", err
      }
      w.Header().Add("Content-Type", "text/plain")
      session.Values["username"] = username
      // Write cookie into session
      err = session.Save(r, w)
      if err != nil {
        return "Authentication Error", &utils.AuthError{OriginalError: err}
      }

    } else {
      // Run business logic endpoints ONLY if there is a valid session
    }
  }
  return f(ctx, w, r, request)
}

sessions.NewCookieStore sets up a session database that is encrypted with the byte array passed into it as a key. Again, "Super secure pls no hax" is not a secure encryption key, especially when it's hardcoded. From there we add the username to the session database, which is a basic map, and call gorilla's session store Save method. Save sets up the cookies and other request/response information we use to manage sessions.

As long as we don't return an error we want to pass control from our middleware to the rest of the program. We do this by calling f as the last statement in our function with our modified context, and returning its value

Now we can set up our /login endpoint. We will parse the authentication info out of our HTTP header like before, then get the hashed password from the database based on the username. We return an error if the user doesn't exist. If it exists, we check to see if the user submitted hash matches the hash in the database. We again add the user's username into the session store and Save it.

var sessionStore = sessions.NewCookieStore([]byte("Super secure plz no hax"))

func AuthMiddleWare(f nethttp.StrictHTTPHandlerFunc, operationID string) nethttp.StrictHTTPHandlerFunc {
  return func(ctx context.Context, w http.ResponseWriter, 
               r *http.Request, request interface{}) (response interface{}, err error) {
    session, err := sessionStore.Get(r, "SESSION")
    if err != nil {
      return "Authentication Error", &utils.AuthError{OriginalError: err}
    }
    if operationID == "PostLogin" {
      // Check if user/pw combo exists and make new session if it does 
            // check against db
      username, password, ok := r.BasicAuth()
      if !ok {
        return "Authentication Error", 
                &utils.AuthError{NewError: errors.New("invalid basic auth header")}
      }
      stmt := SELECT(Users.Password).FROM(Users).WHERE(Users.Username.EQ(String(username)))
      var hashedPassword model.Users
      err := stmt.Query(utils.DB, &hashedPassword)
      if err != nil {
        return "Authentication Error", &utils.AuthError{OriginalError: err}
      }
      err = bcrypt.CompareHashAndPassword([]byte(hashedPassword.Password), []byte(password))
      if err != nil {
        if errors.Is(err, bcrypt.ErrMismatchedHashAndPassword) {
          return "Authentication Error", 
                  &utils.AuthError{OriginalError: errors.New("username and password mismatch")}
        } else {
          return "Authentication Error", 
                  &utils.AuthError{OriginalError: err}
        }
      }
      w.Header().Add("Content-Type", "text/plain")
      session.Values["username"] = username
      // Write cookie into session
      err = session.Save(r, w)
      if err != nil {
        return "Authentication Error", &utils.AuthError{OriginalError: err}
      }
    } else if operationID == "PostNewUser" {
      // Add a new user/pw combo to DB and create a new session
      username, password, ok := r.BasicAuth()
      if !ok {
        return "Authentication Error", 
                &utils.AuthError{NewError: errors.New("invalid basic auth header")}
      }
      err = CreateNewUser(username, password)
      if err != nil {
        return "Authentication Error", err
      }
      w.Header().Add("Content-Type", "text/plain")
      session.Values["username"] = username
      // Write cookie into session
      err = session.Save(r, w)
      if err != nil {
        return "Authentication Error", &utils.AuthError{OriginalError: err}
      }

    } else {
      // We should have an existing session if we are not logging in or creating a new user
    }       
  }

  return f(ctx, w, r, request)
}

We now need to authorize use of our business endpoints when a user submits a valid cookie for their session. Since the first thing we do when we enter our middleware is call the Get method on our session store, we are going to rely on the idea that a user already has an established session once they've run either /newUser or /login successfully. We will check the isNew field of our session struct, and return an authentication error in that case. If the session isn't new, we will add the username saved in the session to the context we pass to our business logic handler:

var sessionStore = sessions.NewCookieStore([]byte("Super secure plz no hax"))
func AuthMiddleWare(f nethttp.StrictHTTPHandlerFunc, operationID string) nethttp.StrictHTTPHandlerFunc {
  return func(ctx context.Context, w http.ResponseWriter, 
               r *http.Request, request interface{}) (response interface{}, err error) {
    session, err := sessionStore.Get(r, "SESSION")
    if err != nil {
      return "Authentication Error", &utils.AuthError{OriginalError: err}
    }
    if operationID == "PostLogin" {
      // Check if user/pw combo exists and make new session if it does   
      username, password, ok := r.BasicAuth()
      if !ok {
        return "Authentication Error", 
                &utils.AuthError{NewError: errors.New("invalid basic auth header")}
      }
      stmt := SELECT(Users.Password).FROM(Users).WHERE(Users.Username.EQ(String(username)))
      var hashedPassword model.Users
      err := stmt.Query(utils.DB, &hashedPassword)
      if err != nil {
        return "Authentication Error", &utils.AuthError{OriginalError: err}
      }
      err = bcrypt.CompareHashAndPassword([]byte(hashedPassword.Password), []byte(password))
      if err != nil {
        if errors.Is(err, bcrypt.ErrMismatchedHashAndPassword) {
          return "Authentication Error", 
                  &utils.AuthError{OriginalError: errors.New("username and password mismatch")}
        } else {
          return "Authentication Error", &utils.AuthError{OriginalError: err}
        }
      }
      w.Header().Add("Content-Type", "text/plain")
      session.Values["username"] = username
      // Write cookie into session
      err = session.Save(r, w)
      if err != nil {
        return "Authentication Error", &utils.AuthError{OriginalError: err}
      }
    } else if operationID == "PostNewUser" {
      // Add a new user/pw combo to DB and create a new session
      username, password, ok := r.BasicAuth()
      if !ok {
        return "Authentication Error", 
                &utils.AuthError{NewError: errors.New("invalid basic auth header")}
      }
      err = CreateNewUser(username, password)
      if err != nil {
        return "Authentication Error", err
      }
      w.Header().Add("Content-Type", "text/plain")
      session.Values["username"] = username
      // Write cookie into session
      err = session.Save(r, w)
      if err != nil {
        return "Authentication Error", &utils.AuthError{OriginalError: err}
      }

    } else if session.IsNew {
      // We should have an existing session if we are not logging in or creating a new user
      return "Authentication Error", 
              &utils.AuthError{NewError: errors.New("must use cookie to access this resource")}
    }
  }
  ctx = context.WithValue(ctx, "username", session.Values["username"])
  return f(ctx, w, r, request)
}

With our middleware defined, we can register it with our generated code and pass it into our server constructor using NewStrictHandlerWithOptions. We will use custom StrictHTTPServerOptions (a type oapi generates) to make sure we send the correct HTTP error code based on whether or not we have correctly authenticated.

It is of important note that a RequestErrorHandlerFunc is only triggered when there is a problem decoding a JSON response body. So although authentication errors are client errors we need to handle them with a custom ResponseErrorHandlerFunc.

m := []nethttp.StrictHTTPMiddlewareFunc{AuthMiddleWare}
server := impl.NewServer()
i := api.NewStrictHandlerWithOptions(server, m, api.StrictHTTPServerOptions{
  RequestErrorHandlerFunc: func(w http.ResponseWriter, r *http.Request, err error) {
    slog.Error("caught client error", "error", err.Error(), "code", http.StatusUnauthorized)
    http.Error(w, err.Error(), http.StatusBadRequest)
  },
  ResponseErrorHandlerFunc: func(w http.ResponseWriter, r *http.Request, err error) {
    // All errors returned by nethttp.StrictHTTPMiddlewareFunc middleware are considered
    // response errors, even though bad auth is technically a bad request. (see codegened
    // stricthandler middleware for details)
    // We're going to be a little messy here and return client error codes with the response 
    // error options so we don't have to rewrite the auth middleware.
    var authErr *utils.AuthError
    if errors.As(err, &authErr) {
      slog.Error("caught client error", "error", err.(*utils.AuthError).BothErrors(), "code", http.StatusUnauthorized)
      http.Error(w, err.Error(), http.StatusUnauthorized)
    } else {
      slog.Error("caught server error", "error", err.Error(), "code", http.StatusInternalServerError)
      http.Error(w, err.Error(), http.StatusInternalServerError)
    }
  },
})
r := http.NewServeMux()
// get an `http.Handler` that we can use
h := api.HandlerFromMux(i, r)

s := &http.Server{
  Handler: h,
  Addr:    "127.0.0.1:8080",
}
// And we serve HTTP until the world ends.
log.Fatal(s.ListenAndServe())

Now we can see who is accessing our endpoint in our business logic hander by accessing its context:

// (POST /runBusinessLogic)
func (Server) PostRunBusinessLogic(
  ctx context.Context, 
  request PostRunBusinessLogicRequestObject) (PostRunBusinessLogicResponseObject, error) {
  username := ctx.Value("username").(string)
  return api.PostRunBusinessLogic200TextResponse(fmt.Sprintf("Hello %s!", username)), nil
}

HTTP Basic Authentication and Session Management With Golang's OAPI-Codegen

Ryan Michael

Read more

Unnecessary Nerd Math - Calculating the Expected Heat of a Battletech Plasma Rifle

AI Can Reason. Kind Of

Making an On-Demand Game Loop Using Go Pt. 2

Making an On-Demand Game Loop Using Go Pt. 1