tokens

Documentation

Overview

Package tokens handles the creation and verification of JWT tokens for authentication.

Index

• type Claims
• type TokenManager
  • func MockTokenManager() (tm *TokenManager, err error)
  • func New(keys map[string]string, audience string) (tm *TokenManager, err error)
  • func (tm *TokenManager) CreateAccessToken(creds interface{}) (_ *jwt.Token, err error)
  • func (tm *TokenManager) CreateRefreshToken(accessToken *jwt.Token) (refreshToken *jwt.Token, err error)
  • func (tm *TokenManager) CurrentKey() ksuid.KSUID
  • func (tm *TokenManager) Keys() map[ksuid.KSUID]*rsa.PublicKey
  • func (tm *TokenManager) Parse(tks string) (claims *Claims, err error)
  • func (tm *TokenManager) Sign(token *jwt.Token) (tks string, err error)
  • func (tm *TokenManager) Validate(ctx context.Context, idToken, audience string) (*idtoken.Payload, error)
  • func (tm *TokenManager) Verify(tks string) (claims *Claims, err error)

Types

type Claims

type Claims struct {
	jwt.RegisteredClaims
	Domain  string `json:"hd,omitempty"`
	Email   string `json:"email,omitempty"`
	Name    string `json:"name,omitempty"`
	Picture string `json:"picture,omitempty"`
}

Claims implements custom claims for the GDS application to hold user data provided from external openid sources. It also embeds the standard JWT claims.

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 ksuid. 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 ksuid.

When the TokenManager creates tokens it will use JWT standard claims as well as extended claims based on Oauth credentials. The standard claims included are exp, nbf aud, and sub. The iss claim is optional and would duplicate aud, so it is omitted. On token verification, the exp, nbf, and aud claims are validated.

func MockTokenManager

func MockTokenManager() (tm *TokenManager, err error)

MockTokenManager creates a new TokenManager with a randomly generated RSA key to be used for testing external code that depends on the Token Manager.

func New

func New(keys map[string]string, audience string) (tm *TokenManager, err error)

New creates a TokenManager with the specified keys which should be a mapping of KSUID 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 (*TokenManager) CreateAccessToken

func (tm *TokenManager) CreateAccessToken(creds interface{}) (_ *jwt.Token, err error)

CreateAccessToken from the verified Google 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) CurrentKey

func (tm *TokenManager) CurrentKey() ksuid.KSUID

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

func (*TokenManager) Keys

func (tm *TokenManager) Keys() map[ksuid.KSUID]*rsa.PublicKey

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

func (*TokenManager) Parse

func (tm *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) Validate

func (tm *TokenManager) Validate(ctx context.Context, idToken, audience string) (*idtoken.Payload, error)

Validate the given token using the provided audience and return the token's payload. This method provides a convenient way for tests to circumvent Google's specific validation logic in order to test successful authentication.

func (*TokenManager) Verify

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

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