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.CredentialsCache{Provider: 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

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

Variables

This section is empty.

Functions

This section is empty.

Types

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.

                            Source Files