auth

Documentation

Overview

Package auth handles auth

Index

• Constants
• Variables
• func AuthContextFromRequest(c echo.Context) (*context.Context, error)
• func Authenticate(conf AuthOptions) echo.MiddlewareFunc
• func ClearAuthCookies(w http.ResponseWriter)
• func CookieExpired(cookie *http.Cookie) bool
• func GetAccessToken(c echo.Context) (string, error)
• func GetActorUserID(c echo.Context) (string, error)
• func GetClaims(c echo.Context) (*tokens.Claims, error)
• func GetOrganizationID(c echo.Context) (string, error)
• func GetOrganizationIDFromContext(ctx context.Context) (string, error)
• func GetRefreshToken(c echo.Context) (string, error)
• func GetUserIDFromContext(ctx context.Context) (string, error)
• func NewTestContextWithOrgID(orgID string) (echo.Context, error)
• func NewTestContextWithValidUser(subject string) (echo.Context, error)
• func Reauthenticate(conf AuthOptions, validator tokens.Validator) func(c echo.Context) (string, error)
• func SetAuthCookies(w http.ResponseWriter, accessToken, refreshToken string)
• type AuthOption
  • func WithAudience(audience string) AuthOption
  • func WithAuthOptions(opts AuthOptions) AuthOption
  • func WithBeforeFunc(before middleware.BeforeFunc) AuthOption
  • func WithContext(ctx context.Context) AuthOption
  • func WithIssuer(issuer string) AuthOption
  • func WithJWKSEndpoint(url string) AuthOption
  • func WithMinRefreshInterval(interval time.Duration) AuthOption
  • func WithReauthenticator(reauth Reauthenticator) AuthOption
  • func WithSkipperFunc(skipper middleware.Skipper) AuthOption
  • func WithValidator(validator tokens.Validator) AuthOption
• type AuthOptions
  • func NewAuthOptions(opts ...AuthOption) (conf AuthOptions)
  • func (conf *AuthOptions) Validator() (tokens.Validator, error)
• type ContextKey
• type LoginReply
• type Reauthenticator
• type RefreshRequest

Constants

const (
	Authorization             = "Authorization"
	DefaultKeysURL            = "http://localhost:17608/.well-known/jwks.json"
	DefaultAudience           = "http://localhost:17608"
	DefaultIssuer             = "http://localhost:17608"
	DefaultMinRefreshInterval = 5 * time.Minute
	AccessTokenCookie         = "access_token"
	RefreshTokenCookie        = "refresh_token"
)

Variables

var (
	// ErrNoClaims is returned when no claims are found on the request context
	ErrNoClaims = errors.New("no claims found on the request context")

	// ErrNoUserInfo is returned when no user info is found on the request context
	ErrNoUserInfo = errors.New("no user info found on the request context")

	// ErrNoAuthUser is returned when no authenticated user is found on the request context
	ErrNoAuthUser = errors.New("could not identify authenticated user in request")

	// ErrUnverifiedUser is returned when the user is not verified
	ErrUnverifiedUser = errors.New("user is not verified")

	// ErrParseBearer is returned when the bearer token could not be parsed from the authorization header
	ErrParseBearer = errors.New("could not parse bearer token from authorization header")

	// ErrNoAuthorization is returned when no authorization header is found in the request
	ErrNoAuthorization = errors.New("no authorization header in request")

	// ErrNoRequest is returned when no request is found on the context
	ErrNoRequest = errors.New("no request found on the context")

	// ErrNoRefreshToken is returned when no refresh token is found on the request
	ErrNoRefreshToken = errors.New("no refresh token available on request")

	// ErrRefreshDisabled is returned when re-authentication with refresh tokens is disabled
	ErrRefreshDisabled = errors.New("re-authentication with refresh tokens disabled")

	// ErrUnableToConstructValidator is returned when the validator cannot be constructed
	ErrUnableToConstructValidator = errors.New("unable to construct validator")

	// ErrPasswordTooWeak is returned when the password is too weak
	ErrPasswordTooWeak = errors.New("password is too weak: use a combination of upper and lower case letters, numbers, and special characters")
)

var ContextAccessToken = &ContextKey{"access_token"}

ContextAccessToken is the context key for the access token

var ContextRequestID = &ContextKey{"request_id"}

ContextRequestID is the context key for the request ID

var ContextUserClaims = &ContextKey{"user_claims"}

ContextUserClaims is the context key for the user claims

Functions

func AuthContextFromRequest

func AuthContextFromRequest(c echo.Context) (*context.Context, error)

AuthContextFromRequest creates a context from the echo request context, copying fields that may be required for forwarded requests. This method should be called by handlers which need to forward requests to other services and need to preserve data from the original request such as the user's credentials.

func Authenticate

func Authenticate(conf AuthOptions) echo.MiddlewareFunc

Authenticate is a middleware function that is used to authenticate requests - it is not applied to all routes so be cognizant of that

func ClearAuthCookies

func ClearAuthCookies(w http.ResponseWriter)

ClearAuthCookies is a helper function to clear authentication cookies on a echo request to effectively logger out a user.

func CookieExpired

func CookieExpired(cookie *http.Cookie) bool

CookieExpired checks to see if a cookie is expired

func GetAccessToken

func GetAccessToken(c echo.Context) (string, error)

GetAccessToken retrieves the bearer token from the authorization header and parses it to return only the JWT access token component of the header. Alternatively, if the authorization header is not present, then the token is fetched from cookies. If the header is missing or the token is not available, an error is returned.

NOTE: the authorization header takes precedence over access tokens in cookies.

func GetActorUserID

func GetActorUserID(c echo.Context) (string, error)

GetActorUserID returns the user from the echo.Context

func GetClaims

func GetClaims(c echo.Context) (*tokens.Claims, error)

GetClaims fetches and parses datum claims from the echo context. Returns an error if no claims exist on the context

func GetOrganizationID

func GetOrganizationID(c echo.Context) (string, error)

GetOrganizationID returns the organization ID from the echo.Context

func GetOrganizationIDFromContext

func GetOrganizationIDFromContext(ctx context.Context) (string, error)

GetOrganizationIDFromContext returns the organization ID from context from context

func GetRefreshToken

func GetRefreshToken(c echo.Context) (string, error)

GetRefreshToken retrieves the refresh token from the cookies in the request. If the cookie is not present or expired then an error is returned.

func GetUserIDFromContext

func GetUserIDFromContext(ctx context.Context) (string, error)

GetUserIDFromContext returns the actor subject from the echo context

func NewTestContextWithOrgID

func NewTestContextWithOrgID(orgID string) (echo.Context, error)

NewTestContextWithOrgID creates an echo context with a fake orgID for testing purposes ONLY

func NewTestContextWithValidUser

func NewTestContextWithValidUser(subject string) (echo.Context, error)

NewTestContextWithValidUser creates an echo context with a fake subject for testing purposes ONLY

func Reauthenticate

func Reauthenticate(conf AuthOptions, validator tokens.Validator) func(c echo.Context) (string, error)

Reauthenticate is a middleware helper that can use refresh tokens in the echo context to obtain a new access token. If it is unable to obtain a new valid access token, then an error is returned and processing should stop.

func SetAuthCookies

func SetAuthCookies(w http.ResponseWriter, accessToken, refreshToken string)

SetAuthCookies is a helper function to set authentication cookies on a echo request. The access token cookie (access_token) is an http only cookie that expires when the access token expires. The refresh token cookie is not an http only cookie (it can be accessed by client-side scripts) and it expires when the refresh token expires. Both cookies require https and will not be set (silently) over http connections.

Types

type AuthOption

type AuthOption func(opts *AuthOptions)

AuthOption allows users to optionally supply configuration to the Authorization middleware.

func WithAudience

func WithAudience(audience string) AuthOption

WithAudience allows the user to specify an alternative audience.

func WithAuthOptions

func WithAuthOptions(opts AuthOptions) AuthOption

WithAuthOptions allows the user to update the default auth options with an auth options struct to set many options values at once. Zero values are ignored, so if using this option, the defaults will still be preserved if not set on the input.

func WithBeforeFunc

func WithBeforeFunc(before middleware.BeforeFunc) AuthOption

WithBeforeFunc allows the user to specify a function to happen before the auth middleware

func WithContext

func WithContext(ctx context.Context) AuthOption

WithContext allows the user to specify an external, cancelable context to control the background refresh behavior of the JWKS cache.

func WithIssuer

func WithIssuer(issuer string) AuthOption

WithIssuer allows the user to specify an alternative issuer.

func WithJWKSEndpoint

func WithJWKSEndpoint(url string) AuthOption

WithJWKSEndpoint allows the user to specify an alternative endpoint to fetch the JWKS public keys from. This is useful for testing or for different environments.

func WithMinRefreshInterval

func WithMinRefreshInterval(interval time.Duration) AuthOption

WithMinRefreshInterval allows the user to specify an alternative minimum duration between cache refreshes to control refresh behavior for the JWKS public keys.

func WithReauthenticator

func WithReauthenticator(reauth Reauthenticator) AuthOption

WithReauthenticator allows the user to specify a reauthenticator to the auth middleware.

func WithSkipperFunc

func WithSkipperFunc(skipper middleware.Skipper) AuthOption

WithSkipperFunc allows the user to specify a skipper function for the middleware

func WithValidator

func WithValidator(validator tokens.Validator) AuthOption

WithValidator allows the user to specify an alternative validator to the auth middleware. This is particularly useful for testing authentication.

type AuthOptions

type AuthOptions struct {
	// KeysURL endpoint to the JWKS public keys on the datum server
	KeysURL string
	// Audience to verify on tokens
	Audience string
	// Issuer to verify on tokens
	Issuer string
	// MinRefreshInterval to cache the JWKS public keys
	MinRefreshInterval time.Duration
	// Context to control the lifecycle of the background fetch routine
	Context context.Context

	// Skipper defines a function to skip middleware
	Skipper middleware.Skipper
	// BeforeFunc  defines a function which is executed just before the middleware
	BeforeFunc middleware.BeforeFunc
	// contains filtered or unexported fields
}

AuthOptions is constructed from variadic AuthOption arguments with reasonable defaults.

func NewAuthOptions

func NewAuthOptions(opts ...AuthOption) (conf AuthOptions)

NewAuthOptions creates an AuthOptions object with reasonable defaults and any user supplied input from the AuthOption variadic arguments.

func (*AuthOptions) Validator

func (conf *AuthOptions) Validator() (tokens.Validator, error)

Validator returns the user supplied validator or constructs a new JWKS Cache Validator from the supplied options. If the options are invalid or the validator cannot be created an error is returned

type ContextKey

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

ContextKey is the key name for the additional context

type LoginReply

type LoginReply struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token,omitempty"`
	LastLogin    string `json:"last_login,omitempty"`
}

type Reauthenticator

type Reauthenticator interface {
	Refresh(context.Context, *RefreshRequest) (*LoginReply, error)
}

Reauthenticator generates new access and refresh pair given a valid refresh token.

type RefreshRequest

type RefreshRequest struct {
	RefreshToken string `json:"refresh_token"`
	OrgID        string `json:"org_id,omitempty"`
}