userauth

Documentation

Overview

Package userauth verifies the short-lived RS256 JWT the GitLab Rails monolith mints (via Authn::TokenExchange::TokenIssuer).

Index

• type Config
  • func (c Config) Validate() error
• type FailReason
• type GitLabClaims
• type Issuer
• type Option
  • func WithFetchErrorHandler(fn func(error)) Option
  • func WithFetchSuccessHandler(fn func()) Option
• type Token
• type Verifier
  • func NewVerifier(ctx context.Context, cfg Config, opts ...Option) (*Verifier, error)
  • func (v *Verifier) Ready() bool
  • func (v *Verifier) Verify(_ context.Context, rawToken string) (*Token, error)
• type VerifyError
  • func (e *VerifyError) Error() string
  • func (e *VerifyError) Unwrap() error

Types

type Config

type Config struct {
	Issuers           []Issuer `mapstructure:"issuers"`
	ExpectedAudiences []string `mapstructure:"expected_audiences"`
}

func (Config) Validate

func (c Config) Validate() error

type FailReason

type FailReason string

const (
	ReasonInvalidToken FailReason = "invalid_token"
	// ReasonExpired: signature/issuer/claims are valid but the token is past exp. Kept distinct from
	// invalid_token so consumers can handle an expired token separately from an unverifiable one.
	ReasonExpired FailReason = "expired"
	// ReasonKeysUnavailable: the JWKS could not be fetched (unreachable, timeout, or non-2xx), so no
	// token can be verified yet. The token itself may be valid — a transient condition.
	ReasonKeysUnavailable FailReason = "keys_unavailable"
)

type GitLabClaims

type GitLabClaims struct {
	Origin           string
	OriginID         string
	LocalID          string
	IdentityKind     string
	OrganizationRole string // optional
}

GitLabClaims is the nested "gitlab" object (ADR-021). LocalID is minted as a JSON number but surfaced as a string.

type Issuer

type Issuer struct {
	URL     string `mapstructure:"url"`
	KeysURL string `mapstructure:"keys_url"`
}

type Option

type Option func(*options)

func WithFetchErrorHandler

func WithFetchErrorHandler(fn func(error)) Option

func WithFetchSuccessHandler

func WithFetchSuccessHandler(fn func()) Option

type Token

type Token struct {
	Issuer    string
	Subject   string // opaque GlobalID; never parsed
	Audience  []string
	IssuedAt  time.Time
	NotBefore time.Time
	Expiry    time.Time

	Version int // "ver" claim
	GitLab  GitLabClaims
}

type Verifier

type Verifier struct {
	// contains filtered or unexported fields
}

func NewVerifier

func NewVerifier(ctx context.Context, cfg Config, opts ...Option) (*Verifier, error)

func (*Verifier) Ready

func (v *Verifier) Ready() bool

func (*Verifier) Verify

func (v *Verifier) Verify(_ context.Context, rawToken string) (*Token, error)

type VerifyError

type VerifyError struct {
	Reason FailReason
	// contains filtered or unexported fields
}

func (*VerifyError) Error

func (e *VerifyError) Error() string

func (*VerifyError) Unwrap

func (e *VerifyError) Unwrap() error