Documentation
¶
Overview ¶
Package credentials provides credential retrieval and management for S3 compatible object storage.
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 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 := NewFromEnv()
// 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 := NewFromIAM("")
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()
Index ¶
- Constants
- type Chain
- type Credentials
- func New(provider Provider) *Credentials
- func NewChainCredentials(providers []Provider) *Credentials
- func NewEnvAWS() *Credentials
- func NewEnvMinio() *Credentials
- func NewFileAWSCredentials(filename string, profile string) *Credentials
- func NewFileMinioClient(filename string, alias string) *Credentials
- func NewIAM(endpoint string) *Credentials
- func NewStatic(id, secret, token string, signerType SignatureType) *Credentials
- func NewStaticV2(id, secret, token string) *Credentials
- func NewStaticV4(id, secret, token string) *Credentials
- type EnvAWS
- type EnvMinio
- type Expiry
- type FileAWSCredentials
- type FileMinioClient
- type IAM
- type Provider
- type SignatureType
- type Static
- type Value
Constants ¶
const DefaultExpiryWindow = time.Second * 10 // 10 secs
DefaultExpiryWindow - Default expiry window. 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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Chain ¶
type Chain struct {
Providers []Provider
// contains filtered or unexported fields
}
A Chain will search for a provider which returns credentials and cache that provider until Retrieve is called again.
The Chain 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, collecting all errors from all providers.
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.
creds := credentials.NewChainCredentials(
[]credentials.Provider{
&credentials.EnvAWSS3{},
&credentials.EnvMinio{},
})
// Usage of ChainCredentials.
mc, err := minio.NewWithCredentials(endpoint, creds, secure, "us-east-1")
if err != nil {
log.Fatalln(err)
}
type Credentials ¶
Credentials - A container for synchronous safe retrieval of 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 New ¶
func New(provider Provider) *Credentials
New returns a pointer to a new Credentials with the provider set.
func NewChainCredentials ¶
func NewChainCredentials(providers []Provider) *Credentials
NewChainCredentials returns a pointer to a new Credentials object wrapping a chain of providers.
func NewEnvAWS ¶
func NewEnvAWS() *Credentials
NewEnvAWS returns a pointer to a new Credentials object wrapping the environment variable provider.
func NewEnvMinio ¶
func NewEnvMinio() *Credentials
NewEnvMinio returns a pointer to a new Credentials object wrapping the environment variable provider.
func NewFileAWSCredentials ¶
func NewFileAWSCredentials(filename string, profile string) *Credentials
NewFileAWSCredentials returns a pointer to a new Credentials object wrapping the Profile file provider.
func NewFileMinioClient ¶
func NewFileMinioClient(filename string, alias string) *Credentials
NewFileMinioClient returns a pointer to a new Credentials object wrapping the Alias file provider.
func NewIAM ¶
func NewIAM(endpoint string) *Credentials
NewIAM returns a pointer to a new Credentials object wrapping the IAM. Takes a ConfigProvider to create a EC2Metadata client. The ConfigProvider is satisfied by the session.Session type.
func NewStatic ¶
func NewStatic(id, secret, token string, signerType SignatureType) *Credentials
NewStatic returns a pointer to a new Credentials object wrapping a static credentials value provider.
func NewStaticV2 ¶
func NewStaticV2(id, secret, token string) *Credentials
NewStaticV2 returns a pointer to a new Credentials object wrapping a static credentials value provider, signature is set to v2. If access and secret are not specified then regardless of signature type set it Value will return as anonymous.
func NewStaticV4 ¶
func NewStaticV4(id, secret, token string) *Credentials
NewStaticV4 is similar to NewStaticV2 with similar considerations.
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 refreshed.
If the Credentials were forced to be expired with Expire() this will reflect that override.
type EnvAWS ¶
type EnvAWS struct {
// contains filtered or unexported fields
}
A EnvAWS retrieves credentials from the environment variables of the running process. EnvAWSironment credentials never expire.
EnvAWSironment variables used:
* Access Key ID: AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY. * Secret Access Key: AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY. * Secret Token: AWS_SESSION_TOKEN.
type EnvMinio ¶
type EnvMinio struct {
// contains filtered or unexported fields
}
A EnvMinio retrieves credentials from the environment variables of the running process. EnvMinioironment credentials never expire.
EnvMinioironment variables used:
* Access Key ID: MINIO_ACCESS_KEY. * Secret Access Key: MINIO_SECRET_KEY.
type Expiry ¶
type Expiry struct {
// If set will be used by IsExpired to determine the current time.
// Defaults to time.Now if CurrentTime is not set.
CurrentTime func() time.Time
// contains filtered or unexported fields
}
A Expiry provides shared expiration logic to be used by credentials providers to implement expiry functionality.
The best method to use this struct is as an anonymous field within the provider's struct.
Example:
type IAMCredentialProvider struct {
Expiry
...
}
func (*Expiry) SetExpiration ¶
SetExpiration sets the expiration IsExpired will check when called.
If window is greater than 0 the expiration time will be reduced by the window value.
Using a window is helpful to trigger credentials to expire sooner than the expiration time given to ensure no requests are made with expired tokens.
type FileAWSCredentials ¶
type FileAWSCredentials struct {
// contains filtered or unexported fields
}
A FileAWSCredentials 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 (*FileAWSCredentials) IsExpired ¶
func (p *FileAWSCredentials) IsExpired() bool
IsExpired returns if the shared credentials have expired.
func (*FileAWSCredentials) Retrieve ¶
func (p *FileAWSCredentials) Retrieve() (Value, error)
Retrieve reads and extracts the shared credentials from the current users home directory.
type FileMinioClient ¶
type FileMinioClient struct {
// contains filtered or unexported fields
}
A FileMinioClient retrieves credentials from the current user's home directory, and keeps track if those credentials are expired.
Configuration file example: $HOME/.mc/config.json
func (*FileMinioClient) IsExpired ¶
func (p *FileMinioClient) IsExpired() bool
IsExpired returns if the shared credentials have expired.
func (*FileMinioClient) Retrieve ¶
func (p *FileMinioClient) Retrieve() (Value, error)
Retrieve reads and extracts the shared credentials from the current users home directory.
type IAM ¶
type IAM struct {
Expiry
// Required http Client to use when connecting to IAM metadata service.
Client *http.Client
// contains filtered or unexported fields
}
A IAM retrieves credentials from the EC2 service, and keeps track if those credentials are expired.
type Provider ¶
type Provider interface {
// Retrieve 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.
type SignatureType ¶
type SignatureType int
SignatureType is type of Authorization requested for a given HTTP request.
const ( // SignatureDefault is always set to v4. SignatureDefault SignatureType = iota SignatureV4 SignatureV2 SignatureV4Streaming SignatureAnonymous // Anonymous signature signifies, no signature. )
Different types of supported signatures - default is SignatureV4 or SignatureDefault.
func (SignatureType) IsAnonymous ¶
func (s SignatureType) IsAnonymous() bool
IsAnonymous - is signature empty?
func (SignatureType) IsStreamingV4 ¶
func (s SignatureType) IsStreamingV4() bool
IsStreamingV4 - is signature SignatureV4Streaming?
func (SignatureType) String ¶
func (s SignatureType) String() string
Stringer humanized version of signature type, strings returned here are case insensitive.
Source Files