authtoken

Documentation

Overview

Package authtoken provides an authtoken with an encrypted value and an associated expiration time. It also provides a repository which manages the lifetime of the token.

The auth token value is a base62 bit value with a version prefix. This value is encrypted at rest and is used to authenticate incoming requests to the controller. It is associated with a public id which allows admins to operate on it without knowing the token itself. It also has an expiration time and a last accessed time which are used to determine if the token can still be used.

Repository

A repository provides methods for creating, validating a provided token value, and deleting the auth token. At validation time if the token is determined to be expired or stale it will be removed from the backing storage by the repo.

Index

• Constants
• func EncryptToken(ctx context.Context, kmsCache *kms.Kms, scopeId, publicId, token string) (string, error)
• type AuthToken
  • func TestAuthToken(t *testing.T, conn *gorm.DB, kms *kms.Kms, scopeId string) *AuthToken
  • func (s *AuthToken) SetTableName(n string)
  • func (s *AuthToken) TableName() string
• type Option
  • func WithLimit(limit int) Option
  • func WithTokenTimeToLiveDuration(ttl time.Duration) Option
  • func WithTokenTimeToStaleDuration(dur time.Duration) Option
• type Repository
  • func NewRepository(r db.Reader, w db.Writer, kms *kms.Kms, opt ...Option) (*Repository, error)
  • func (r *Repository) CreateAuthToken(ctx context.Context, withIamUser *iam.User, withAuthAccountId string, ...) (*AuthToken, error)
  • func (r *Repository) DeleteAuthToken(ctx context.Context, id string, opt ...Option) (int, error)
  • func (r *Repository) ListAuthTokens(ctx context.Context, withScopeIds []string, opt ...Option) ([]*AuthToken, error)
  • func (r *Repository) LookupAuthToken(ctx context.Context, id string, opt ...Option) (*AuthToken, error)
  • func (r *Repository) ValidateToken(ctx context.Context, id, token string, opt ...Option) (*AuthToken, error)

Constants

const (
	AuthTokenPrefix = "at"
	// The version prefix is used to differentiate token versions just for future proofing.
	TokenValueVersionPrefix = "0"
)

Functions

func EncryptToken

func EncryptToken(ctx context.Context, kmsCache *kms.Kms, scopeId, publicId, token string) (string, error)

EncryptToken is a shared function for encrypting a token value for return to the user.

Types

type AuthToken

type AuthToken struct {
	*store.AuthToken
	// contains filtered or unexported fields
}

A AuthToken contains auth tokens. It is owned by a scope.

func TestAuthToken

func TestAuthToken(t *testing.T, conn *gorm.DB, kms *kms.Kms, scopeId string) *AuthToken

func (*AuthToken) SetTableName

func (s *AuthToken) SetTableName(n string)

SetTableName sets the table name. If the caller attempts to set the name to "" the name will be reset to the default name.

func (*AuthToken) TableName

func (s *AuthToken) TableName() string

TableName returns the table name for the auth token.

type Option

type Option func(*options)

Option - how Options are passed as arguments.

func WithLimit

func WithLimit(limit int) Option

WithLimit provides an option to provide a limit. Intentionally allowing negative integers. If WithLimit < 0, then unlimited results are returned. If WithLimit == 0, then default limits are used for results.

func WithTokenTimeToLiveDuration

func WithTokenTimeToLiveDuration(ttl time.Duration) Option

WithTokenTimeToLiveDuration allows setting the auth token time-to-live.

func WithTokenTimeToStaleDuration

func WithTokenTimeToStaleDuration(dur time.Duration) Option

WithTokenTimeToStaleDuration allows setting the auth token staleness duration.

type Repository

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

A Repository stores and retrieves the persistent types in the authtoken package. It is not safe to use a repository concurrently.

func NewRepository

func NewRepository(r db.Reader, w db.Writer, kms *kms.Kms, opt ...Option) (*Repository, error)

NewRepository creates a new Repository. The returned repository is not safe for concurrent go routines to access it.

func (*Repository) CreateAuthToken

func (r *Repository) CreateAuthToken(ctx context.Context, withIamUser *iam.User, withAuthAccountId string, opt ...Option) (*AuthToken, error)

CreateAuthToken inserts an Auth Token into the repository and returns a new Auth Token. The returned auth token contains the auth token value. The provided IAM User ID must be associated to the provided auth account id or an error will be returned. All options are ignored.

func (*Repository) DeleteAuthToken

func (r *Repository) DeleteAuthToken(ctx context.Context, id string, opt ...Option) (int, error)

DeleteAuthToken deletes the token with the provided id from the repository returning a count of the number of records deleted. All options are ignored.

func (*Repository) ListAuthTokens

func (r *Repository) ListAuthTokens(ctx context.Context, withScopeIds []string, opt ...Option) ([]*AuthToken, error)

ListAuthTokens lists auth tokens in the given scopes and supports the WithLimit option.

func (*Repository) LookupAuthToken

func (r *Repository) LookupAuthToken(ctx context.Context, id string, opt ...Option) (*AuthToken, error)

LookupAuthToken returns the AuthToken for the provided id. Returns nil, nil if no AuthToken is found for id. For security reasons, the actual token is not included in the returned AuthToken. All exported options are ignored.

func (*Repository) ValidateToken

func (r *Repository) ValidateToken(ctx context.Context, id, token string, opt ...Option) (*AuthToken, error)

ValidateToken returns a token from storage if the auth token with the provided id and token exists. The approximate last accessed time may be updated depending on how long it has been since the last time the token was validated. If a token is returned it is guaranteed to be valid. For security reasons, the actual token value is not included in the returned AuthToken. If no valid auth token is found nil, nil is returned. All options are ignored.

NOTE: Do not log or add the token string to any errors to avoid leaking it as it is a secret.