credentials

package
v7.0.28 Latest Latest
Warning

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

Go to latest
Published: Apr 13, 2021 License: Apache-2.0 Imports: 23 Imported by: 0

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

View Source
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 AssumeRoleResponse

type AssumeRoleResponse struct {
	XMLName xml.Name `xml:"https://sts.amazonaws.com/doc/2011-06-15/ AssumeRoleResponse" json:"-"`

	Result           AssumeRoleResult `xml:"AssumeRoleResult"`
	ResponseMetadata struct {
		RequestID string `xml:"RequestId,omitempty"`
	} `xml:"ResponseMetadata,omitempty"`
}

AssumeRoleResponse contains the result of successful AssumeRole request.

type AssumeRoleResult

type AssumeRoleResult struct {
	// The identifiers for the temporary security credentials that the operation
	// returns.
	AssumedRoleUser AssumedRoleUser `xml:",omitempty"`

	// The temporary security credentials, which include an access key ID, a secret
	// access key, and a security (or session) token.
	//
	// Note: The size of the security token that STS APIs return is not fixed. We
	// strongly recommend that you make no assumptions about the maximum size. As
	// of this writing, the typical size is less than 4096 bytes, but that can vary.
	// Also, future updates to AWS might require larger sizes.
	Credentials struct {
		AccessKey    string    `xml:"AccessKeyId" json:"accessKey,omitempty"`
		SecretKey    string    `xml:"SecretAccessKey" json:"secretKey,omitempty"`
		Expiration   time.Time `xml:"Expiration" json:"expiration,omitempty"`
		SessionToken string    `xml:"SessionToken" json:"sessionToken,omitempty"`
	} `xml:",omitempty"`

	// A percentage value that indicates the size of the policy in packed form.
	// The service rejects any policy with a packed size greater than 100 percent,
	// which means the policy exceeded the allowed space.
	PackedPolicySize int `xml:",omitempty"`
}

AssumeRoleResult - Contains the response to a successful AssumeRole request, including temporary credentials that can be used to make MinIO API requests.

type AssumeRoleWithClientGrantsResponse

type AssumeRoleWithClientGrantsResponse struct {
	XMLName          xml.Name           `xml:"https://sts.amazonaws.com/doc/2011-06-15/ AssumeRoleWithClientGrantsResponse" json:"-"`
	Result           ClientGrantsResult `xml:"AssumeRoleWithClientGrantsResult"`
	ResponseMetadata struct {
		RequestID string `xml:"RequestId,omitempty"`
	} `xml:"ResponseMetadata,omitempty"`
}

AssumeRoleWithClientGrantsResponse contains the result of successful AssumeRoleWithClientGrants request.

type AssumeRoleWithLDAPResponse

type AssumeRoleWithLDAPResponse struct {
	XMLName          xml.Name           `xml:"https://sts.amazonaws.com/doc/2011-06-15/ AssumeRoleWithLDAPIdentityResponse" json:"-"`
	Result           LDAPIdentityResult `xml:"AssumeRoleWithLDAPIdentityResult"`
	ResponseMetadata struct {
		RequestID string `xml:"RequestId,omitempty"`
	} `xml:"ResponseMetadata,omitempty"`
}

AssumeRoleWithLDAPResponse contains the result of successful AssumeRoleWithLDAPIdentity request

type AssumeRoleWithWebIdentityResponse

type AssumeRoleWithWebIdentityResponse struct {
	XMLName          xml.Name          `xml:"https://sts.amazonaws.com/doc/2011-06-15/ AssumeRoleWithWebIdentityResponse" json:"-"`
	Result           WebIdentityResult `xml:"AssumeRoleWithWebIdentityResult"`
	ResponseMetadata struct {
		RequestID string `xml:"RequestId,omitempty"`
	} `xml:"ResponseMetadata,omitempty"`
}

AssumeRoleWithWebIdentityResponse contains the result of successful AssumeRoleWithWebIdentity request.

type AssumedRoleUser

type AssumedRoleUser struct {
	Arn           string
	AssumedRoleID string `xml:"AssumeRoleId"`
}

AssumedRoleUser - The identifiers for the temporary security credentials that the operation returns. Please also see https://docs.aws.amazon.com/goto/WebAPI/sts-2011-06-15/AssumedRoleUser

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 no credentials value.

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 after IsExpired() is true.

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)
}

func (*Chain) IsExpired

func (c *Chain) 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 (*Chain) Retrieve

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

Retrieve returns the credentials value, returns no credentials(anonymous) if no credentials provider returned any value.

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

type ClientGrantsResult

type ClientGrantsResult struct {
	AssumedRoleUser AssumedRoleUser `xml:",omitempty"`
	Audience        string          `xml:",omitempty"`
	Credentials     struct {
		AccessKey    string    `xml:"AccessKeyId" json:"accessKey,omitempty"`
		SecretKey    string    `xml:"SecretAccessKey" json:"secretKey,omitempty"`
		Expiration   time.Time `xml:"Expiration" json:"expiration,omitempty"`
		SessionToken string    `xml:"SessionToken" json:"sessionToken,omitempty"`
	} `xml:",omitempty"`
	PackedPolicySize             int    `xml:",omitempty"`
	Provider                     string `xml:",omitempty"`
	SubjectFromClientGrantsToken string `xml:",omitempty"`
}

ClientGrantsResult - Contains the response to a successful AssumeRoleWithClientGrants request, including temporary credentials that can be used to make MinIO API requests.

type ClientGrantsToken

type ClientGrantsToken struct {
	Token  string
	Expiry int
}

ClientGrantsToken - client grants token with expiry.

type Credentials

type Credentials struct {
	sync.Mutex
	// contains filtered or unexported fields
}

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.

func NewLDAPIdentity

func NewLDAPIdentity(stsEndpoint, ldapUsername, ldapPassword string) (*Credentials, error)

NewLDAPIdentity returns new credentials object that uses LDAP Identity.

func NewSTSAssumeRole

func NewSTSAssumeRole(stsEndpoint string, opts STSAssumeRoleOptions) (*Credentials, error)

NewSTSAssumeRole returns a pointer to a new Credentials object wrapping the STSAssumeRole.

func NewSTSClientGrants

func NewSTSClientGrants(stsEndpoint string, getClientGrantsTokenExpiry func() (*ClientGrantsToken, error)) (*Credentials, error)

NewSTSClientGrants returns a pointer to a new Credentials object wrapping the STSClientGrants.

func NewSTSWebIdentity

func NewSTSWebIdentity(stsEndpoint string, getWebIDTokenExpiry func() (*WebIdentityToken, error)) (*Credentials, error)

NewSTSWebIdentity returns a pointer to a new Credentials object wrapping the STSWebIdentity.

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.

func (*EnvAWS) IsExpired

func (e *EnvAWS) IsExpired() bool

IsExpired returns if the credentials have been retrieved.

func (*EnvAWS) Retrieve

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

Retrieve retrieves the keys from the environment.

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.

func (*EnvMinio) IsExpired

func (e *EnvMinio) IsExpired() bool

IsExpired returns if the credentials have been retrieved.

func (*EnvMinio) Retrieve

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

Retrieve retrieves the keys from the environment.

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) 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 FileAWSCredentials

type FileAWSCredentials struct {
	// Path to the shared credentials file.
	//
	// If empty will look for "AWS_SHARED_CREDENTIALS_FILE" env variable. If the
	// env value is empty will default to current user's home directory.
	// Linux/OSX: "$HOME/.aws/credentials"
	// Windows:   "%USERPROFILE%\.aws\credentials"
	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 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 {
	// Path to the shared credentials file.
	//
	// If empty will look for "MINIO_SHARED_CREDENTIALS_FILE" env variable. If the
	// env value is empty will default to current user's home directory.
	// Linux/OSX: "$HOME/.mc/config.json"
	// Windows:   "%USERALIAS%\mc\config.json"
	Filename string

	// MinIO Alias to extract credentials from the shared credentials file. If empty
	// will default to environment variable "MINIO_ALIAS" or "default" if
	// environment variable is also not set.
	Alias string
	// 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.

func (*IAM) Retrieve

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

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

type LDAPIdentity

type LDAPIdentity struct {
	Expiry
	// contains filtered or unexported fields
}

LDAPIdentity retrieves credentials from MinIO

func (*LDAPIdentity) Retrieve

func (k *LDAPIdentity) Retrieve() (value Value, err error)

Retrieve gets the credential by calling the MinIO STS API for LDAP on the configured stsEndpoint.

type LDAPIdentityResult

type LDAPIdentityResult struct {
	Credentials struct {
		AccessKey    string    `xml:"AccessKeyId" json:"accessKey,omitempty"`
		SecretKey    string    `xml:"SecretAccessKey" json:"secretKey,omitempty"`
		Expiration   time.Time `xml:"Expiration" json:"expiration,omitempty"`
		SessionToken string    `xml:"SessionToken" json:"sessionToken,omitempty"`
	} `xml:",omitempty"`

	SubjectFromToken string `xml:",omitempty"`
}

LDAPIdentityResult - contains credentials for a successful AssumeRoleWithLDAPIdentity request.

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 STSAssumeRole

type STSAssumeRole struct {
	Expiry

	// Required http Client to use when connecting to MinIO STS service.
	Client *http.Client

	// STS endpoint to fetch STS credentials.
	STSEndpoint string

	// various options for this request.
	Options STSAssumeRoleOptions
}

A STSAssumeRole retrieves credentials from MinIO service, and keeps track if those credentials are expired.

func (*STSAssumeRole) Retrieve

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

Retrieve retrieves credentials from the MinIO service. Error will be returned if the request fails.

type STSAssumeRoleOptions

type STSAssumeRoleOptions struct {
	// Mandatory inputs.
	AccessKey string
	SecretKey string

	Location        string // Optional commonly needed with AWS STS.
	DurationSeconds int    // Optional defaults to 1 hour.

	// Optional only valid if using with AWS STS
	RoleARN         string
	RoleSessionName string
}

STSAssumeRoleOptions collection of various input options to obtain AssumeRole credentials.

type STSClientGrants

type STSClientGrants struct {
	Expiry

	// Required http Client to use when connecting to MinIO STS service.
	Client *http.Client
	// contains filtered or unexported fields
}

A STSClientGrants retrieves credentials from MinIO service, and keeps track if those credentials are expired.

func (*STSClientGrants) Retrieve

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

Retrieve retrieves credentials from the MinIO service. Error will be returned if the request fails.

type STSWebIdentity

type STSWebIdentity struct {
	Expiry

	// Required http Client to use when connecting to MinIO STS service.
	Client *http.Client
	// contains filtered or unexported fields
}

A STSWebIdentity retrieves credentials from MinIO service, and keeps track if those credentials are expired.

func (*STSWebIdentity) Expiration

func (m *STSWebIdentity) Expiration() time.Time

Expiration returns the expiration time of the credentials

func (*STSWebIdentity) Retrieve

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

Retrieve retrieves credentials from the MinIO service. Error will be returned if the request fails.

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) IsV2

func (s SignatureType) IsV2() bool

IsV2 - is signature SignatureV2?

func (SignatureType) IsV4

func (s SignatureType) IsV4() bool

IsV4 - is signature SignatureV4?

func (SignatureType) String

func (s SignatureType) String() string

Stringer humanized version of signature type, strings returned here are case insensitive.

type Static

type Static struct {
	Value
}

A Static is a set of credentials which are set programmatically, and will never expire.

func (*Static) IsExpired

func (s *Static) IsExpired() bool

IsExpired returns if the credentials are expired.

For Static, the credentials never expired.

func (*Static) Retrieve

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

Retrieve returns the static credentials.

type Value

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

	// AWS Secret Access Key
	SecretAccessKey string

	// AWS Session Token
	SessionToken string

	// Signature Type.
	SignerType SignatureType
}

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

type WebIdentityResult

type WebIdentityResult struct {
	AssumedRoleUser AssumedRoleUser `xml:",omitempty"`
	Audience        string          `xml:",omitempty"`
	Credentials     struct {
		AccessKey    string    `xml:"AccessKeyId" json:"accessKey,omitempty"`
		SecretKey    string    `xml:"SecretAccessKey" json:"secretKey,omitempty"`
		Expiration   time.Time `xml:"Expiration" json:"expiration,omitempty"`
		SessionToken string    `xml:"SessionToken" json:"sessionToken,omitempty"`
	} `xml:",omitempty"`
	PackedPolicySize            int    `xml:",omitempty"`
	Provider                    string `xml:",omitempty"`
	SubjectFromWebIdentityToken string `xml:",omitempty"`
}

WebIdentityResult - Contains the response to a successful AssumeRoleWithWebIdentity request, including temporary credentials that can be used to make MinIO API requests.

type WebIdentityToken

type WebIdentityToken struct {
	Token  string
	Expiry int
}

WebIdentityToken - web identity token with expiry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL