credentials

package
v7.0.8 Latest Latest
Warning

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

 Go to latest Published: Feb 4, 2021 License: Apache-2.0 Imports: 23 Imported by: 1,700

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.

View Source 
const STSVersion = "2011-06-15"

STSVersion sts version string

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

	// Custom endpoint to fetch IAM role credentials.
	Endpoint string
}

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

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

	// Exported STS endpoint to fetch STS credentials.
	STSEndpoint string

	// LDAP username/password used to fetch LDAP STS credentials.
	LDAPUsername, LDAPPassword string
}

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

	// MinIO endpoint to fetch STS credentials.
	STSEndpoint string

	// getClientGrantsTokenExpiry function to retrieve tokens
	// from IDP This function should return two values one is
	// accessToken which is a self contained access token (JWT)
	// and second return value is the expiry associated with
	// this token. This is a customer provided function and
	// is mandatory.
	GetClientGrantsTokenExpiry func() (*ClientGrantsToken, error)
}

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

	// Exported STS endpoint to fetch STS credentials.
	STSEndpoint string

	// Exported GetWebIDTokenExpiry function which returns ID
	// tokens from IDP. This function should return two values
	// one is ID token which is a self contained ID token (JWT)
	// and second return value is the expiry associated with
	// this token.
	// This is a customer provided function and is mandatory.
	GetWebIDTokenExpiry func() (*WebIdentityToken, error)
	// 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.

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.