1 // Package credentials provides credential retrieval and management
3 // The Credentials is the primary method of getting access to and managing
4 // credentials Values. Using dependency injection retrieval of the credential
5 // values is handled by a object which satisfies the Provider interface.
7 // By default the Credentials.Get() will cache the successful result of a
8 // Provider's Retrieve() until Provider.IsExpired() returns true. At which
9 // point Credentials will call Provider's Retrieve() to get new credential Value.
11 // The Provider is responsible for determining when credentials Value have expired.
12 // It is also important to note that Credentials will always call Retrieve the
13 // first time Credentials.Get() is called.
15 // Example of using the environment variable credentials.
17 // creds := credentials.NewEnvCredentials()
19 // // Retrieve the credentials value
20 // credValue, err := creds.Get()
25 // Example of forcing credentials to expire and be refreshed on the next Get().
26 // This may be helpful to proactively expire credentials and refresh them sooner
27 // than they would naturally expire on their own.
29 // creds := credentials.NewCredentials(&ec2rolecreds.EC2RoleProvider{})
31 // credsValue, err := creds.Get()
32 // // New credentials will be retrieved instead of from cache.
37 // Each Provider built into this package also provides a helper method to generate
38 // a Credentials pointer setup with the provider. To use a custom Provider just
39 // create a type which satisfies the Provider interface and pass it to the
40 // NewCredentials method.
42 // type MyProvider struct{}
43 // func (m *MyProvider) Retrieve() (Value, error) {...}
44 // func (m *MyProvider) IsExpired() bool {...}
46 // creds := credentials.NewCredentials(&MyProvider{})
47 // credValue, err := creds.Get()
56 // AnonymousCredentials is an empty Credential object that can be used as
57 // dummy placeholder credentials for requests that do not need signed.
59 // This Credentials can be used to configure a service to not sign requests
60 // when making service API calls. For example, when accessing public
63 // svc := s3.New(session.Must(session.NewSession(&aws.Config{
64 // Credentials: credentials.AnonymousCredentials,
66 // // Access public S3 buckets.
69 var AnonymousCredentials = NewStaticCredentials("", "", "")
71 // A Value is the AWS credentials value for individual credential fields.
76 // AWS Secret Access Key
77 SecretAccessKey string
82 // Provider used to get credentials
86 // A Provider is the interface for any component which will provide credentials
87 // Value. A provider is required to manage its own Expired state, and what to
90 // The Provider should not need to implement its own mutexes, because
91 // that will be managed by Credentials.
92 type Provider interface {
93 // Retrieve returns nil if it successfully retrieved the value.
94 // Error is returned if the value were not obtainable, or empty.
95 Retrieve() (Value, error)
97 // IsExpired returns if the credentials are no longer valid, and need
102 // An ErrorProvider is a stub credentials provider that always returns an error
103 // this is used by the SDK when construction a known provider is not possible
105 type ErrorProvider struct {
106 // The error to be returned from Retrieve
109 // The provider name to set on the Retrieved returned Value
113 // Retrieve will always return the error that the ErrorProvider was created with.
114 func (p ErrorProvider) Retrieve() (Value, error) {
115 return Value{ProviderName: p.ProviderName}, p.Err
118 // IsExpired will always return not expired.
119 func (p ErrorProvider) IsExpired() bool {
123 // A Expiry provides shared expiration logic to be used by credentials
124 // providers to implement expiry functionality.
126 // The best method to use this struct is as an anonymous field within the
127 // provider's struct.
130 // type EC2RoleProvider struct {
135 // The date/time when to expire on
138 // If set will be used by IsExpired to determine the current time.
139 // Defaults to time.Now if CurrentTime is not set. Available for testing
140 // to be able to mock out the current time.
141 CurrentTime func() time.Time
144 // SetExpiration sets the expiration IsExpired will check when called.
146 // If window is greater than 0 the expiration time will be reduced by the
149 // Using a window is helpful to trigger credentials to expire sooner than
150 // the expiration time given to ensure no requests are made with expired
152 func (e *Expiry) SetExpiration(expiration time.Time, window time.Duration) {
153 e.expiration = expiration
155 e.expiration = e.expiration.Add(-window)
159 // IsExpired returns if the credentials are expired.
160 func (e *Expiry) IsExpired() bool {
161 if e.CurrentTime == nil {
162 e.CurrentTime = time.Now
164 return e.expiration.Before(e.CurrentTime())
167 // A Credentials provides synchronous safe retrieval of AWS credentials Value.
168 // Credentials will cache the credentials value until they expire. Once the value
169 // expires the next Get will attempt to retrieve valid credentials.
171 // Credentials is safe to use across multiple goroutines and will manage the
172 // synchronous state so the Providers do not need to implement their own
175 // The first Credentials.Get() will always call Provider.Retrieve() to get the
176 // first instance of the credentials Value. All calls to Get() after that
177 // will return the cached credentials Value until IsExpired() returns true.
178 type Credentials struct {
186 // NewCredentials returns a pointer to a new Credentials with the provider set.
187 func NewCredentials(provider Provider) *Credentials {
194 // Get returns the credentials value, or error if the credentials Value failed
197 // Will return the cached credentials Value if it has not expired. If the
198 // credentials Value has expired the Provider's Retrieve() will be called
199 // to refresh the credentials.
201 // If Credentials.Expire() was called the credentials Value will be force
202 // expired, and the next call to Get() will cause them to be refreshed.
203 func (c *Credentials) Get() (Value, error) {
208 creds, err := c.provider.Retrieve()
213 c.forceRefresh = false
219 // Expire expires the credentials and forces them to be retrieved on the
220 // next call to Get().
222 // This will override the Provider's expired state, and force Credentials
223 // to call the Provider's Retrieve().
224 func (c *Credentials) Expire() {
228 c.forceRefresh = true
231 // IsExpired returns if the credentials are no longer valid, and need
234 // If the Credentials were forced to be expired with Expire() this will
235 // reflect that override.
236 func (c *Credentials) IsExpired() bool {
243 // isExpired helper method wrapping the definition of expired credentials.
244 func (c *Credentials) isExpired() bool {
245 return c.forceRefresh || c.provider.IsExpired()