tokens

Documentation

Index

• type CachedJWKSValidator
  • func NewCachedJWKSValidator(ctx context.Context, cache *jwk.Cache, endpoint, audience, issuer string) (validator *CachedJWKSValidator, err error)
  • func (v *CachedJWKSValidator) Parse(tks string) (claims *Claims, err error)
  • func (v *CachedJWKSValidator) Refresh(ctx context.Context) (err error)
  • func (v *CachedJWKSValidator) Verify(tks string) (claims *Claims, err error)
• type Claims
  • func (c Claims) HasAllPermissions(requiredPermissions ...string) bool
  • func (c Claims) HasPermission(requiredPermission string) bool
  • func (c Claims) ParseOrgID() ulid.ULID
  • func (c Claims) ParseUserID() ulid.ULID
• type JWKSValidator
  • func NewJWKSValidator(keys jwk.Set, audience, issuer string) *JWKSValidator
  • func (v *JWKSValidator) Parse(tks string) (claims *Claims, err error)
  • func (v *JWKSValidator) Verify(tks string) (claims *Claims, err error)
• type MockValidator
  • func (m *MockValidator) Parse(tks string) (*Claims, error)
  • func (m *MockValidator) Verify(tks string) (*Claims, error)
• type TokenManager
  • func New(conf config.TokenConfig) (tm *TokenManager, err error)
  • func NewWithKey(key *rsa.PrivateKey, conf config.TokenConfig) (tm *TokenManager, err error)
  • func (tm *TokenManager) CreateAccessToken(claims *Claims) (_ *jwt.Token, err error)
  • func (tm *TokenManager) CreateRefreshToken(accessToken *jwt.Token) (refreshToken *jwt.Token, err error)
  • func (tm *TokenManager) CreateTokenPair(claims *Claims) (accessToken, refreshToken string, err error)
  • func (tm *TokenManager) CurrentKey() ulid.ULID
  • func (tm *TokenManager) Keys() (keys jwk.Set, err error)
  • func (v *TokenManager) Parse(tks string) (claims *Claims, err error)
  • func (tm *TokenManager) Sign(token *jwt.Token) (tks string, err error)
  • func (v *TokenManager) Verify(tks string) (claims *Claims, err error)
• type Validator

Types

type CachedJWKSValidator

type CachedJWKSValidator struct {
	JWKSValidator
	// contains filtered or unexported fields
}

func NewCachedJWKSValidator

func NewCachedJWKSValidator(ctx context.Context, cache *jwk.Cache, endpoint, audience, issuer string) (validator *CachedJWKSValidator, err error)

func (*CachedJWKSValidator) Parse

func (v *CachedJWKSValidator) 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 (*CachedJWKSValidator) Refresh

func (v *CachedJWKSValidator) Refresh(ctx context.Context) (err error)

func (*CachedJWKSValidator) Verify

func (v *CachedJWKSValidator) Verify(tks string) (claims *Claims, err error)

Verify an access or a refresh token after parsing and return its claims.

type Claims

type Claims struct {
	jwt.RegisteredClaims
	Name        string   `json:"name,omitempty"`
	Email       string   `json:"email,omitempty"`
	Picture     string   `json:"picture,omitempty"`
	OrgID       string   `json:"org,omitempty"`
	ProjectID   string   `json:"project,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
}

Claims implements custom claims for the Quarterdeck application.

func (Claims) HasAllPermissions

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

HasAllPermissions checks if all specified permissions are in the claims.

func (Claims) HasPermission

func (c Claims) HasPermission(requiredPermission string) bool

HasPermission checks if the claims contain the specified permission.

func (Claims) ParseOrgID

func (c Claims) ParseOrgID() ulid.ULID

ParseOrgID returns the ULID of the organization ID in the claims. If the OrgID is not valid then an empty ULID is returned without an error to reduce error checking in handlers. If the caller needs to know if the ULID is invalid they should parse it themselves; otherwise the Null ULID will prevent most accesses from succeeding.

func (Claims) ParseUserID

func (c Claims) ParseUserID() ulid.ULID

ParseUserID returns the ULID of the user from the Subject of the claims. If the UserID is not valid then an empty ULID is returned without an error to reduce error checking in the handlers. If the caller needs to know if the ULID is invalid, they should parse it themsleves or perform an IsZero check on the result.

type JWKSValidator

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

JWKSValidator provides public verification that JWT tokens have been issued by the Quarterdeck authentication service by checking that the tokens have been signed using public keys from a JSON Web Key Set (JWKS). The validator then returns Quarterdeck specific claims if the token is in fact valid.

func NewJWKSValidator

func NewJWKSValidator(keys jwk.Set, audience, issuer string) *JWKSValidator

func (*JWKSValidator) Parse

func (v *JWKSValidator) 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 (*JWKSValidator) Verify

func (v *JWKSValidator) Verify(tks string) (claims *Claims, err error)

Verify an access or a refresh token after parsing and return its claims.

type MockValidator

type MockValidator struct {
	OnVerify func(string) (*Claims, error)
	OnParse  func(string) (*Claims, error)
	Calls    map[string]int
}

func (*MockValidator) Parse

func (m *MockValidator) Parse(tks string) (*Claims, error)

func (*MockValidator) Verify

func (m *MockValidator) Verify(tks string) (*Claims, error)

type TokenManager

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

TokenManager handles the creation and verification of RSA signed JWT tokens. To facilitate signing key rollover, TokenManager can accept multiple keys identified by a ulid. JWT tokens generated by token managers include a kid in the header that allows the token manager to verify the key with the specified signature. To sign keys the token manager will always use the latest private key by ulid.

When the TokenManager creates tokens it will use JWT standard claims as well as extended claims based on Quarterdeck usage. The standard claims included are exp, nbf aud, and sub. On token verification, the exp, nbf, iss and aud claims are validated. TODO: Create automatic key rotation mechanism rather than loading keys.

func New

func New(conf config.TokenConfig) (tm *TokenManager, err error)

New creates a TokenManager with the specified keys which should be a mapping of ULID strings to paths to files that contain PEM encoded RSA private keys. This input is specifically designed for the config environment variable so that keys can be loaded from k8s or vault secrets that are mounted as files on disk.

func NewWithKey

func NewWithKey(key *rsa.PrivateKey, conf config.TokenConfig) (tm *TokenManager, err error)

func (*TokenManager) CreateAccessToken

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

CreateAccessToken from the credential payload or from an previous token if the access token is being reauthorized from previous credentials. Note that the returned token only contains the claims and is unsigned.

func (*TokenManager) CreateRefreshToken

func (tm *TokenManager) CreateRefreshToken(accessToken *jwt.Token) (refreshToken *jwt.Token, err error)

CreateRefreshToken from the Access token claims with predefined expiration. Note that the returned token only contains the claims and is unsigned.

func (*TokenManager) CreateTokenPair

func (tm *TokenManager) CreateTokenPair(claims *Claims) (accessToken, refreshToken string, err error)

CreateTokenPair returns signed access and refresh tokens for the specified claims in one step (since normally users want both an access and a refresh token)!

func (*TokenManager) CurrentKey

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

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

func (*TokenManager) Keys

func (tm *TokenManager) Keys() (keys jwk.Set, err error)

Keys returns the JSON Web Key Set with public keys for use externally.

func (*TokenManager) Parse

func (v *TokenManager) 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 (*TokenManager) Sign

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

Sign an access or refresh token and return the token string.

func (*TokenManager) Verify

func (v *TokenManager) Verify(tks string) (claims *Claims, err error)

Verify an access or a refresh token after parsing and return its claims.

type Validator

type Validator interface {
	// Verify an access or a refresh token after parsing and return its claims.
	Verify(tks string) (claims *Claims, err error)

	// Parse an access or refresh token without verifying claims (e.g. to check an expired token).
	Parse(tks string) (claims *Claims, err error)
}

Validators are able to verify that access and refresh tokens were issued by Quarterdeck and that their claims are valid (e.g. not expired).