tokens

README

tokens

The tokens package encapsulates the part of the auth system that handles issuing and validating refresh tokens.

Implementation

Tokens consist of an ID, the profile they correspond to, the scopes that the token has access to, whether the token has been revoked or used yet, and some metadata about its creation. Tokens are only usable once.

Place in the Architecture

Tokens are a method of obtaining a grant using the grants system. That grant can then be traded for a new access token and a new refresh token, to keep their session alive.

Whenever a grant is issued, it should create a new access token using the sessions system and a refresh token using the tokens system. The user then keeps both of those tokens, using the access token to authenticate future requests for their data. When the access token expires, the refresh token should be used as a new grant source to obtain a new grant, which in turn is exchanged for a new access token and refresh token, keeping the cycle going.

Scope

tokens is solely responsible for issuing refresh tokens as part of a session and validating them. The HTTP handlers it provides are responsible for verifying the authentication and authorization of the requests made against it, which will be coming from untrusted sources.

The questions tokens is meant to answer for the system include:

• Is this a valid refresh token?
• For which profile should an access token be issued when this refresh token is redeemed? And for which profile?
• What refresh tokens does a user have floating around right now, unused?

The things tokens is explicitly not expected to do include:

• Manage valid scopes.
• Generate or validate access tokens.
• Understand scopes, clients, or profiles beyond opaque IDs to be passed through transparently.

Documentation

Index

• Constants
• Variables
• type Dependencies
  • func (d Dependencies) CreateJWT(ctx context.Context, token RefreshToken) (string, error)
  • func (d Dependencies) Validate(ctx context.Context, jwtVal string) (RefreshToken, error)
• type RefreshToken
  • func ApplyChange(t RefreshToken, change RefreshTokenChange) RefreshToken
  • func FillTokenDefaults(token RefreshToken) (RefreshToken, error)
• type RefreshTokenChange
  • func (r RefreshTokenChange) HasFilter() bool
  • func (r RefreshTokenChange) IsEmpty() bool
• type Storer

Constants

const (
	// NumTokenResults is the number of Tokens to retrieve when listing Tokens.
	NumTokenResults = 25
)

Variables

var (
	// ErrTokenNotFound is returned when a Token is requested but its ID doesn't exist.
	ErrTokenNotFound = errors.New("token not found")
	// ErrInvalidToken is returned when a Token ID and Value are passed to Validate
	// but do not match a valid Token.
	ErrInvalidToken = errors.New("invalid token")
	// ErrTokenAlreadyExists is returned when a Token is created, but its ID already exists in the Storer.
	ErrTokenAlreadyExists = errors.New("token already exists")
	// ErrTokenRevoked is returned when the Token identified by Validate has been revoked.
	ErrTokenRevoked = errors.New("token revoked")
	// ErrTokenUsed is returned when the Token identified by Validate has already been used.
	ErrTokenUsed = errors.New("token used")
	// ErrNoTokenChangeFilter is returned when a TokenChange is passed to UpdateTokens
	// that has none of the filtering fields set.
	ErrNoTokenChangeFilter = errors.New("invalid token change: must have one or more filter fields set")
)

Types

type Dependencies

type Dependencies struct {
	Storer        Storer // Storer is the Storer to use when retrieving, setting, or removing RefreshTokens.
	JWTPrivateKey *rsa.PrivateKey
	JWTPublicKey  *rsa.PublicKey
	ServiceID     string
}

Dependencies manages the dependency injection for the tokens package. All its properties are required for a Dependencies struct to be valid.

func (Dependencies) CreateJWT

func (d Dependencies) CreateJWT(ctx context.Context, token RefreshToken) (string, error)

CreateJWT returns a signed JWT for `token`, using the private key set in `d.JWTPrivateKey` as the private key to sign with.

func (Dependencies) Validate

func (d Dependencies) Validate(ctx context.Context, jwtVal string) (RefreshToken, error)

Validate checks that the token with the given ID has the given value, and returns an ErrInvalidToken if not.

type RefreshToken

type RefreshToken struct {
	ID          string
	CreatedAt   time.Time
	CreatedFrom string
	Scopes      []string
	ProfileID   string
	ClientID    string
	Revoked     bool
	Used        bool
}

RefreshToken represents a refresh token that can be used to obtain a new access token.

func ApplyChange

func ApplyChange(t RefreshToken, change RefreshTokenChange) RefreshToken

ApplyChange updates the properties on `t` as specified by `change`. It does not check that `t` would be matched by the ID, ProfileID, or ClientID properties of `change`.

func FillTokenDefaults

func FillTokenDefaults(token RefreshToken) (RefreshToken, error)

FillTokenDefaults returns a copy of `token` with all empty properties that have default values, like ID and CreatedAt set to their default values.

type RefreshTokenChange

type RefreshTokenChange struct {
	ID        string
	ProfileID string
	ClientID  string

	Revoked *bool
	Used    *bool
}

RefreshTokenChange represents a change to one or more RefreshTokens. If ID is set, only the RefreshToken specified by that ID will be changed. If ProfileID is set, all Tokens with a matching ProfileID property will be changed. If ClientID is set, all Tokens with a matching ClientID property will be changed.

Revoked and Used specify the new values for the RefreshToken(s)' Revoked or Used properties. If nil, the property won't be updated.

func (RefreshTokenChange) HasFilter

func (r RefreshTokenChange) HasFilter() bool

HasFilter returns true if one of the fields of `r` that is used to filter which tokens to apply the change to is set.

func (RefreshTokenChange) IsEmpty

func (r RefreshTokenChange) IsEmpty() bool

IsEmpty returns true if the RefreshTokenChange would not update any property on the matching RefreshTokens.

type Storer

type Storer interface {
	GetToken(ctx context.Context, id string) (RefreshToken, error)
	CreateToken(ctx context.Context, token RefreshToken) error
	UpdateTokens(ctx context.Context, change RefreshTokenChange) error
	UseToken(ctx context.Context, id string) error
	GetTokensByProfileID(ctx context.Context, profileID string, since, before time.Time) ([]RefreshToken, error)
}

Storer represents an interface to a persistence method for RefreshTokens. It is used to store, update, and retrieve RefreshTokens.