Documentation
¶
Overview ¶
Package auth implements single-admin authentication for HTTP services.
Index ¶
- Constants
- Variables
- type AuthError
- type AuthMethod
- type ErrorCode
- type Manager
- func (m *Manager) Authenticate(request *http.Request) (Principal, error)
- func (m *Manager) AuthenticateBearer(token string) (Principal, error)
- func (m *Manager) ClearSession(writer http.ResponseWriter, request *http.Request)
- func (m *Manager) CookieName() string
- func (m *Manager) CurrentSession(request *http.Request) (Session, error)
- func (m *Manager) IssueSession(writer http.ResponseWriter, request *http.Request) (Session, error)
- type Option
- type Principal
- type Session
Constants ¶
const (
AdminSubject = "admin"
)
Variables ¶
var ( ErrMissingCredentials = &AuthError{Code: CodeMissingCredentials} ErrInvalidBearer = &AuthError{Code: CodeInvalidBearer} ErrInvalidSession = &AuthError{Code: CodeInvalidSession} ErrExpiredSession = &AuthError{Code: CodeExpiredSession} ErrCSRF = &AuthError{Code: CodeCSRF} )
Functions ¶
This section is empty.
Types ¶
type AuthError ¶
type AuthError struct {
Code ErrorCode
}
AuthError is a typed authentication error returned by Authenticate and AuthenticateBearer. Callers can inspect Code or use errors.Is with the exported sentinel errors below.
type AuthMethod ¶
type AuthMethod string
AuthMethod identifies how a request was authenticated.
const ( // AuthMethodBearer identifies a request authenticated with an admin bearer token. AuthMethodBearer AuthMethod = "bearer" // AuthMethodSession identifies a request authenticated with a signed browser session. AuthMethodSession AuthMethod = "session" )
type ErrorCode ¶
type ErrorCode string
ErrorCode classifies an authentication failure without exposing credentials.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager validates the single admin bearer token and issues signed browser sessions. It retains only the SHA-256 hash of the admin token; the plaintext admin token is not kept after initialization.
func NewManager ¶
NewManager loads or creates the admin token and session HMAC key at their caller-specified paths. Both files are created with, and normalized to, mode 0600. The returned bootstrapToken is non-empty only when this call created the admin token; callers may display it once for initial setup. An existing stored token is never returned.
func (*Manager) Authenticate ¶
Authenticate authenticates an HTTP request. A supplied Authorization header takes precedence over a session cookie. Cookie-authenticated state-changing requests require a matching X-CSRF-Token header; bearer-authenticated requests do not.
func (*Manager) AuthenticateBearer ¶
AuthenticateBearer validates token using a constant-time comparison and returns the admin principal on success.
func (*Manager) ClearSession ¶
func (m *Manager) ClearSession(writer http.ResponseWriter, request *http.Request)
ClearSession expires the configured browser session cookie.
func (*Manager) CookieName ¶
CookieName returns the configured browser session cookie name.
func (*Manager) CurrentSession ¶
CurrentSession validates the signed browser session and returns the browser values needed to make CSRF-protected requests. It never exposes the bearer token or the session signing key.
func (*Manager) IssueSession ¶
IssueSession writes a signed, expiring browser session cookie and returns its CSRF token. Call it only after the caller has authenticated an administrator. X-Forwarded-Proto is trusted for Secure-cookie detection, so deployments must ensure it is stripped or set only by a trusted reverse proxy.
type Option ¶
type Option func(*managerOptions) error
Option configures a Manager.
func WithClock ¶
WithClock supplies the clock used to issue and validate session expiry. It is useful when an application already has a controlled time source.
func WithCookieName ¶
WithCookieName sets the name of the browser session cookie.
func WithSessionTTL ¶
WithSessionTTL sets the lifetime used for newly issued browser sessions.
type Principal ¶
type Principal struct {
Subject string
Method AuthMethod
}
Principal is the authenticated identity for a request.
git-ci has one administrative identity, identified by AdminSubject.
Source Files