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 CreateDerivedKey(password string) (_ string, err error)
• func ExpiresAt(tks string) (_ time.Time, err error)
• func GetAccessToken(c *gin.Context) (tks string, err error)
• func GetRefreshToken(c *gin.Context) (tks string, err error)
• func IsDerivedKey(s string) bool
• func NotBefore(tks string) (_ time.Time, err error)
• func ParseDerivedKey(encoded string) (dk, salt []byte, time, memory uint32, threads uint8, err error)
• func ParseUnverified(tks string) (claims *jwt.RegisteredClaims, err error)
• func Reauthenticate(issuer *ClaimsIssuer) gin.HandlerFunc
• func SetAuthCookies(c *gin.Context, accessToken, refreshToken, domain string) (err error)
• func VerifyDerivedKey(dk, password string) (_ bool, err error)
• type Claims
  • func GetClaims(c *gin.Context) (*Claims, error)
  • func (c Claims) HasAllPermissions(required ...string) bool
  • func (c Claims) HasPermission(required string) bool
  • func (c *Claims) SetSubjectID(uid int64)
  • func (c Claims) SubjectId() (int64, 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) Sign(token *jwt.Token) (tks string, err error)
  • func (tm *ClaimsIssuer) Verify(tks string) (claims *Claims, err error)

Constants

const (
	ContextUserClaims  = "user_claims"
	ContextAccessToken = "access_token"
	ContextRequestID   = "request_id"
	AccessTokenCookie  = "access_token"
	RefreshTokenCookie = "refresh_token"
)

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 in request")
	ErrNoRefreshToken    = errors.New("cannot reauthenticate no refresh token in request")
)

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 CreateDerivedKey

func CreateDerivedKey(password string) (_ string, err error)

CreateDerivedKey creates an encoded derived key with a random hash for the password.

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 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 IsDerivedKey

func IsDerivedKey(s string) bool

func NotBefore

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

func ParseDerivedKey

func ParseDerivedKey(encoded string) (dk, salt []byte, time, memory uint32, threads uint8, err error)

ParseDerivedKey returns the parts of the encoded derived key string.

func ParseUnverified

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

func Reauthenticate

func Reauthenticate(issuer *ClaimsIssuer) gin.HandlerFunc

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 VerifyDerivedKey

func VerifyDerivedKey(dk, password string) (_ bool, err error)

VerifyDerivedKey checks that the submitted password matches the derived key.

Types

type Claims

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

func GetClaims

func GetClaims(c *gin.Context) (*Claims, 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(uid int64)

func (Claims) SubjectId

func (c Claims) SubjectId() (int64, 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) 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)