Getting Started - go-security

go-security is a net/http-native security framework for Go covering session management, authentication, authorization, OAuth2/JWT, and CSRF. It assembles into an http.Handler via a fluent builder and requires only golang.org/x/crypto beyond the standard library.

Installation

go get github.com/thuongh2/go-security

Verify the dependency graph stays clean:

go list -deps ./... | grep -v golang.org/x/crypto
# should list only standard library packages

The 5-line integration

package main

import (
    "log"
    "net/http"

    "github.com/thuongh2/go-security/authn"
    "github.com/thuongh2/go-security/authz"
    "github.com/thuongh2/go-security/crypto/password"
    "github.com/thuongh2/go-security/securityhttp"
    "github.com/thuongh2/go-security/web/session"
)

func main() {
    // 1. Password encoder — bcrypt by default
    encoder := password.NewBcryptEncoder(password.DefaultBcryptCost)

    // 2. User service — implement authn.UserService over your DB
    users := myUserService{}  // see "Implementing UserService" below

    // 3. Authentication manager
    manager := authn.NewManager([]authn.Provider{
        authn.NewPasswordProvider(users, encoder),
    })

    // 4. Session store — swap MemoryStore for Redis in production
    store := session.NewMemoryStore(session.Options{})

    // 5. Assemble the secured handler
    handler, err := securityhttp.NewHandler(myApp(),
        securityhttp.WithSessionStore(store, users),
        securityhttp.WithLogin("/login", manager),
        securityhttp.WithAuthorize(authz.Routes(
            authz.Match("/admin/**").HasRole("ADMIN"),
            authz.Match("/api/**").Authenticated(),
            authz.AnyRequest().PermitAll(),
        )),
    )
    if err != nil {
        log.Fatal(err) // NewHandler errors on misconfiguration — fail loud, never fail open
    }

    log.Fatal(http.ListenAndServe(":8080", handler))
}

What you get for free:

Security headers — X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer
CSRF protection — session-backed synchronizer token
Secure cookies — Secure; HttpOnly; SameSite=Lax
Default-deny authorization — NewHandler() errors if your route set has no catch-all

Implementing UserService

The single method LoadUser loads a user by username. Implement it over your existing user table:

type myUserService struct{ db *sql.DB }

func (s myUserService) LoadUser(ctx context.Context, username string) (*authn.User, error) {
    var u authn.User
    row := s.db.QueryRowContext(ctx,
        `SELECT password_hash, roles, disabled, locked FROM users WHERE username = $1`,
        username,
    )
    err := row.Scan(&u.PasswordHash, pq.Array(&roles), &u.Disabled, &u.Locked)
    if errors.Is(err, sql.ErrNoRows) {
        return nil, authn.ErrUserNotFound // signal "unknown user" to the provider
    }
    if err != nil {
        return nil, err
    }
    u.Username = username
    u.Authorities = parseRoles(roles)
    return &u, nil
}

SessionAuthentication reloads the user on every request, so role changes and account status take effect immediately without requiring a re-login.

Logging in

The login endpoint (POST /login) expects JSON:

{ "username": "alice", "password": "s3cret" }

Success response:

{ "authenticated": true }

The session cookie is set automatically. The CSRF cookie (XSRF-TOKEN) is also set on the first GET through the chain.

Logging out

Send a POST with the CSRF token:

POST /logout HTTP/1.1
X-CSRF-Token: <value-from-XSRF-TOKEN-cookie>

The session is invalidated and the cookie cleared.

Running the playground

The repository includes a self-contained playground that demonstrates the full stack including all four OAuth2 providers:

go run ./examples/playground

Open http://localhost:8080.

Next steps

Core Concepts — Authentication, Authority, the security context
securityhttp — full API reference
authn — Providers — add OAuth2, JWT, API key, or MFA

​Installation

​The 5-line integration

​Implementing UserService

​Logging in

​Logging out

​Running the playground

​Next steps