credentials

Documentation

Index

• Variables
• func IsTokenProviderHappy(tp TokenProvider) bool
• type BaseTokenOptions
• type Credentials
  • func New(thelmaConfig config.Config, thelmaRoot root.Root) (Credentials, error)
  • func NewWithStore(store stores.Store) Credentials
• type MockTokenProvider
  • func (m *MockTokenProvider) Get() ([]byte, error)
  • func (m *MockTokenProvider) Reissue() ([]byte, error)
• type TokenOption
• type TokenOptions
• type TokenProvider
  • func GetTypedTokenProvider[T any](c Credentials, key string, options ...TypedTokenOption[T]) (TokenProvider, error)
• type TypedTokenOption
• type TypedTokenOptions

Variables

var (
	TokenProviders = map[string]TokenProvider{}
)

Functions

func IsTokenProviderHappy

func IsTokenProviderHappy(tp TokenProvider) bool

IsTokenProviderHappy helps other packages check if a TokenProvider is set up properly. It's a simple check but defining it here helps with encapsulation. It can handle nil inputs.

Types

type BaseTokenOptions

type BaseTokenOptions struct {
	// EnvVars (optional) environment variables to use for this token. Defaults to key (upper-cased with s/-/_/, eg. "vault-token" -> "VAULT_TOKEN").
	// Ideally only one environment variable should be used, but multiple are supported for backwards compatibility.
	// Environment variables will be checked both with the "THELMA_" prefix and without.
	EnvVars []string
	// PromptEnabled (optional) if true, user will be prompted to manually enter a token value if one does not exist in credential store.
	PromptEnabled bool
	// PromptMessage (optional) Override default prompt message ("Please enter VAULT_TOKEN: ")
	PromptMessage string
	// CredentialStore (optional) Use a custom credential store instead of the default store (~/.thelma/credentials/$key)
	CredentialStore stores.Store
}

type Credentials

type Credentials interface {
	// GetTokenProvider returns a TokenProvider for the given key, applying the given options if a new TokenProvider is
	// created to fulfill the request. If a TokenProvider already exists for the given key, it will be returned.
	// It's important for callers to be consistent with the options they pass in, at least for a given Thelma execution,
	// since the options are only used on the first call for a given key.
	//
	// The caching means that there will only ever be one TokenProvider for a given key, so the TokenProvider's
	// concurrency-safety guarantees will reliably apply (and the caller doesn't need to worry about caching the
	// response of this function).
	GetTokenProvider(key string, opts ...TokenOption) TokenProvider
}

func New

func New(thelmaConfig config.Config, thelmaRoot root.Root) (Credentials, error)

New returns a new Credentials instance using a directory store rooted at credentialsDir

func NewWithStore

func NewWithStore(store stores.Store) Credentials

NewWithStore returns a new Credentials instance backed by the given store

type MockTokenProvider

type MockTokenProvider struct {
	ReturnString string
	ReturnBytes  []byte
	ReturnNil    bool
	ReturnErr    bool
	FailIfCalled *testing.T
}

MockTokenProvider offers a TokenProvider that is as simple as possible to facilitate testing outside of this package.

func (*MockTokenProvider) Get

func (m *MockTokenProvider) Get() ([]byte, error)

func (*MockTokenProvider) Reissue

func (m *MockTokenProvider) Reissue() ([]byte, error)

type TokenOption

type TokenOption func(*TokenOptions)

TokenOption function for configuring a token's Options

type TokenOptions

type TokenOptions struct {
	BaseTokenOptions
	// ValidateFn (optional) Optional function for validating a token. If supplied, stored credentials will be validated before being returned to caller.
	// This function can be called quite frequently in Goroutine scenarios, so offline validation is ideal.
	ValidateFn func([]byte) error
	// RefreshFn (optional) Optional function for refreshing a token. Called if a stored credential turns out to be invalid. If an error is returned, IssueFn will be called to issue a new credential.
	RefreshFn func([]byte) ([]byte, error)
	// IssueFn (optional) Optional function for issuing a new token. If supplied, prompt options are ignored.
	IssueFn func() ([]byte, error)
	// contains filtered or unexported fields
}

TokenOptions configuration options for a TokenProvider

type TokenProvider

type TokenProvider interface {
	// Get provides a token value based on the configuration of the TokenProvider. The overall flow is as follows:
	//
	// 1. If a match for any TokenOptions.EnvVars is found, immediately return that value
	// 2. If a match for the key is found in the TokenOptions.CredentialStore:
	//    - If it is valid per TokenOptions.ValidateFn, return it
	//    - If it is invalid but TokenOptions.RefreshFn is provided, attempt to refresh the token and validate, store, and return it
	//      (errors from TokenOptions.RefreshFn will cause the flow to continue to step 3)
	// 3. If TokenOptions.IssueFn is provided, issue a new token and validate, store, and return it
	// 4. If TokenOptions.IssueFn isn't provided but TokenOptions.PromptEnabled is true and the session is interactive,
	//    prompt the user for a new token value and validate, store, and return it
	Get() ([]byte, error)
	// Reissue clears the state of the TokenProvider and then calls Get (which will usually then issue a new token).
	Reissue() ([]byte, error)
}

TokenProvider manages a token used for authentication, possibly stored on the local filesystem. The exported methods are Goroutine-safe.

func GetTypedTokenProvider

func GetTypedTokenProvider[T any](c Credentials, key string, options ...TypedTokenOption[T]) (TokenProvider, error)

GetTypedTokenProvider is like Credentials.GetTokenProvider but for TypedTokenOptions. Go's lackluster generics support prevents this method from actually being present on Credentials, so the receiver must be passed here.

type TypedTokenOption

type TypedTokenOption[T any] func(*TypedTokenOptions[T])

type TypedTokenOptions

type TypedTokenOptions[T any] struct {
	BaseTokenOptions

	// UnmarshalFromStoreFn (required) parses T from the BaseTokenOptions.CredentialStore.
	//
	// If you're trying to change the stored representation of a token, it's safe to just error here.
	// UnmarshalFromStoreFn and MarshalToStoreFn get baked into TokenOptions.ValidateFn and similar,
	// so if they return an error it'll be seen as a validation error (and so will fall through to
	// refreshing/issuing). In other words, you don't need to gracefully handle it.
	UnmarshalFromStoreFn func([]byte) (T, error)
	// MarshalToStoreFn (required) will be used to store T in the BaseTokenOptions.CredentialStore.
	MarshalToStoreFn func(T) ([]byte, error)

	// MarshalToReturnFn (optional) will be used to return T to the caller of TokenProvider.Get.
	// If omitted, MarshalToStoreFn will be used.
	MarshalToReturnFn func(T) ([]byte, error)

	// ValidateFn (optional) is like TokenOptions.ValidateFn, but for T.
	ValidateFn func(T) error
	// RefreshFn (optional) is like TokenOptions.RefreshFn, but for T.
	RefreshFn func(T) (T, error)
	// IssueFn (optional) is like TokenOptions.IssueFn, but for T.
	IssueFn func() (T, error)
}