auth

Documentation

Index

• Constants
• Variables
• func Authenticate(issuer *ClaimsIssuer) gin.HandlerFunc
• func Authorize(permissions ...string) gin.HandlerFunc
• func ClearAuthCookies(c *gin.Context, domain string)
• func ExpiresAt(tks string) (_ time.Time, err error)
• func GetAccessToken(c *gin.Context) (tks string, err error)
• func GetOrganization() string
• func GetRefreshToken(c *gin.Context) (tks string, err error)
• func IsLocalhost(domain string) bool
• func NotBefore(tks string) (_ time.Time, err error)
• func ParseUnverified(tks string) (claims *jwt.RegisteredClaims, err error)
• func SetAuthCookies(c *gin.Context, accessToken, refreshToken, domain string) (err error)
• func SetOrganization(o string)
• type Claims
  • func GetClaims(c *gin.Context) (*Claims, error)
  • func NewClaims(ctx context.Context, model any) (*Claims, error)
  • func NewClaimsForAPIClient(ctx context.Context, key *models.APIKey) (claims *Claims, err error)
  • func NewClaimsForUser(ctx context.Context, user *models.User) (claims *Claims, err error)
  • func (c Claims) HasAllPermissions(required ...string) bool
  • func (c Claims) HasPermission(required string) bool
  • func (c *Claims) SetSubjectID(sub SubjectType, id ulid.ULID)
  • func (c Claims) SubjectID() (SubjectType, ulid.ULID, error)
• type ClaimsIssuer
  • func NewIssuer(conf config.AuthConfig) (_ *ClaimsIssuer, err error)
  • func (tm *ClaimsIssuer) CreateAccessToken(claims *Claims) (_ *jwt.Token, err error)
  • func (tm *ClaimsIssuer) CreateRefreshToken(accessToken *jwt.Token) (_ *jwt.Token, err error)
  • func (tm *ClaimsIssuer) CreateTokens(claims *Claims) (signedAccessToken, signedRefreshToken string, err error)
  • func (tm *ClaimsIssuer) CurrentKey() ulid.ULID
  • func (tm *ClaimsIssuer) Keys() map[ulid.ULID]*rsa.PublicKey
  • func (tm *ClaimsIssuer) Parse(tks string) (claims *Claims, err error)
  • func (tm *ClaimsIssuer) RefreshAudience() string
  • func (tm *ClaimsIssuer) Sign(token *jwt.Token) (tks string, err error)
  • func (tm *ClaimsIssuer) Verify(tks string) (claims *Claims, err error)
• type SubjectType

Constants

const (
	SubjectUser   = SubjectType('u')
	SubjectAPIKey = SubjectType('k')
)

const (
	Authorization      = "Authorization"
	AccessTokenCookie  = "access_token"
	RefreshTokenCookie = "refresh_token"
	ContextUserClaims  = "user_claims"
	CookieMaxAgeBuffer = 600 * time.Second
)

const (
	DefaultRefreshAudience = "http://localhost:8000/v1/reauthenticate"
)

Variables

var (
	ErrUnknownSigningKey = errors.New("unknown signing key")
	ErrNoKeyID           = errors.New("token does not have kid in header")
	ErrInvalidKeyID      = errors.New("invalid key id")
	ErrUnparsableClaims  = errors.New("could not parse or verify claims")
	ErrInvalidAudience   = errors.New("invalid audience")
	ErrInvalidIssuer     = errors.New("invalid issuer")
	ErrUnauthenticated   = errors.New("request is unauthenticated")
	ErrNoClaims          = errors.New("no claims found on the request context")
	ErrNoUserInfo        = errors.New("no user info found on the request context")
	ErrInvalidAuthToken  = errors.New("invalid authorization token")
	ErrAuthRequired      = errors.New("this endpoint requires authentication")
	ErrNotAuthorized     = errors.New("user does not have permission to perform this operation")
	ErrNoAuthUser        = errors.New("could not identify authenticated user in request")
	ErrParseBearer       = errors.New("could not parse Bearer token from Authorization header")
	ErrNoAuthorization   = errors.New("no authorization header or cookies in request")
	ErrNoRefreshToken    = errors.New("cannot reauthenticate no refresh token in request")
	ErrNotAccepted       = errors.New("the accepted formats are not offered by the server")
)

Authentication Errors

Functions

func Authenticate

func Authenticate(issuer *ClaimsIssuer) gin.HandlerFunc

func Authorize

func Authorize(permissions ...string) gin.HandlerFunc

func ClearAuthCookies

func ClearAuthCookies(c *gin.Context, domain string)

ClearAuthCookies is a helper function to clear authentication cookies on a gin request to effectively log out a user.

func ExpiresAt

func ExpiresAt(tks string) (_ time.Time, err error)

func GetAccessToken

func GetAccessToken(c *gin.Context) (tks string, err 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 GetOrganization

func GetOrganization() string

Get the current organization that is being used for all new user claims.

func GetRefreshToken

func GetRefreshToken(c *gin.Context) (tks string, err 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 IsLocalhost

func IsLocalhost(domain string) bool

func NotBefore

func NotBefore(tks string) (_ time.Time, err error)

func ParseUnverified

func ParseUnverified(tks string) (claims *jwt.RegisteredClaims, err error)

func SetAuthCookies

func SetAuthCookies(c *gin.Context, accessToken, refreshToken, domain string) (err error)

SetAuthCookies is a helper function to set authentication cookies on a gin 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.

func SetOrganization

func SetOrganization(o string)

Set the organization for any new user claims.

Types

type Claims

type Claims struct {
	jwt.RegisteredClaims
	ClientID     string   `json:"clientID,omitempty"`
	Name         string   `json:"name,omitempty"`
	Email        string   `json:"email,omitempty"`
	Gravatar     string   `json:"gravatar,omitempty"`
	Organization string   `json:"org,omitempty"`
	Role         string   `json:"role,omitempty"`
	Permissions  []string `json:"permissions,omitempty"`
}

func GetClaims

func GetClaims(c *gin.Context) (*Claims, error)

func NewClaims

func NewClaims(ctx context.Context, model any) (*Claims, error)

func NewClaimsForAPIClient

func NewClaimsForAPIClient(ctx context.Context, key *models.APIKey) (claims *Claims, err error)

func NewClaimsForUser

func NewClaimsForUser(ctx context.Context, user *models.User) (claims *Claims, err error)

func (Claims) HasAllPermissions

func (c Claims) HasAllPermissions(required ...string) bool

func (Claims) HasPermission

func (c Claims) HasPermission(required string) bool

func (*Claims) SetSubjectID

func (c *Claims) SetSubjectID(sub SubjectType, id ulid.ULID)

func (Claims) SubjectID

func (c Claims) SubjectID() (SubjectType, ulid.ULID, error)

type ClaimsIssuer

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

func NewIssuer

func NewIssuer(conf config.AuthConfig) (_ *ClaimsIssuer, err error)

func (*ClaimsIssuer) CreateAccessToken

func (tm *ClaimsIssuer) CreateAccessToken(claims *Claims) (_ *jwt.Token, err error)

func (*ClaimsIssuer) CreateRefreshToken

func (tm *ClaimsIssuer) CreateRefreshToken(accessToken *jwt.Token) (_ *jwt.Token, err error)

func (*ClaimsIssuer) CreateTokens

func (tm *ClaimsIssuer) CreateTokens(claims *Claims) (signedAccessToken, signedRefreshToken string, err error)

CreateTokens creates and signs an access and refresh token in one step.

func (*ClaimsIssuer) CurrentKey

func (tm *ClaimsIssuer) CurrentKey() ulid.ULID

CurrentKey returns the ulid of the current key being used to sign tokens.

func (*ClaimsIssuer) Keys

func (tm *ClaimsIssuer) Keys() map[ulid.ULID]*rsa.PublicKey

Keys returns the map of ulid to public key for use externally.

func (*ClaimsIssuer) Parse

func (tm *ClaimsIssuer) Parse(tks string) (claims *Claims, err error)

Parse an access or refresh token verifying its signature but without verifying its claims. This ensures that valid JWT tokens are still accepted but claims can be handled on a case-by-case basis; for example by validating an expired access token during reauthentication.

func (*ClaimsIssuer) RefreshAudience

func (tm *ClaimsIssuer) RefreshAudience() string

func (*ClaimsIssuer) Sign

func (tm *ClaimsIssuer) Sign(token *jwt.Token) (tks string, err error)

func (*ClaimsIssuer) Verify

func (tm *ClaimsIssuer) Verify(tks string) (claims *Claims, err error)

type SubjectType

type SubjectType rune