oidcauth

Documentation

Overview

package oidcauth bundles up an opinionated approach to authentication using both the OIDC authorization code workflow and simple JWT decoding (via static keys, JWKS, and OIDC discovery).

NOTE: This was roughly forked from hashicorp/vault-plugin-auth-jwt originally at commit 825c85535e3832d254a74253a8e9ae105357778b with later backports of behavior in 0e93b06cecb0477d6ee004e44b04832d110096cf

Index

• Constants
• type Authenticator
  • func New(c *Config, logger hclog.Logger) (*Authenticator, error)
  • func (a *Authenticator) ClaimsFromAuthCode(ctx context.Context, stateParam, code string) (*Claims, interface{}, error)
  • func (a *Authenticator) ClaimsFromJWT(ctx context.Context, jwt string) (*Claims, error)
  • func (a *Authenticator) GetAuthCodeURL(ctx context.Context, redirectURI string, statePayload interface{}) (string, error)
  • func (a *Authenticator) Stop()
• type Claims
• type Config
  • func (c *Config) Validate() error
• type ProviderLoginFailedError
  • func (e *ProviderLoginFailedError) Error() string
  • func (e *ProviderLoginFailedError) Unwrap() error
• type TokenVerificationFailedError
  • func (e *TokenVerificationFailedError) Error() string
  • func (e *TokenVerificationFailedError) Unwrap() error

Constants

const (
	// TypeOIDC is the config type to specify if the OIDC authorization code
	// workflow is desired. The Authenticator methods GetAuthCodeURL and
	// ClaimsFromAuthCode are activated with the type.
	TypeOIDC = "oidc"

	// TypeJWT is the config type to specify if simple JWT decoding (via static
	// keys, JWKS, and OIDC discovery) is desired.  The Authenticator method
	// ClaimsFromJWT is activated with this type.
	TypeJWT = "jwt"
)

Types

type Authenticator

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

Authenticator allows for extracting a set of claims from either an OIDC authorization code exchange or a bare JWT.

func New

func New(c *Config, logger hclog.Logger) (*Authenticator, error)

New creates an authenticator suitable for use with either an OIDC authorization code workflow or a bare JWT workflow depending upon the value of the config Type.

func (*Authenticator) ClaimsFromAuthCode

func (a *Authenticator) ClaimsFromAuthCode(ctx context.Context, stateParam, code string) (*Claims, interface{}, error)

ClaimsFromAuthCode is the second part of the OIDC authorization code workflow. The interface{} return value is the statePayload previously passed via GetAuthCodeURL.

The error may be of type *ProviderLoginFailedError or *TokenVerificationFailedError which can be detected via errors.As().

Requires the authenticator's config type be set to 'oidc'.

func (*Authenticator) ClaimsFromJWT

func (a *Authenticator) ClaimsFromJWT(ctx context.Context, jwt string) (*Claims, error)

ClaimsFromJWT is unrelated to the OIDC authorization code workflow. This allows for a JWT to be directly validated and decoded into a set of claims.

Requires the authenticator's config type be set to 'jwt'.

func (*Authenticator) GetAuthCodeURL

func (a *Authenticator) GetAuthCodeURL(ctx context.Context, redirectURI string, statePayload interface{}) (string, error)

GetAuthCodeURL is the first part of the OIDC authorization code workflow. The statePayload field is stored in the Authenticator instance keyed by the "state" key so it can be returned during a future call to ClaimsFromAuthCode.

Requires the authenticator's config type be set to 'oidc'.

func (*Authenticator) Stop

func (a *Authenticator) Stop()

Stop stops any background goroutines and does cleanup.

type Claims

type Claims struct {
	// Values is a set of key/value string claims about the authentication
	// exchange.
	Values map[string]string

	// Lists is a set of key/value string list claims about the authentication
	// exchange.
	Lists map[string][]string
}

Claims represents a set of claims or assertions computed about a given authentication exchange.

type Config

type Config struct {
	// Type defines which kind of authentication will be happening, OIDC-based
	// or JWT-based.  Allowed values are either 'oidc' or 'jwt'.
	//
	// Defaults to 'oidc' if unset.
	Type string

	// JWTSupportedAlgs is a list of supported signing algorithms. Defaults to
	// RS256.
	JWTSupportedAlgs []string

	// Comma-separated list of 'aud' claims that are valid for login; any match
	// is sufficient
	// TODO(sso): actually just send these down as string claims?
	BoundAudiences []string

	// Mappings of claims (key) that will be copied to a metadata field
	// (value). Use this if the claim you are capturing is singular (such as an
	// attribute).
	//
	// When mapped, the values can be any of a number, string, or boolean and
	// will all be stringified when returned.
	ClaimMappings map[string]string

	// Mappings of claims (key) that will be copied to a metadata field
	// (value). Use this if the claim you are capturing is list-like (such as
	// groups).
	//
	// When mapped, the values in each list can be any of a number, string, or
	// boolean and will all be stringified when returned.
	ListClaimMappings map[string]string

	// OIDCDiscoveryURL is the OIDC Discovery URL, without any .well-known
	// component (base path).  Cannot be used with "JWKSURL" or
	// "JWTValidationPubKeys".
	OIDCDiscoveryURL string

	// OIDCDiscoveryCACert is the CA certificate or chain of certificates, in
	// PEM format, to use to validate connections to the OIDC Discovery URL. If
	// not set, system certificates are used.
	OIDCDiscoveryCACert string

	// OIDCClientID is the OAuth Client ID configured with your OIDC provider.
	//
	// Valid only if Type=oidc
	OIDCClientID string

	// The OAuth Client Secret configured with your OIDC provider.
	//
	// Valid only if Type=oidc
	OIDCClientSecret string

	// Comma-separated list of OIDC scopes
	//
	// Valid only if Type=oidc
	OIDCScopes []string

	// Comma-separated list of allowed values for redirect_uri
	//
	// Valid only if Type=oidc
	AllowedRedirectURIs []string

	// Log received OIDC tokens and claims when debug-level logging is active.
	// Not recommended in production since sensitive information may be present
	// in OIDC responses.
	//
	// Valid only if Type=oidc
	VerboseOIDCLogging bool

	// JWKSURL is the JWKS URL to use to authenticate signatures. Cannot be
	// used with "OIDCDiscoveryURL" or "JWTValidationPubKeys".
	//
	// Valid only if Type=jwt
	JWKSURL string

	// JWKSCACert is the CA certificate or chain of certificates, in PEM
	// format, to use to validate connections to the JWKS URL. If not set,
	// system certificates are used.
	//
	// Valid only if Type=jwt
	JWKSCACert string

	// JWTValidationPubKeys is a list of PEM-encoded public keys to use to
	// authenticate signatures locally. Cannot be used with "JWKSURL" or
	// "OIDCDiscoveryURL".
	//
	// Valid only if Type=jwt
	JWTValidationPubKeys []string

	// BoundIssuer is the value against which to match the 'iss' claim in a
	// JWT.  Optional.
	//
	// Valid only if Type=jwt
	BoundIssuer string

	// Duration in seconds of leeway when validating expiration of
	// a token to account for clock skew.
	//
	// Defaults to 150 (2.5 minutes) if set to 0 and can be disabled if set to -1.`,
	//
	// Valid only if Type=jwt
	ExpirationLeeway time.Duration

	// Duration in seconds of leeway when validating not before values of a
	// token to account for clock skew.
	//
	// Defaults to 150 (2.5 minutes) if set to 0 and can be disabled if set to
	// -1.`,
	//
	// Valid only if Type=jwt
	NotBeforeLeeway time.Duration

	// Duration in seconds of leeway when validating all claims to account for
	// clock skew.
	//
	// Defaults to 60 (1 minute) if set to 0 and can be disabled if set to
	// -1.`,
	//
	// Valid only if Type=jwt
	ClockSkewLeeway time.Duration
}

Config is the collection of all settings that pertain to doing OIDC-based authentication and direct JWT-based authentication processes.

func (*Config) Validate

func (c *Config) Validate() error

Validate returns an error if the config is not valid.

type ProviderLoginFailedError

type ProviderLoginFailedError struct {
	Err error
}

ProviderLoginFailedError is an error type sometimes returned from ClaimsFromAuthCode().

It represents a failure to complete the authorization code workflow with the provider such as losing important OIDC parameters or a failure to fetch an id_token.

You can check for it with errors.As().

func (*ProviderLoginFailedError) Error

func (e *ProviderLoginFailedError) Error() string

func (*ProviderLoginFailedError) Unwrap

func (e *ProviderLoginFailedError) Unwrap() error

type TokenVerificationFailedError

type TokenVerificationFailedError struct {
	Err error
}

TokenVerificationFailedError is an error type sometimes returned from ClaimsFromAuthCode().

It represents a failure to vet the returned OIDC credentials for validity such as the id_token not passing verification or using an mismatched nonce.

You can check for it with errors.As().

func (*TokenVerificationFailedError) Error

func (e *TokenVerificationFailedError) Error() string

func (*TokenVerificationFailedError) Unwrap

func (e *TokenVerificationFailedError) Unwrap() error