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 ¶
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") )
Functions ¶
This section is empty.
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 ¶ added in v0.2.0
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.
Source Files
Directories