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)
• func NewAuthTokenId(ctx context.Context) (string, error)
• type AuthToken
  • func TestAuthToken(t testing.TB, conn *db.DB, kms *kms.Kms, scopeId string, opt ...Option) *AuthToken
  • func (s *AuthToken) SetTableName(n string)
  • func (s *AuthToken) TableName() string
• type Option
  • func WithIamOptions(with ...iam.Option) Option
  • func WithLimit(limit int) Option
  • func WithPasswordOptions(with ...password.Option) Option
  • func WithPublicId(id string) Option
  • func WithStatus(status Status) Option
  • func WithTokenTimeToLiveDuration(ttl time.Duration) Option
  • func WithTokenTimeToStaleDuration(dur time.Duration) Option
• type Repository
  • func NewRepository(ctx context.Context, r db.Reader, w db.Writer, kms *kms.Kms, opt ...Option) (*Repository, error)
  • func (r *Repository) CloseExpiredPendingTokens(ctx context.Context) (int, 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) IssueAuthToken(ctx context.Context, tokenRequestId string) (*AuthToken, 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)
• type Status

Constants

const (
	// 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.

func NewAuthTokenId

func NewAuthTokenId(ctx context.Context) (string, error)

NewAuthTokenId creates a new id for an auth token.

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.TB, conn *db.DB, kms *kms.Kms, scopeId string, opt ...Option) *AuthToken

TestAuthToken, despite its name, does more than just return an auth token; it also creates an auth method, an account, and a user and binds them together, then creates an auth token against it

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 WithIamOptions

func WithIamOptions(with ...iam.Option) Option

WithIamOptions allows passing through options for the IAM package. This is useful for things like tests where you may use testing helper functions in this package but they also create IAM resources.

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 WithPasswordOptions

func WithPasswordOptions(with ...password.Option) Option

WithPasswordOptions allows passing through options for the password package. This is useful for things like tests where you may use testing helper functions in this package but they also create password resources.

func WithPublicId

func WithPublicId(id string) Option

WithPublicId allows the setting of the auth token's public id

func WithStatus

func WithStatus(status Status) Option

WithStatus allows setting of the auth token's Status.

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(ctx context.Context, 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) CloseExpiredPendingTokens

func (r *Repository) CloseExpiredPendingTokens(ctx context.Context) (int, error)

CloseExpiredPendingTokens will close expired pending tokens in the repo. This function should called on a periodic basis a Controllers via it's "ticker" pattern.

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. The Auth Token will have a Status of "issued". The WithStatus and WithPublicId options are supported and all other 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) IssueAuthToken

func (r *Repository) IssueAuthToken(ctx context.Context, tokenRequestId string) (*AuthToken, error)

IssueAuthToken will retrieve the "pending" token and update it's status to "issued". If the token has already been issued, an error is returned with a nil token. If no token is found for the tokenRequestId an error is returned with a nil token.

Note: no oplog entries are created for auth token operations (this is intentional).

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.

type Status

type Status string

Status of the AuthToken. It will default IssuedStatus in the database.

const (
	// UnknownStatus for the token.
	UnknownStatus Status = "unknown"

	// PendingStatus means that the token has been created but it pending while
	// waiting to be issued.
	PendingStatus Status = "auth token pending"

	// IssuedStatus means the token has been issued.  It is a final status for the
	// token.
	IssuedStatus Status = "token issued"

	// FailedStatus means the token is in a failed status before it was issued and
	// this is a final status.
	FailedStatus Status = "authentication failed"

	// SystemErrorStatus means that the system encountered an error before
	// issuing the token. This is a final status.
	SystemErrorStatus Status = "system error"
)