processcreds

Documentation

Overview

Package processcreds is a credentials provider to retrieve credentials from a external CLI invoked process.

WARNING: The following describes a method of sourcing credentials from an external process. This can potentially be dangerous, so proceed with caution. Other credential providers should be preferred if at all possible. If using this option, you should make sure that the config file is as locked down as possible using security best practices for your operating system.

Concurrency and caching

The Provider is not safe to be used concurrently, and does not provide any caching of credentials retrieved. You should wrap the Provider with a `aws.CredentialsCache` to provide concurrency safety, and caching of credentials.

Loading credentials with the SDKs AWS Config

You can use credentials from a AWS shared config `credential_process` in a variety of ways.

One way is to setup your shared config file, located in the default location, with the `credential_process` key and the command you want to be called. You also need to set the AWS_SDK_LOAD_CONFIG environment variable (e.g., `export AWS_SDK_LOAD_CONFIG=1`) to use the shared config file.

[default]
credential_process = /command/to/call

Loading configuration using external will use the credential process to retrieve credentials. NOTE: If there are credentials in the profile you are using, the credential process will not be used.

// Initialize a session to load credentials.
cfg, _ := config.LoadDefaultConfig(context.TODO())

// Create S3 service client to use the credentials.
svc := s3.NewFromConfig(cfg)

Loading credentials with the Provider directly

Another way to use the credentials process provider is by using the `NewProvider` constructor to create the provider and providing a it with a command to be executed to retrieve credentials.

The following example creates a credentials provider for a command, and wraps it with the CredentialsCache before assigning the provider to the Amazon S3 API client's Credentials option.

 // Create credentials using the Provider.
	provider := processcreds.NewProvider("/path/to/command")

 // Create the service client value configured for credentials.
 svc := s3.New(s3.Options{
   Credentials: aws.NewCredentialsCache(provider),
 })

If you need more control, you can set any configurable options in the credentials using one or more option functions.

provider := processcreds.NewProvider("/path/to/command",
    func(o *processcreds.Options) {
      // Override the provider's default timeout
      o.Timeout = 2 * time.Minute
    })

You can also use your own `exec.Cmd` value by satisfying a value that satisfies the `NewCommandBuilder` interface and use the `NewProviderCommand` constructor.

// Create an exec.Cmd
cmdBuilder := processcreds.NewCommandBuilderFunc(
	func(ctx context.Context) (*exec.Cmd, error) {
		cmd := exec.CommandContext(ctx,
			"customCLICommand",
			"-a", "argument",
		)
		cmd.Env = []string{
			"ENV_VAR_FOO=value",
			"ENV_VAR_BAR=other_value",
		}

		return cmd, nil
	},
)

// Create credentials using your exec.Cmd and custom timeout
provider := processcreds.NewProviderCommand(cmdBuilder,
	func(opt *processcreds.Provider) {
		// optionally override the provider's default timeout
		opt.Timeout = 1 * time.Second
	})

Index

• Constants
• type CredentialProcessResponse
• type DefaultNewCommandBuilder
  • func (b DefaultNewCommandBuilder) NewCommand(ctx context.Context) (*exec.Cmd, error)
• type NewCommandBuilder
• type NewCommandBuilderFunc
  • func (fn NewCommandBuilderFunc) NewCommand(ctx context.Context) (*exec.Cmd, error)
• type Options
• type Provider
  • func NewProvider(command string, options ...func(*Options)) *Provider
  • func NewProviderCommand(builder NewCommandBuilder, options ...func(*Options)) *Provider
  • func (p *Provider) Retrieve(ctx context.Context) (aws.Credentials, error)
• type ProviderError
  • func (e *ProviderError) Error() string
  • func (e *ProviderError) Unwrap() error

Constants

const (
	// ProviderName is the name this credentials provider will label any
	// returned credentials Value with.
	ProviderName = `ProcessProvider`

	// DefaultTimeout default limit on time a process can run.
	DefaultTimeout = time.Duration(1) * time.Minute
)

Types

type CredentialProcessResponse

type CredentialProcessResponse struct {
	// As of this writing, the Version key must be set to 1. This might
	// increment over time as the structure evolves.
	Version int

	// The access key ID that identifies the temporary security credentials.
	AccessKeyID string `json:"AccessKeyId"`

	// The secret access key that can be used to sign requests.
	SecretAccessKey string

	// The token that users must pass to the service API to use the temporary credentials.
	SessionToken string

	// The date on which the current credentials expire.
	Expiration *time.Time
}

A CredentialProcessResponse is the AWS credentials format that must be returned when executing an external credential_process.

type DefaultNewCommandBuilder

type DefaultNewCommandBuilder struct {
	Args []string
}

DefaultNewCommandBuilder provides the default NewCommandBuilder implementation used by the provider. It takes a command and arguments to invoke. The command will also be initialized with the current process environment variables, stderr, and stdin pipes.

func (DefaultNewCommandBuilder) NewCommand

func (b DefaultNewCommandBuilder) NewCommand(ctx context.Context) (*exec.Cmd, error)

NewCommand returns an initialized exec.Cmd with the builder's initialized Args. The command is also initialized current process environment variables, stderr, and stdin pipes.

type NewCommandBuilder

type NewCommandBuilder interface {
	NewCommand(context.Context) (*exec.Cmd, error)
}

NewCommandBuilder provides the interface for specifying how command will be created that the Provider will use to retrieve credentials with.

type NewCommandBuilderFunc

type NewCommandBuilderFunc func(context.Context) (*exec.Cmd, error)

NewCommandBuilderFunc provides a wrapper type around a function pointer to satisfy the NewCommandBuilder interface.

func (NewCommandBuilderFunc) NewCommand

func (fn NewCommandBuilderFunc) NewCommand(ctx context.Context) (*exec.Cmd, error)

NewCommand calls the underlying function pointer the builder was initialized with.

type Options

type Options struct {
	// Timeout limits the time a process can run.
	Timeout time.Duration
}

Options is the configuration options for configuring the Provider.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider satisfies the credentials.Provider interface, and is a client to retrieve credentials from a process.

func NewProvider

func NewProvider(command string, options ...func(*Options)) *Provider

NewProvider returns a pointer to a new Credentials object wrapping the Provider.

The provider defaults to the DefaultNewCommandBuilder for creating command the Provider will use to retrieve credentials with.

func NewProviderCommand

func NewProviderCommand(builder NewCommandBuilder, options ...func(*Options)) *Provider

NewProviderCommand returns a pointer to a new Credentials object with the specified command, and default timeout duration. Use this to provide custom creation of exec.Cmd for options like environment variables, or other configuration.

func (*Provider) Retrieve

func (p *Provider) Retrieve(ctx context.Context) (aws.Credentials, error)

Retrieve executes the credential process command and returns the credentials, or error if the command fails.

type ProviderError

type ProviderError struct {
	Err error
}

ProviderError is an error indicating failure initializing or executing the process credentials provider

func (*ProviderError) Error

func (e *ProviderError) Error() string

Error returns the error message.

func (*ProviderError) Unwrap

func (e *ProviderError) Unwrap() error

Unwrap returns the underlying error the provider error wraps.