credentials

package
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 7, 2024 License: Apache-2.0 Imports: 12 Imported by: 28

Documentation

Overview

Package credentials provides credential retrieval and management

The Credentials is the primary method of getting access to and managing credentials Values. Using dependency injection retrieval of the credential values is handled by a object which satisfies the Provider interface.

By default the Credentials.Get() will cache the successful result of a Provider's Retrieve() until Provider.IsExpired() returns true. At which point Credentials will call Provider's Retrieve() to get new credential Value.

The Provider is responsible for determining when credentials Value have expired. It is also important to note that Credentials will always call Retrieve the first time Credentials.Get() is called.

Example of using the environment variable credentials. 

creds := NewEnvCredentials()

// Retrieve the credentials value
credValue, err := creds.Get()
if err != nil {
    // handle error
}

Example of forcing credentials to expire and be refreshed on the next Get(). This may be helpful to proactively expire credentials and refresh them sooner than they would naturally expire on their own. 

creds := NewCredentials(&EC2RoleProvider{})
creds.Expire()
credsValue, err := creds.Get()
// New credentials will be retrieved instead of from cache.

Custom Provider

Each Provider built into this package also provides a helper method to generate a Credentials pointer setup with the provider. To use a custom Provider just create a type which satisfies the Provider interface and pass it to the NewCredentials method. 

type MyProvider struct{}
func (m *MyProvider) Retrieve() (Value, error) {...}
func (m *MyProvider) IsExpired() bool {...}

creds := NewCredentials(&MyProvider{})
credValue, err := creds.Get()

Package ini provides functions for parsing INI configuration files.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrAccessKeyIDNotFound is returned when the AWS Access Key ID can't be
	// found in the process's environment.
	ErrAccessKeyIDNotFound = apierr.New("EnvAccessKeyNotFound", "AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY not found in environment", nil)
	// ErrSecretAccessKeyNotFound is returned when the AWS Secret Access Key
	// can't be found in the process's environment.
	ErrSecretAccessKeyNotFound = apierr.New("EnvSecretNotFound", "AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY not found in environment", nil)
)
View Source 
var AnonymousCredentials = NewStaticCredentials("", "", "")

Create an empty Credential object that can be used as dummy placeholder credentials for requests that do not need signed.

This Credentials can be used to configure a service to not sign requests when making service API calls. For example, when accessing public s3 buckets. 

svc := s3.New(&aws.Config{Credentials: AnonymousCredentials})
// Access public S3 buckets.
View Source 
var (
	// ErrNoValidProvidersFoundInChain Is returned when there are no valid
	// providers in the ChainProvider.
	ErrNoValidProvidersFoundInChain = apierr.New("NoCredentialProviders", "no valid providers in chain", nil)
)
View Source 
var (
	// ErrSharedCredentialsHomeNotFound is emitted when the user directory cannot be found.
	ErrSharedCredentialsHomeNotFound = apierr.New("UserHomeNotFound", "user home directory not found.", nil)
)
View Source 
var (
	// ErrStaticCredentialsEmpty is emitted when static credentials are empty.
	ErrStaticCredentialsEmpty = apierr.New("EmptyStaticCreds", "static credentials are empty", nil)
)

Functions

This section is empty.

Types

type ChainProvider 

type ChainProvider struct {
	Providers []Provider
	// contains filtered or unexported fields
}

A ChainProvider will search for a provider which returns credentials and cache that provider until Retrieve is called again.

The ChainProvider provides a way of chaining multiple providers together which will pick the first available using priority order of the Providers in the list.

If none of the Providers retrieve valid credentials Value, ChainProvider's Retrieve() will return the error ErrNoValidProvidersFoundInChain.

If a Provider is found which returns valid credentials Value ChainProvider will cache that Provider for all calls to IsExpired(), until Retrieve is called again.

Example of ChainProvider to be used with an EnvProvider and EC2RoleProvider. In this example EnvProvider will first check if any credentials are available vai the environment variables. If there are none ChainProvider will check the next Provider in the list, EC2RoleProvider in this case. If EC2RoleProvider does not return any credentials ChainProvider will return the error ErrNoValidProvidersFoundInChain 

creds := NewChainCredentials(
    []Provider{
        &EnvProvider{},
        &EC2RoleProvider{},
    })
creds.Retrieve()

func (*ChainProvider) IsExpired 

func (c *ChainProvider) IsExpired() bool

IsExpired will returned the expired state of the currently cached provider if there is one. If there is no current provider, true will be returned.

func (*ChainProvider) Retrieve 

func (c *ChainProvider) Retrieve() (Value, error)

Retrieve returns the credentials value or error if no provider returned without error.

If a provider is found it will be cached and any calls to IsExpired() will return the expired state of the cached provider.

type Credentials 

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

A Credentials provides synchronous safe retrieval of AWS credentials Value. Credentials will cache the credentials value until they expire. Once the value expires the next Get will attempt to retrieve valid credentials.

Credentials is safe to use across multiple goroutines and will manage the synchronous state so the Providers do not need to implement their own synchronization.

The first Credentials.Get() will always call Provider.Retrieve() to get the first instance of the credentials Value. All calls to Get() after that will return the cached credentials Value until IsExpired() returns true.

func NewChainCredentials 

func NewChainCredentials(providers []Provider) *Credentials

NewChainCredentials returns a pointer to a new Credentials object wrapping a chain of providers.

func NewCredentials 

func NewCredentials(provider Provider) *Credentials

NewCredentials returns a pointer to a new Credentials with the provider set.

func NewEC2RoleCredentials 

func NewEC2RoleCredentials(client *http.Client, endpoint string, window time.Duration) *Credentials

NewEC2RoleCredentials returns a pointer to a new Credentials object wrapping the EC2RoleProvider.

Takes a custom http.Client which can be configured for custom handling of things such as timeout.

Endpoint is the URL that the EC2RoleProvider will connect to when retrieving role and credentials.

Window is the expiry window that will be subtracted from the expiry returned by the role credential request. This is done so that the credentials will expire sooner than their actual lifespan.

func NewEnvCredentials 

func NewEnvCredentials() *Credentials

NewEnvCredentials returns a pointer to a new Credentials object wrapping the environment variable provider.

func NewSharedCredentials 

func NewSharedCredentials(filename, profile string) *Credentials

NewSharedCredentials returns a pointer to a new Credentials object wrapping the Profile file provider.

func NewStaticCredentials 

func NewStaticCredentials(id, secret, token string) *Credentials

NewStaticCredentials returns a pointer to a new Credentials object wrapping a static credentials value provider.

func (*Credentials) Expire 

func (c *Credentials) Expire()

Expire expires the credentials and forces them to be retrieved on the next call to Get().

This will override the Provider's expired state, and force Credentials to call the Provider's Retrieve().

func (*Credentials) Get 

func (c *Credentials) Get() (Value, error)

Get returns the credentials value, or error if the credentials Value failed to be retrieved.

Will return the cached credentials Value if it has not expired. If the credentials Value has expired the Provider's Retrieve() will be called to refresh the credentials.

If Credentials.Expire() was called the credentials Value will be force expired, and the next call to Get() will cause them to be refreshed.

func (*Credentials) IsExpired 

func (c *Credentials) IsExpired() bool

IsExpired returns if the credentials are no longer valid, and need to be retrieved.

If the Credentials were forced to be expired with Expire() this will reflect that override.

type EC2RoleProvider 

type EC2RoleProvider struct {
	// Endpoint must be fully quantified URL
	Endpoint string

	// HTTP client to use when connecting to EC2 service
	Client *http.Client

	// ExpiryWindow will allow the credentials to trigger refreshing prior to
	// the credentials actually expiring. This is beneficial so race conditions
	// with expiring credentials do not cause request to fail unexpectedly
	// due to ExpiredTokenException exceptions.
	//
	// So a ExpiryWindow of 10s would cause calls to IsExpired() to return true
	// 10 seconds before the credentials are actually expired.
	//
	// If ExpiryWindow is 0 or less it will be ignored.
	ExpiryWindow time.Duration
	// contains filtered or unexported fields
}

A EC2RoleProvider retrieves credentials from the EC2 service, and keeps track if those credentials are expired.

Example how to configure the EC2RoleProvider with custom http Client, Endpoint or ExpiryWindow 

p := &credentials.EC2RoleProvider{
    // Pass in a custom timeout to be used when requesting
    // IAM EC2 Role credentials.
    Client: &http.Client{
        Timeout: 10 * time.Second,
    },
    // Use default EC2 Role metadata endpoint, Alternate endpoints can be
    // specified setting Endpoint to something else.
    Endpoint: "",
    // Do not use early expiry of credentials. If a non zero value is
    // specified the credentials will be expired early
    ExpiryWindow: 0,
}

func (*EC2RoleProvider) IsExpired 

func (m *EC2RoleProvider) IsExpired() bool

IsExpired returns if the credentials are expired.

func (*EC2RoleProvider) Retrieve 

func (m *EC2RoleProvider) Retrieve() (Value, error)

Retrieve retrieves credentials from the EC2 service. Error will be returned if the request fails, or unable to extract the desired credentials.

type EnvProvider 

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

A EnvProvider retrieves credentials from the environment variables of the running process. Environment credentials never expire.

Environment variables used: - Access Key ID: AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY - Secret Access Key: AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY

func (*EnvProvider) IsExpired 

func (e *EnvProvider) IsExpired() bool

IsExpired returns if the credentials have been retrieved.

func (*EnvProvider) Retrieve 

func (e *EnvProvider) Retrieve() (Value, error)

Retrieve retrieves the keys from the environment.

type ErrSyntax 

type ErrSyntax struct {
	Line   int
	Source string // The contents of the erroneous line, without leading or trailing whitespace
}

ErrSyntax is returned when there is a syntax error in an INI file.

func (ErrSyntax) Error 

func (e ErrSyntax) Error() string

type File 

type File map[string]Section

A File represents a parsed INI file.

func Load 

func Load(in io.Reader) (File, error)

Loads and returns a File from a reader.

func LoadFile 

func LoadFile(filename string) (File, error)

Loads and returns an INI File from a file on disk.

func (File) Get 

func (f File) Get(section, key string) (value string, ok bool)

Looks up a value for a key in a section and returns that value, along with a boolean result similar to a map lookup.

func (File) Load 

func (f File) Load(in io.Reader) (err error)

Loads INI data from a reader and stores the data in the File.

func (File) LoadFile 

func (f File) LoadFile(file string) (err error)

Loads INI data from a named file and stores the data in the File.

func (File) Section 

func (f File) Section(name string) Section

Returns a named Section. A Section will be created if one does not already exist for the given name.

type Provider 

type Provider interface {
	// Refresh returns nil if it successfully retrieved the value.
	// Error is returned if the value were not obtainable, or empty.
	Retrieve() (Value, error)

	// IsExpired returns if the credentials are no longer valid, and need
	// to be retrieved.
	IsExpired() bool
}

A Provider is the interface for any component which will provide credentials Value. A provider is required to manage its own Expired state, and what to be expired means.

The Provider should not need to implement its own mutexes, because that will be managed by Credentials.

type Section 

type Section map[string]string

A Section represents a single section of an INI file.

type SharedCredentialsProvider 

type SharedCredentialsProvider struct {
	// Path to the shared credentials file. If empty will default to current user's
	// home directory.
	Filename string

	// AWS Profile to extract credentials from the shared credentials file. If empty
	// will default to environment variable "AWS_PROFILE" or "default" if
	// environment variable is also not set.
	Profile string
	// contains filtered or unexported fields
}

A SharedCredentialsProvider retrieves credentials from the current user's home directory, and keeps track if those credentials are expired.

Profile ini file example: $HOME/.aws/credentials

func (*SharedCredentialsProvider) IsExpired 

func (p *SharedCredentialsProvider) IsExpired() bool

IsExpired returns if the shared credentials have expired.

func (*SharedCredentialsProvider) Retrieve 

func (p *SharedCredentialsProvider) Retrieve() (Value, error)

Retrieve reads and extracts the shared credentials from the current users home directory.

type StaticProvider 

type StaticProvider struct {
	Value
}

A StaticProvider is a set of credentials which are set pragmatically, and will never expire.

func (*StaticProvider) IsExpired 

func (s *StaticProvider) IsExpired() bool

IsExpired returns if the credentials are expired.

For StaticProvider, the credentials never expired.

func (*StaticProvider) Retrieve 

func (s *StaticProvider) Retrieve() (Value, error)

Retrieve returns the credentials or error if the credentials are invalid.

type Value 

type Value struct {
	// AWS Access key ID
	AccessKeyID string

	// AWS Secret Access Key
	SecretAccessKey string

	// AWS Session Token
	SessionToken string
}

A Value is the AWS credentials value for individual credential fields.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.