Documentation
¶
Overview ¶
Package auth tells a service who made a request from an OAuth2 access token Ory Hydra issued. Two ways, one result (Auth):
- JWT access tokens (strategies.access_token: jwt): verified locally against Hydra's public keys, without a call. A revoked token stays valid until it expires (ttl.access_token): the model's promise.
- Introspection: any access token, opaque or JWT, asked of Hydra's admin API on every call. Nothing is cached: a revoked token fails the next call, at the price of a call to the admin API.
Neither caches tokens, so every replica of a service answers alike. The only cache is of the public keys, fetched on first use, on an unknown kid and in the background when old.
Index ¶
- Constants
- Variables
- func GRPCCode(err error) codes.Code
- func HTTPStatus(err error) int
- func WithAuth(ctx context.Context, a Auth) context.Context
- type Auth
- type Authenticator
- func (a Authenticator) Authenticate(ctx context.Context, h http.Header) (Auth, error)
- func (a Authenticator) Optional(next http.Handler) http.Handler
- func (a Authenticator) Required(next http.Handler) http.Handler
- func (a Authenticator) StreamInterceptor(required bool) grpc.StreamServerInterceptor
- func (a Authenticator) UnaryInterceptor(required bool) grpc.UnaryServerInterceptor
- type ExpiredError
- type Introspection
- type Tokens
- type TokensOptions
Constants ¶
const ( // FromJWT: verified locally from a JWT access token. FromJWT = "jwt" // FromIntrospection: Hydra answered for the token. FromIntrospection = "introspection" )
Source of an Auth.
Variables ¶
var ( // ErrNoCredential: the request carries no bearer token. ErrNoCredential = errors.New("auth: no credential") // ErrInvalid: the token is malformed, badly signed, not an access token // or its claims fail. ErrInvalid = errors.New("auth: invalid token") // ErrExpired: the token's exp has passed (or its nbf has not come). ErrExpired = errors.New("auth: token expired") // ErrUnknownKey: the token is signed with a key Hydra does not publish. ErrUnknownKey = errors.New("auth: token signed with an unknown key") // ErrInactive: Hydra says the token is not active (revoked, expired or // never issued). ErrInactive = errors.New("auth: token not active") ErrUnavailable = errors.New("auth: unavailable") )
Errors. Every error of the package wraps one of them.
var ErrOptions = errors.New("auth: options")
ErrOptions: an option is missing or wrong.
Functions ¶
func HTTPStatus ¶
HTTPStatus is the status a refusal for err answers with.
Types ¶
type Auth ¶
type Auth struct {
// Subject is the user the token was issued for, or the client itself
// for client credentials.
Subject string
// ClientID is the OAuth2 client the token was issued to.
ClientID string
// Scopes granted to the token.
Scopes []string
// Audience the token is meant for.
Audience []string
// ExpiresAt and IssuedAt of the token.
ExpiresAt time.Time
IssuedAt time.Time
// TokenID is the token's jti (JWT) — empty from introspection.
TokenID string
// Extra are the claims the consent or the token hook added (Hydra's
// "ext"); with mirrored top-level claims they are in Claims too.
Extra map[string]any
// Claims are all of a JWT's claims (FromJWT).
Claims map[string]any
// Source is FromJWT or FromIntrospection.
Source string
}
Auth is who a token speaks for and what it may do.
func FromContext ¶
FromContext returns the Auth the middleware put into ctx.
type Authenticator ¶
type Authenticator struct {
// Tokens verifies JWT access tokens locally; nil: JWTs go to
// Introspection.
Tokens *Tokens
// Introspection asks Hydra; zero: opaque tokens are refused.
Introspection Introspection
}
Authenticator finds a request's bearer token and verifies it: a JWT with Tokens, any other token (or a JWT when Tokens is nil) with Introspection. Either may be absent: that token is then refused.
func (Authenticator) Authenticate ¶
Authenticate verifies the bearer token the headers carry.
func (Authenticator) Optional ¶
func (a Authenticator) Optional(next http.Handler) http.Handler
Optional lets requests without a token through without an Auth; a token that fails still gets 401.
func (Authenticator) Required ¶
func (a Authenticator) Required(next http.Handler) http.Handler
Required lets through only requests a token authenticates; the others get 401 (503 when Hydra or its keys are unreachable).
func (Authenticator) StreamInterceptor ¶
func (a Authenticator) StreamInterceptor(required bool) grpc.StreamServerInterceptor
StreamInterceptor authenticates every stream (required: refuses anonymous streams too).
func (Authenticator) UnaryInterceptor ¶
func (a Authenticator) UnaryInterceptor(required bool) grpc.UnaryServerInterceptor
UnaryInterceptor authenticates every unary call (required: refuses anonymous calls too).
type ExpiredError ¶ added in v0.0.19
type ExpiredError struct {
Auth Auth
// contains filtered or unexported fields
}
ExpiredError is the refusal of an access token whose signature, issuer and audience verified but whose exp has passed (or nbf has not come). It wraps ErrExpired; Auth names whose token it was, so a caller can tell the client exactly why it is refused. The token is still refused: never authenticate with Auth.
func (*ExpiredError) Error ¶ added in v0.0.19
func (e *ExpiredError) Error() string
func (*ExpiredError) Unwrap ¶ added in v0.0.19
func (e *ExpiredError) Unwrap() error
type Introspection ¶
type Introspection struct {
// contains filtered or unexported fields
}
Introspection asks Hydra's admin API about a token on every call: no cache, so a revoked token fails the next call on every replica.
func NewIntrospection ¶
func NewIntrospection(adminURL string, headers map[string]string, client *http.Client) (Introspection, error)
NewIntrospection asks Hydra's admin API at adminURL (as this service reaches it); headers go with every request (a proxy's authorization); client nil: a client with a 10s timeout.
func (Introspection) Verify ¶
Verify asks Hydra whether token is an active access token and returns what it grants; scopes, when given, must all be granted (Hydra checks).
func (Introspection) WithAudience ¶ added in v0.0.5
func (i Introspection) WithAudience(audience string) Introspection
WithAudience is i requiring tokens whose aud holds audience (see TokensOptions.Audience).
type Tokens ¶
type Tokens struct {
// contains filtered or unexported fields
}
Tokens verifies JWT access tokens locally against Hydra's public keys. One Tokens serves every goroutine; it holds the keys' cache.
func NewTokens ¶
func NewTokens(o TokensOptions) (*Tokens, error)
NewTokens creates the verifier; it fetches nothing until the first token.
type TokensOptions ¶
type TokensOptions struct {
// Issuer is Hydra's issuer (urls.self.issuer) tokens must carry as iss.
// Required.
Issuer string
// KeysURL is Hydra's public keys; empty: <Issuer>/.well-known/jwks.json.
KeysURL string
// Audience is a value tokens' aud must hold. Empty: not checked — then
// a token Hydra issued for another API of the installation is accepted
// too (its signature and issuer still are checked); set it when one
// Hydra serves several APIs and have clients request the audience.
Audience string
// Leeway is the clock skew tolerated on exp, nbf and iat. Default 30s.
Leeway time.Duration
// HTTPClient fetches the keys. Default: a client with a 10s timeout.
HTTPClient *http.Client
// KeysMaxAge is how old the keys may get before a background refetch.
// Default 10m. A token with an unknown kid fetches at once anyway.
KeysMaxAge time.Duration
// KeysMinRefresh is the least time between two fetches. Default 30s.
KeysMinRefresh time.Duration
// Now is the clock (tests). Default time.Now.
Now func() time.Time
}
TokensOptions configure NewTokens.