auth

Documentation

Index

• Constants
• func ClearAuthCookies(c *gin.Context, audience []string)
• func ClearResetPasswordTokenCookie(c *gin.Context, domain string)
• func ClearSecureCookie(c *gin.Context, name, domain string, httpOnly bool)
• func IsLocalhost(domain string) bool
• func SetAuthCookies(c *gin.Context, accessToken, refreshToken string) (err error)
• func SetResetPasswordTokenCookie(c *gin.Context, token, domain string)
• func SetSecureCookie(c *gin.Context, name, value string, maxAge int, domain string, httpOnly bool)
• func SigningMethod() jwt.SigningMethod
• type Issuer
  • func NewIssuer(conf config.AuthConfig) (_ *Issuer, err error)
  • func (tm *Issuer) AddKey(keyID ulid.ULID, key SigningKey) (err error)
  • func (tm *Issuer) ComputeETag(data []byte)
  • func (tm *Issuer) CreateAccessToken(claims *auth.Claims) (_ *jwt.Token, err error)
  • func (tm *Issuer) CreateRefreshToken(accessToken *jwt.Token) (_ *jwt.Token, err error)
  • func (tm *Issuer) CreateTokens(claims *auth.Claims) (signedAccessToken, signedRefreshToken string, err error)
  • func (tm *Issuer) CurrentKey() ulid.ULID
  • func (tm *Issuer) Directives() string
  • func (tm *Issuer) ETag() string
  • func (tm *Issuer) Expires() time.Time
  • func (tm *Issuer) GetKey(token *jwt.Token) (key interface{}, err error)
  • func (tm *Issuer) Keys() (_ *JWKS, err error)
  • func (tm *Issuer) LastModified() time.Time
  • func (tm *Issuer) Modified(t time.Time, d any)
  • func (tm *Issuer) NotAuthorized(c *gin.Context) (err error)
  • func (tm *Issuer) Parse(tks string) (claims *auth.Claims, err error)
  • func (tm *Issuer) RefreshAudience() string
  • func (tm *Issuer) SetETag(s string)
  • func (tm *Issuer) SetMaxAge(v any)
  • func (tm *Issuer) SetSMaxAge(v any)
  • func (tm *Issuer) Sign(token *jwt.Token) (tks string, err error)
  • func (tm *Issuer) Verify(tks string) (claims *auth.Claims, err error)
• type JWKS
  • func (j *JWKS) Add(keyID ulid.ULID, key SigningKey) error
  • func (j *JWKS) ComputeETag([]byte)
  • func (j *JWKS) Directives() string
  • func (j *JWKS) ETag() string
  • func (j *JWKS) Expires() time.Time
  • func (j *JWKS) LastModified() time.Time
  • func (j *JWKS) Modified(time.Time, any)
  • func (j *JWKS) SetETag(etag string)
  • func (j *JWKS) SetMaxAge(any)
  • func (j *JWKS) SetSMaxAge(any)
• type SigningKey
  • func GenerateKeys() (_ SigningKey, err error)
  • func LoadKeys(path string) (_ SigningKey, err error)

Constants

const (
	AccessTokenCookie        = "access_token"
	RefreshTokenCookie       = "refresh_token"
	ResetPasswordTokenCookie = "reset_password_token"

	CookieMaxAgeBuffer          = 600 * time.Second
	ResetPasswordTokenCookieTTL = 900 * time.Second // 15 minutes; same as [server.resetPasswordTokenTTL]

)

const (
	JWKSMaxAge               = 7 * 24 * time.Hour
	JWKSStaleWhileRevalidate = 24 * time.Hour
)

const (
	BlockPublicKey  = "PUBLIC KEY"
	BlockPrivateKey = "PRIVATE KEY"
)

Functions

func ClearAuthCookies

func ClearAuthCookies(c *gin.Context, audience []string)

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

func ClearResetPasswordTokenCookie

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

func ClearSecureCookie

func ClearSecureCookie(c *gin.Context, name, domain string, httpOnly bool)

func IsLocalhost

func IsLocalhost(domain string) bool

func SetAuthCookies

func SetAuthCookies(c *gin.Context, accessToken, refreshToken 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.

The cookie domains are set based on the access token audience (the refresh token audience is the issuer so must duplicate the access token audience).

func SetResetPasswordTokenCookie

func SetResetPasswordTokenCookie(c *gin.Context, token, domain string)

func SetSecureCookie

func SetSecureCookie(c *gin.Context, name, value string, maxAge int, domain string, httpOnly bool)

func SigningMethod

func SigningMethod() jwt.SigningMethod

Types

type Issuer

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

func NewIssuer

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

func (*Issuer) AddKey

func (tm *Issuer) AddKey(keyID ulid.ULID, key SigningKey) (err error)

AddKey adds a new key to the issuer and updates the current key if the new is newer than the current key. The keyID must be a valid ULID and the ULID timestamp must fall after the current key's timestamp.

func (*Issuer) ComputeETag

func (tm *Issuer) ComputeETag(data []byte)

func (*Issuer) CreateAccessToken

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

func (*Issuer) CreateRefreshToken

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

func (*Issuer) CreateTokens

func (tm *Issuer) CreateTokens(claims *auth.Claims) (signedAccessToken, signedRefreshToken string, err error)

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

func (*Issuer) CurrentKey

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

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

func (*Issuer) Directives

func (tm *Issuer) Directives() string

func (*Issuer) ETag

func (tm *Issuer) ETag() string

func (*Issuer) Expires

func (tm *Issuer) Expires() time.Time

func (*Issuer) GetKey

func (tm *Issuer) GetKey(token *jwt.Token) (key interface{}, err error)

GetKey is an jwt.KeyFunc that selects the public key from the list of managed internal keys based on the kid in the token header. If the kid does not exist an error is returned and the token will not be able to be verified.

func (*Issuer) Keys

func (tm *Issuer) Keys() (_ *JWKS, err error)

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

func (*Issuer) LastModified

func (tm *Issuer) LastModified() time.Time

func (*Issuer) Modified

func (tm *Issuer) Modified(t time.Time, d any)

func (*Issuer) NotAuthorized

func (tm *Issuer) NotAuthorized(c *gin.Context) (err error)

func (*Issuer) Parse

func (tm *Issuer) Parse(tks string) (claims *auth.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 (*Issuer) RefreshAudience

func (tm *Issuer) RefreshAudience() string

Computes the refresh audience claim based on the issuer URL and a specific path to better protect refresh tokens from being used in other contexts.

func (*Issuer) SetETag

func (tm *Issuer) SetETag(s string)

func (*Issuer) SetMaxAge

func (tm *Issuer) SetMaxAge(v any)

func (*Issuer) SetSMaxAge

func (tm *Issuer) SetSMaxAge(v any)

func (*Issuer) Sign

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

func (*Issuer) Verify

func (tm *Issuer) Verify(tks string) (claims *auth.Claims, err error)

type JWKS

type JWKS struct {
	sync.RWMutex
	jose.JSONWebKeySet
	// contains filtered or unexported fields
}

func (*JWKS) Add

func (j *JWKS) Add(keyID ulid.ULID, key SigningKey) error

Append a key to the JWKS. If a key with the same KeyID already exists, an error is returned.

func (*JWKS) ComputeETag

func (j *JWKS) ComputeETag([]byte)

ComputeETag to implement the ETagger interface but panics and should not be used.

func (*JWKS) Directives

func (j *JWKS) Directives() string

func (*JWKS) ETag

func (j *JWKS) ETag() string

func (*JWKS) Expires

func (j *JWKS) Expires() time.Time

func (*JWKS) LastModified

func (j *JWKS) LastModified() time.Time

func (*JWKS) Modified

func (j *JWKS) Modified(time.Time, any)

func (*JWKS) SetETag

func (j *JWKS) SetETag(etag string)

SetETag to implement the ETagger interface but panics and should not be used.

func (*JWKS) SetMaxAge

func (j *JWKS) SetMaxAge(any)

func (*JWKS) SetSMaxAge

func (j *JWKS) SetSMaxAge(any)

type SigningKey

type SigningKey interface {
	Dump(path string) error
	PublicKey() crypto.PublicKey
	PrivateKey() crypto.PrivateKey
}

SigningKey is an interface for cryptographic keys used for token signing without the need for callers to understand the specific signature algorithm.

func GenerateKeys

func GenerateKeys() (_ SigningKey, err error)

func LoadKeys

func LoadKeys(path string) (_ SigningKey, err error)

Load the specified keys from the filesystem TODO: support loading keys from a vault or other secure storage.