|
3 | 3 | [](https://www.npmjs.com/package/@aws-sdk/credential-provider-ini) |
4 | 4 | [](https://www.npmjs.com/package/@aws-sdk/credential-provider-ini) |
5 | 5 |
|
6 | | -## AWS Credential Provider for Node.JS - Shared Configuration Files |
| 6 | +> An internal package |
7 | 7 |
|
8 | | -This module provides a function, `fromIni` that will create |
9 | | -`CredentialProvider` functions that read from a shared credentials file at |
10 | | -`~/.aws/credentials` and a shared configuration file at `~/.aws/config`. Both |
11 | | -files are expected to be INI formatted with section names corresponding to |
12 | | -profiles. Sections in the credentials file are treated as profile names, whereas |
13 | | -profile sections in the config file must have the format of`[profile profile-name]`, |
14 | | -except for the default profile. Please see the [sample |
15 | | -files](#sample-files) below for examples of well-formed configuration and |
16 | | -credentials files. |
| 8 | +## Usage |
17 | 9 |
|
18 | | -Profiles that appear in both files will not be merged, and the version that |
19 | | -appears in the credentials file will be given precedence over the profile found |
20 | | -in the config file. |
21 | | - |
22 | | -## Supported configuration |
23 | | - |
24 | | -You may customize how credentials are resolved by providing an options hash to |
25 | | -the `fromIni` factory function. The following options are supported: |
26 | | - |
27 | | -- `profile` - The configuration profile to use. If not specified, the provider |
28 | | - will use the value in the `AWS_PROFILE` environment variable or a default of |
29 | | - `default`. |
30 | | -- `filepath` - The path to the shared credentials file. If not specified, the |
31 | | - provider will use the value in the `AWS_SHARED_CREDENTIALS_FILE` environment |
32 | | - variable or a default of `~/.aws/credentials`. |
33 | | -- `configFilepath` - The path to the shared config file. If not specified, the |
34 | | - provider will use the value in the `AWS_CONFIG_FILE` environment variable or a |
35 | | - default of `~/.aws/config`. |
36 | | -- `mfaCodeProvider` - A function that returns a a promise fulfilled with an |
37 | | - MFA token code for the provided MFA Serial code. If a profile requires an MFA |
38 | | - code and `mfaCodeProvider` is not a valid function, the credential provider |
39 | | - promise will be rejected. |
40 | | -- `roleAssumer` - A function that assumes a role and returns a promise |
41 | | - fulfilled with credentials for the assumed role. You may call `sts:assumeRole` |
42 | | - API within this function. |
43 | | -- `roleAssumerWithWebIdentity` - A function that assumes a role with web identity |
44 | | - and returns a promise fulfilled with credentials for the assumed role. You may call |
45 | | - `sts:assumeRoleWithWebIdentity` API within this function. |
46 | | - |
47 | | -## Sample files |
48 | | - |
49 | | -### `~/.aws/credentials` |
50 | | - |
51 | | -```ini |
52 | | -[default] |
53 | | -aws_access_key_id=foo |
54 | | -aws_secret_access_key=bar |
55 | | - |
56 | | -[dev] |
57 | | -aws_access_key_id=foo2 |
58 | | -aws_secret_access_key=bar2 |
59 | | - |
60 | | -[prod] |
61 | | -aws_access_key_id=foo3 |
62 | | -aws_secret_access_key=bar3 |
63 | | -``` |
64 | | - |
65 | | -### `~/.aws/config` |
66 | | - |
67 | | -```ini |
68 | | -[default] |
69 | | -aws_access_key_id=foo |
70 | | -aws_secret_access_key=bar |
71 | | - |
72 | | -[profile dev] |
73 | | -aws_access_key_id=foo2 |
74 | | -aws_secret_access_key=bar2 |
75 | | - |
76 | | -[profile prod] |
77 | | -aws_access_key_id=foo3 |
78 | | -aws_secret_access_key=bar3 |
79 | | - |
80 | | -[profile "testing host"] |
81 | | -aws_access_key_id=foo4 |
82 | | -aws_secret_access_key=bar4 |
83 | | -``` |
84 | | - |
85 | | -### profile with source profile |
86 | | - |
87 | | -```ini |
88 | | -[second] |
89 | | -aws_access_key_id=foo |
90 | | -aws_secret_access_key=bar |
91 | | - |
92 | | -[first] |
93 | | -source_profile=second |
94 | | -role_arn=arn:aws:iam::123456789012:role/example-role-arn |
95 | | -``` |
96 | | - |
97 | | -### profile with source provider |
98 | | - |
99 | | -You can supply `credential_source` options to tell the SDK where to source |
100 | | -credentials for the call to `AssumeRole`. The supported credential providers are |
101 | | -listed bellow: |
102 | | - |
103 | | -```ini |
104 | | -[default] |
105 | | -role_arn=arn:aws:iam::123456789012:role/example-role-arn |
106 | | -credential_source = Ec2InstanceMetadata |
107 | | -``` |
108 | | - |
109 | | -```ini |
110 | | -[default] |
111 | | -role_arn=arn:aws:iam::123456789012:role/example-role-arn |
112 | | -credential_source = Environment |
113 | | -``` |
114 | | - |
115 | | -```ini |
116 | | -[default] |
117 | | -role_arn=arn:aws:iam::123456789012:role/example-role-arn |
118 | | -credential_source = EcsContainer |
119 | | -``` |
120 | | - |
121 | | -### profile with web_identity_token_file |
122 | | - |
123 | | -```ini |
124 | | -[default] |
125 | | -web_identity_token_file=/temp/token |
126 | | -role_arn=arn:aws:iam::123456789012:role/example-role-arn |
127 | | -``` |
128 | | - |
129 | | -You can specify another profile(`second`) whose credentials are used to assume |
130 | | -the role by the `role_arn` setting in this profile(`first`). |
131 | | - |
132 | | -```ini |
133 | | -[second] |
134 | | -web_identity_token_file=/temp/token |
135 | | -role_arn=arn:aws:iam::123456789012:role/example-role-2 |
136 | | - |
137 | | -[first] |
138 | | -source_profile=second |
139 | | -role_arn=arn:aws:iam::123456789012:role/example-role |
140 | | -``` |
141 | | - |
142 | | -### profile with sso credentials |
143 | | - |
144 | | -Please refer the the [`sso credential provider package`](https://www.npmjs.com/package/@aws-sdk/credential-provider-sso) |
145 | | -for how to configure the SSO credentials. |
146 | | - |
147 | | -```ini |
148 | | -[default] |
149 | | -sso_account_id = 012345678901 |
150 | | -sso_region = us-east-1 |
151 | | -sso_role_name = SampleRole |
152 | | -sso_start_url = https://d-abc123.awsapps.com/start |
153 | | -``` |
154 | | - |
155 | | -You can specify another profile(`second`) whose credentials derived from SSO |
156 | | -are used to assume the role by the `role_arn` setting in this profile(`first`). |
157 | | - |
158 | | -```ini |
159 | | -[second] |
160 | | -sso_account_id = 012345678901 |
161 | | -sso_region = us-east-1 |
162 | | -sso_role_name = example-role-2 |
163 | | -sso_start_url = https://d-abc123.awsapps.com/start |
164 | | - |
165 | | -[first] |
166 | | -source_profile=second |
167 | | -role_arn=arn:aws:iam::123456789012:role/example-role |
168 | | -``` |
| 10 | +You probably shouldn't, at least directly. Please use [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers) |
| 11 | +instead. |
0 commit comments