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 // })
92 package processcreds
93