1// Package processcreds is a credentials provider to retrieve credentials from a
 2// external CLI invoked process.
 3//
 4// WARNING: The following describes a method of sourcing credentials from an external
 5// process. This can potentially be dangerous, so proceed with caution. Other
 6// credential providers should be preferred if at all possible. If using this
 7// option, you should make sure that the config file is as locked down as possible
 8// using security best practices for your operating system.
 9//
10// # Concurrency and caching
11//
12// The Provider is not safe to be used concurrently, and does not provide any
13// caching of credentials retrieved. You should wrap the Provider with a
14// `aws.CredentialsCache` to provide concurrency safety, and caching of
15// credentials.
16//
17// # Loading credentials with the SDKs AWS Config
18//
19// You can use credentials from a AWS shared config `credential_process` in a
20// variety of ways.
21//
22// One way is to setup your shared config file, located in the default
23// location, with the `credential_process` key and the command you want to be
24// called. You also need to set the AWS_SDK_LOAD_CONFIG environment variable
25// (e.g., `export AWS_SDK_LOAD_CONFIG=1`) to use the shared config file.
26//
27//	[default]
28//	credential_process = /command/to/call
29//
30// Loading configuration using external will use the credential process to
31// retrieve credentials. NOTE: If there are credentials in the profile you are
32// using, the credential process will not be used.
33//
34//	// Initialize a session to load credentials.
35//	cfg, _ := config.LoadDefaultConfig(context.TODO())
36//
37//	// Create S3 service client to use the credentials.
38//	svc := s3.NewFromConfig(cfg)
39//
40// # Loading credentials with the Provider directly
41//
42// Another way to use the credentials process provider is by using the
43// `NewProvider` constructor to create the provider and providing a it with a
44// command to be executed to retrieve credentials.
45//
46// The following example creates a credentials provider for a command, and wraps
47// it with the CredentialsCache before assigning the provider to the Amazon S3 API
48// client's Credentials option.
49//
50//	 // Create credentials using the Provider.
51//		provider := processcreds.NewProvider("/path/to/command")
52//
53//	 // Create the service client value configured for credentials.
54//	 svc := s3.New(s3.Options{
55//	   Credentials: aws.NewCredentialsCache(provider),
56//	 })
57//
58// If you need more control, you can set any configurable options in the
59// credentials using one or more option functions.
60//
61//	provider := processcreds.NewProvider("/path/to/command",
62//	    func(o *processcreds.Options) {
63//	      // Override the provider's default timeout
64//	      o.Timeout = 2 * time.Minute
65//	    })
66//
67// You can also use your own `exec.Cmd` value by satisfying a value that satisfies
68// the `NewCommandBuilder` interface and use the `NewProviderCommand` constructor.
69//
70//	// Create an exec.Cmd
71//	cmdBuilder := processcreds.NewCommandBuilderFunc(
72//		func(ctx context.Context) (*exec.Cmd, error) {
73//			cmd := exec.CommandContext(ctx,
74//				"customCLICommand",
75//				"-a", "argument",
76//			)
77//			cmd.Env = []string{
78//				"ENV_VAR_FOO=value",
79//				"ENV_VAR_BAR=other_value",
80//			}
81//
82//			return cmd, nil
83//		},
84//	)
85//
86//	// Create credentials using your exec.Cmd and custom timeout
87//	provider := processcreds.NewProviderCommand(cmdBuilder,
88//		func(opt *processcreds.Provider) {
89//			// optionally override the provider's default timeout
90//			opt.Timeout = 1 * time.Second
91//		})
92package processcreds