import "github.com/aws/aws-sdk-go/aws/credentials"
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 := credentials.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 := credentials.NewCredentials(&ec2rolecreds.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 := credentials.NewCredentials(&MyProvider{})
credValue, err := creds.Get()
Deprecated: aws-sdk-go is deprecated. Use aws-sdk-go-v2. See https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-go-v1-on-july-31-2025/.
Index â¹ Index â¾chain_provider.go context_background_go1.7.go context_go1.9.go credentials.go env_provider.go shared_credentials_provider.go static_provider.go
Internal call graph â¹ Internal call graph â¾In the call graph viewer below, each node is a function belonging to this package and its children are the functions it calls—perhaps dynamically.
The root nodes are the entry points of the package: functions that may be called from outside the package. There may be non-exported or anonymous functions among them if they are called dynamically from another package.
Click a node to visit that function's source code. From there you can visit its callers by clicking its declaring func token.
Functions may be omitted if they were determined to be unreachable in the particular programs or tests that were analyzed.
const EnvProviderName = "EnvProvider"
EnvProviderName provides a name of Env provider
const SharedCredsProviderName = "SharedCredentialsProvider"
SharedCredsProviderName provides a name of SharedCreds provider
const StaticProviderName = "StaticProvider"
StaticProviderName provides a name of Static provider
Variables ¶var (
ErrAccessKeyIDNotFound = awserr.New("EnvAccessKeyNotFound", "AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY not found in environment", nil)
ErrSecretAccessKeyNotFound = awserr.New("EnvSecretNotFound", "AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY not found in environment", nil)
)
var AnonymousCredentials = NewStaticCredentials("", "", "")
AnonymousCredentials is 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(session.Must(session.NewSession(&aws.Config{
Credentials: credentials.AnonymousCredentials,
})))
// Access public S3 buckets.
var (
ErrNoValidProvidersFoundInChain = awserr.New("NoCredentialProviders",
`no valid providers in chain. Deprecated.
For verbose messaging see aws.Config.CredentialsChainVerboseErrors`,
nil)
)
var (
ErrSharedCredentialsHomeNotFound = awserr.New("UserHomeNotFound", "user home directory not found.", nil)
)
var (
ErrStaticCredentialsEmpty = awserr.New("EmptyStaticCreds", "static credentials are empty", nil)
)type ChainProvider ¶
type ChainProvider struct {
Providers []Provider
VerboseErrors bool
}
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 via 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 := credentials.NewChainCredentials(
[]credentials.Provider{
&credentials.EnvProvider{},
&ec2rolecreds.EC2RoleProvider{
Client: ec2metadata.New(sess),
},
})
// Usage of ChainCredentials with aws.Config
svc := ec2.New(session.Must(session.NewSession(&aws.Config{
Credentials: creds,
})))
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 Context ¶type Context = context.Context
Context is an alias of the Go stdlib's context.Context interface. It can be used within the SDK's API operation "WithContext" methods.
This type, aws.Context, and context.Context are equivalent.
See https://golang.org/pkg/context on how to use contexts.
type Credentials ¶type Credentials struct {
}
A Credentials provides concurrency 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 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. Token is only required for temporary security credentials retrieved via STS, otherwise an empty string can be passed for this parameter.
func NewStaticCredentialsFromCreds ¶func NewStaticCredentialsFromCreds(creds Value) *Credentials
NewStaticCredentialsFromCreds returns a pointer to a new Credentials object wrapping the static credentials value provide. Same as NewStaticCredentials but takes the creds Value instead of individual fields
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) ExpiresAt ¶func (c *Credentials) ExpiresAt() (time.Time, error)
ExpiresAt provides access to the functionality of the Expirer interface of the underlying Provider, if it supports that interface. Otherwise, it returns an error.
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) GetWithContext ¶func (c *Credentials) GetWithContext(ctx Context) (Value, error)
GetWithContext returns the credentials value, or error if the credentials Value failed to be retrieved. Will return early if the passed in context is canceled.
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.
Passed in Context is equivalent to aws.Context, and context.Context.
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 EnvProvider ¶type EnvProvider struct {
}
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 ErrorProvider ¶type ErrorProvider struct {
Err error
ProviderName string
}
An ErrorProvider is a stub credentials provider that always returns an error this is used by the SDK when construction a known provider is not possible due to an error.
func (ErrorProvider) IsExpired ¶func (p ErrorProvider) IsExpired() bool
IsExpired will always return not expired.
func (ErrorProvider) Retrieve ¶func (p ErrorProvider) Retrieve() (Value, error)
Retrieve will always return the error that the ErrorProvider was created with.
type Expirer ¶type Expirer interface {
ExpiresAt() time.Time
}
An Expirer is an interface that Providers can implement to expose the expiration time, if known. If the Provider cannot accurately provide this info, it should not implement this interface.
type Expiry ¶type Expiry struct {
CurrentTime func() time.Time
}
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 EC2RoleProvider struct {
Expiry
...
}
func (*Expiry) ExpiresAt ¶
func (e *Expiry) ExpiresAt() time.Time
ExpiresAt returns the expiration time of the credential
func (*Expiry) IsExpired ¶func (e *Expiry) IsExpired() bool
IsExpired returns if the credentials are expired.
func (*Expiry) SetExpiration ¶func (e *Expiry) SetExpiration(expiration time.Time, window time.Duration)
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 Provider ¶type Provider interface {
Retrieve() (Value, error)
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 ProviderWithContext ¶type ProviderWithContext interface {
Provider
RetrieveWithContext(Context) (Value, error)
}
ProviderWithContext is a Provider that can retrieve credentials with a Context
type SharedCredentialsProvider struct {
Filename string
Profile string
}
A SharedCredentialsProvider retrieves access key pair (access key ID, secret access key, and session token if present) 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 programmatically, 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 {
AccessKeyID string
SecretAccessKey string
SessionToken string
ProviderName string
}
A Value is the AWS credentials value for individual credential fields.
func (Value) HasKeys ¶func (v Value) HasKeys() bool
HasKeys returns if the credentials Value has both AccessKeyID and SecretAccessKey value set.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4