Core Concepts - go-security

go-security models authentication and authorization around three core concepts: an Authentication carrying the current security state, an Authority granted to that principal, and a SecurityContext threaded through context.Context. Interfaces stand in for annotations, and plain middleware functions replace filter chains.

Authentication

An authentication (core.Authentication) represents the security state of a request. It is either:

Unauthenticated — a request token carrying credentials yet to be verified (e.g. *core.UsernamePasswordToken)
Authenticated — a result token with a verified principal and granted authorities (e.g. *core.AuthenticatedToken)

// Read the current authentication from any handler
auth := core.MustAuthentication(r.Context())
fmt.Println(auth.Authenticated())  // true / false
fmt.Println(auth.Name())           // "alice" or "anonymousUser"
fmt.Println(auth.Authorities())    // [ROLE_ADMIN, ROLE_USER]

core.MustAuthentication panics if no authentication is on the context — use core.AuthenticationFrom for the optional form:

if auth, ok := core.AuthenticationFrom(r.Context()); ok && auth.Authenticated() {
    // handle authenticated request
}

Authority

An authority (core.Authority) is a string value granted to a principal. Roles are authorities with the ROLE_ prefix:

core.Roles("ADMIN", "USER")        // → [ROLE_ADMIN, ROLE_USER]
core.Authority("read:reports")     // → a custom authority

The HasRole authorization rule auto-prefixes with ROLE_:

authz.Routes(authz.Match("/admin/**").HasRole("ADMIN")) // checks for ROLE_ADMIN

The Security Context

The authentication lives on context.Context, scoped to the request:

// Placed on the context by SessionAuthentication middleware
ctx = core.WithAuthentication(r.Context(), auth)

// Read from any function that receives the context
auth, ok := core.AuthenticationFrom(ctx)

The middleware chain places the authentication on the context before your handlers see the request. You never manage this manually.

Authentication Flow

Request
  │
  ▼
SessionAuthentication      ← reads session cookie, reloads User from UserService
  │
  ▼
Anonymous middleware        ← injects ROLE_ANONYMOUS if still unauthenticated
  │
  ▼
CSRF middleware             ← validates token for unsafe methods
  │
  ▼
Authorization middleware    ← first-match-wins route rules
  │
  ▼
Your handler                ← core.MustAuthentication(r.Context()) always works

Manager and Providers

authn.Manager fans out to a list of authn.Provider implementations. Each provider handles one kind of credential:

manager := authn.NewManager([]authn.Provider{
    authn.NewPasswordProvider(users, encoder),    // username/password
    authn.NewBearerTokenProvider(tokenAuth),       // JWT bearer
    authn.NewAPIKeyProvider(apiKeyService),        // API key header
})

The manager iterates providers in order and calls the first one that returns Supports(token) == true — first-supporting-provider-wins dispatch.

User

authn.User is the UserDetails equivalent:

type User struct {
    Username           string
    PasswordHash       string
    Authorities        []core.Authority
    Disabled           bool
    Locked             bool
    AccountExpired     bool
    CredentialsExpired bool
}

User.Check() returns the first account-status error (core.ErrAccountDisabled, core.ErrAccountLocked, etc.) or nil when the account is usable.

Sentinel Errors

All authentication failures wrap a sentinel from core:

Sentinel	Meaning
`core.ErrBadCredentials`	Wrong password or token
`core.ErrAccountDisabled`	Account flagged `Disabled`
`core.ErrAccountLocked`	Account flagged `Locked`
`core.ErrAccountExpired`	Account flagged `AccountExpired`
`core.ErrCredentialsExpired`	Account flagged `CredentialsExpired`
`core.ErrProviderNotFound`	No provider supports the token type
`authn.ErrUserNotFound`	`UserService.LoadUser` found no user

Match them with errors.Is:

auth, err := manager.Authenticate(ctx, token)
if errors.Is(err, core.ErrBadCredentials) { /* ... */ }

​Authentication

​Authority

​The Security Context

​Authentication Flow

​Manager and Providers

​User

​Sentinel Errors