Debian Codegraph @

docs/source/guide/credentials.rst

raw
1 .. _guide_credentials:
2
3 Credentials
4 ===========
5
6 Overview
7 --------
8
9 Boto3 credentials can be configured in multiple ways. Regardless of the source or sources that you choose, you *must* have both AWS credentials and an AWS Region set in order to make requests.
10
11
12 Interactive configuration
13 -------------------------
14
15 If you have the `AWS CLI <http://aws.amazon.com/cli/>`_, then you can use its interactive ``configure`` command to set up your credentials and default region:
16
17 .. code-block:: shell
18
19 aws configure
20
21 Follow the prompts and it will generate configuration files in the correct locations for you.
22
23
24 Configuring credentials
25 -----------------------
26
27 There are two types of configuration data in Boto3: credentials and non-credentials. Credentials include items such as ``aws_access_key_id``, ``aws_secret_access_key``, and ``aws_session_token``. Non-credential configuration includes items such as which region to use or which addressing style to use for Amazon S3. For more information on how to configure non-credential configurations, see the :ref:`guide_configuration` guide.
28
29 Boto3 will look in several locations when searching for credentials. The mechanism in which Boto3 looks for credentials is to search through a list of possible locations and stop as soon as it finds credentials. The order in which Boto3 searches for credentials is:
30
31 #. Passing credentials as parameters in the ``boto3.client()`` method
32 #. Passing credentials as parameters when creating a ``Session`` object
33 #. Environment variables
34 #. Assume role provider
35 #. Assume role with web identity provider
36 #. AWS IAM Identity Center credential provider
37 #. Shared credential file (``~/.aws/credentials``)
38 #. AWS config file (``~/.aws/config``)
39 #. Boto2 config file (``/etc/boto.cfg`` and ``~/.boto``)
40 #. Container credential provider
41 #. Instance metadata service on an Amazon EC2 instance that has an IAM role configured.
42
43 Each of those locations is discussed in more detail below.
44
45
46 Passing credentials as parameters
47 ---------------------------------
48
49 There are valid use cases for providing credentials to the ``client()`` method and ``Session`` object, these include:
50
51 * Retrieving temporary credentials using AWS STS (such as ``sts.get_session_token()``).
52 * Loading credentials from some external location, e.g the OS keychain.
53
54
55 The first option for providing credentials to Boto3 is passing them as parameters when creating clients:
56
57 .. code-block:: python
58
59 import boto3
60
61 client = boto3.client(
62 's3',
63 aws_access_key_id=ACCESS_KEY,
64 aws_secret_access_key=SECRET_KEY,
65 aws_session_token=SESSION_TOKEN
66 )
67
68
69 The second option for providing credentials to Boto3 is passing them as parameters when creating a ``Session`` object:
70
71 .. code-block:: python
72
73 import boto3
74
75 session = boto3.Session(
76 aws_access_key_id=ACCESS_KEY,
77 aws_secret_access_key=SECRET_KEY,
78 aws_session_token=SESSION_TOKEN
79 )
80
81
82 .. warning::
83
84 ``ACCESS_KEY``, ``SECRET_KEY``, and ``SESSION_TOKEN`` are variables that contain your access key, secret key, and optional session token. Note that the examples above do not have hard coded credentials. We do **not** recommend hard coding credentials in your source code.
85
86
87 Environment variables
88 ----------------------
89
90 Boto3 will check these environment variables for credentials:
91
92 * ``AWS_ACCESS_KEY_ID`` - The access key for your AWS account.
93 * ``AWS_SECRET_ACCESS_KEY`` - The secret key for your AWS account.
94 * ``AWS_SESSION_TOKEN`` - The session key for your AWS account. This is only needed when you are using temporary credentials. The ``AWS_SECURITY_TOKEN`` environment variable can also be used, but is only supported for backwards compatibility purposes. ``AWS_SESSION_TOKEN`` is supported by multiple AWS SDKs besides python.
95
96
97 Assume role provider
98 --------------------
99
100 .. note::
101
102 This is a different set of credentials configuration than using IAM roles for EC2 instances, which is discussed in a section below.
103
104 Within the ``~/.aws/config`` file, you can also configure a profile to indicate that Boto3 should assume a role. When you do this, Boto3 will automatically make the corresponding AssumeRole calls to AWS STS on your behalf. It will handle in-memory caching as well as refreshing credentials as needed.
105
106 You can specify the following configuration values for configuring an IAM role in Boto3. For more information about a particular setting, see the :ref:`guide_configuration` section.
107
108 * ``role_arn`` - The ARN of the role you want to assume.
109 * ``source_profile`` - The boto3 profile that contains credentials we should use for the initial AssumeRole call.
110 * ``credential_source`` - The resource (Amazon EC2 instance profile, Amazon ECS container role, or environment variable) that contains the credentials to use for the initial AssumeRole call.
111 * ``external_id`` - A unique identifier that is used by third parties to assume a role in their customers' accounts. This maps to the ``ExternalId`` parameter in the AssumeRole operation. This is an optional parameter.
112 * ``mfa_serial`` - The identification number of the MFA device to use when assuming a role. This is an optional parameter. Specify this value if the trust policy of the role being assumed includes a condition that requires MFA authentication. The value is either the serial number for a hardware device (such as GAHT12345678) or an Amazon Resource Name (ARN) for a virtual device (such as *arn:aws:iam::123456789012:mfa/user*).
113 * ``role_session_name`` - The name applied to this assume-role session. This value affects the assumed role user ARN (such as *arn:aws:sts::123456789012:assumed-role/role_name/role_session_name*). This maps to the RoleSessionName parameter in the AssumeRole operation. This is an optional parameter. If you do not provide this value, a session name will be automatically generated.
114 * ``duration_seconds`` - The length of time in seconds of the role session.
115
116 If MFA authentication is not enabled then you only need to specify a ``role_arn`` and a ``source_profile``.
117
118 When you specify a profile that has an IAM role configuration, Boto3 will make an ``AssumeRole`` call to retrieve temporary credentials. Subsequent Boto3 API calls will use the cached temporary credentials until they expire, in which case Boto3 will then automatically refresh the credentials.
119
120 Please note that Boto3 does not write these temporary credentials to disk. This means that temporary credentials from the ``AssumeRole`` calls are only cached in-memory within a single session. All clients created from that session will share the same temporary credentials.
121
122 If you specify ``mfa_serial``, then the first time an ``AssumeRole`` call is made, you will be prompted to enter the MFA code. **Program execution will block until you enter the MFA code.** You'll need to keep this in mind if you have an ``mfa_serial`` device configured, but would like to use Boto3 in an automated script.
123
124 Below is an example configuration for the minimal amount of configuration needed to configure an assume role profile:
125
126 .. code-block:: ini
127
128 # In ~/.aws/credentials:
129 [development]
130 aws_access_key_id=foo
131 aws_access_key_id=bar
132
133 # In ~/.aws/config
134 [profile crossaccount]
135 role_arn=arn:aws:iam:...
136 source_profile=development
137
138
139 See Using `IAM Roles <http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html>`_ for general information on IAM roles.
140
141
142 Assume Role With Web Identity Provider
143 --------------------------------------
144
145 Within the ``~/.aws/config`` file, you can also configure a profile to indicate that Boto3 should assume a role. When you do this, Boto3 will automatically make the corresponding ``AssumeRoleWithWebIdentity`` calls to AWS STS on your behalf. It will handle in-memory caching as well as refreshing credentials, as needed.
146
147 You can specify the following configuration values for configuring an IAM role in Boto3:
148
149 * ``role_arn`` - The ARN of the role you want to assume.
150 * ``web_identity_token_file`` - The path to a file which contains an OAuth 2.0 access token or OpenID Connect ID token that is provided by the identity provider. The contents of this file will be loaded and passed as the ``WebIdentityToken`` argument to the ``AssumeRoleWithWebIdentity`` operation.
151 * ``role_session_name`` - The name applied to this assume-role session. This value affects the assumed role user ARN (such as *arn:aws:sts::123456789012:assumed-role/role_name/role_session_name*). This maps to the ``RoleSessionName`` parameter in the ``AssumeRoleWithWebIdentity`` operation. This is an optional parameter. If you do not provide this value, a session name will be automatically generated.
152
153 Below is an example configuration for the minimal amount of configuration needed to configure an assume role with web identity profile:
154
155 .. code-block:: ini
156
157 # In ~/.aws/config
158 [profile web-identity]
159 role_arn=arn:aws:iam:...
160 web_identity_token_file=/path/to/a/token
161
162 This provider can also be configured via environment variables:
163
164 * ``AWS_ROLE_ARN`` - The ARN of the role you want to assume.
165 * ``AWS_WEB_IDENTITY_TOKEN_FILE`` - The path to the web identity token file.
166 * ``AWS_ROLE_SESSION_NAME`` - The name applied to this assume-role session.
167
168 .. note::
169
170 These environment variables currently only apply to the assume role with web identity provider and do not apply to the general assume role provider configuration.
171
172
173 AWS IAM Identity Center
174 -----------------------
175
176 Support for the AWS IAM Identity Center (successor to AWS Single Sign-On)
177 credential provider was added in 1.14.0. The IAM Identity Center provides
178 support for single sign-on (SSO) credentials.
179
180 To begin using the IAM Identity Center credential provider, start by using the AWS CLI (v2) to configure and manage your SSO profiles and login sessions.
181 For detailed instructions on the configuration and login process see the `AWS CLI User Guide for SSO <https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html>`_.
182 Once completed you will have one or many profiles in the shared configuration file with the following settings:
183
184 .. code-block:: ini
185
186 # In ~/.aws/config
187 [profile my-sso-profile]
188 sso_start_url = https://my-sso-portal.awsapps.com/start
189 sso_region = us-east-1
190 sso_account_id = 123456789011
191 sso_role_name = readOnly
192
193 * ``sso_start_url`` - The URL that points to the organization's IAM Identity Center user portal.
194 * ``sso_region`` - The AWS Region that contains the IAM Identity Center portal host. This is separate from the default AWS CLI Region parameter, and can also be a different Region.
195 * ``sso_account_id`` - The AWS account ID that contains the IAM role that you want to use with this profile.
196 * ``sso_role_name`` - The name of the IAM role that defines the user's permissions when using this profile.
197
198 You can then specify the profile name via the ``AWS_PROFILE`` environment variable or the ``profile_name`` argument when creating a ``Session``.
199 For example, we can create a Session using the ``my-sso-profile`` profile and any clients created from this session will use the ``my-sso-profile`` credentials:
200
201 .. code-block:: python
202
203 import boto3
204
205 session = boto3.Session(profile_name='my-sso-profile')
206 s3_client = session.client('s3')
207
208
209 Shared credentials file
210 -----------------------
211
212 The shared credentials file has a default location of ``~/.aws/credentials``. You can change the location of the shared credentials file by setting the ``AWS_SHARED_CREDENTIALS_FILE`` environment variable.
213
214 This file is an INI formatted file with section names corresponding to profiles. With each section, the three configuration variables shown above can be specified: ``aws_access_key_id``, ``aws_secret_access_key``, ``aws_session_token``. *These are the only supported values in the shared credential file.*
215
216 Below is a minimal example of the shared credentials file:
217
218 .. code-block:: ini
219
220 [default]
221 aws_access_key_id=foo
222 aws_secret_access_key=bar
223 aws_session_token=baz
224
225 The shared credentials file also supports the concept of profiles. Profiles represent logical groups of configuration. The shared credential file can have multiple profiles:
226
227 .. code-block:: ini
228
229 [default]
230 aws_access_key_id=foo
231 aws_secret_access_key=bar
232
233 [dev]
234 aws_access_key_id=foo2
235 aws_secret_access_key=bar2
236
237 [prod]
238 aws_access_key_id=foo3
239 aws_secret_access_key=bar3
240
241
242 You can then specify a profile name via the ``AWS_PROFILE`` environment variable or the ``profile_name`` argument when creating a ``Session``. For example, we can create a Session using the “dev” profile and any clients created from this session will use the “dev” credentials:
243
244 .. code-block:: python
245
246 import boto3
247
248 session = boto3.Session(profile_name='dev')
249 dev_s3_client = session.client('s3')
250
251
252 AWS config file
253 ---------------
254
255 Boto3 can also load credentials from ``~/.aws/config``. You can change this default location by setting the ``AWS_CONFIG_FILE`` environment variable. The config file is an INI format, with the same keys supported by the shared credentials file. The only difference is that profile sections *must* have the format of ``[profile profile-name]``, except for the default profile:
256
257 .. code-block:: ini
258
259 [default]
260 aws_access_key_id=foo
261 aws_secret_access_key=bar
262
263 [profile dev]
264 aws_access_key_id=foo2
265 aws_secret_access_key=bar2
266
267 [profile prod]
268 aws_access_key_id=foo3
269 aws_secret_access_key=bar3
270
271 The reason that section names must start with profile in the ``~/.aws/config`` file is because there are other sections in this file that are permitted that aren't profile configurations.
272
273
274 Boto2 configuration file support
275 --------------------------------
276
277 Boto3 will attempt to load credentials from the Boto2 config file. It first checks the file pointed to by ``BOTO_CONFIG`` if set, otherwise it will check ``/etc/boto.cfg`` and ``~/.boto``. Note that only the ``[Credentials]`` section of the boto config file is used. All other configuration data in the boto config file is ignored.
278
279 .. code-block:: ini
280
281 # Example ~/.boto file
282 [Credentials]
283 aws_access_key_id = foo
284 aws_secret_access_key = bar
285
286 .. note::
287
288 This credential provider is primarily for backwards compatibility purposes with Boto2.
289
290
291 Container credential provider
292 ---------
293 If you are using Amazon Elastic Container Service (Amazon ECS) or Amazon Elastic Kubernetes Service (Amazon EKS), you can obtain credentials by specifying an HTTP endpoint as an environment variable. The SDK will request credentials from the specified endpoint. For more information, see `Container credential provider <https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html>`_ in the Amazon SDKs and Tools Reference Guide.
294
295
296 IAM roles
297 ---------
298
299 If you are running on Amazon EC2 and no credentials have been found by any of the providers above, Boto3 will try to load credentials from the instance metadata service. In order to take advantage of this feature, you must have specified an IAM role to use when you launched your EC2 instance.
300
301 For more information on how to configure IAM roles on EC2 instances, see the `IAM Roles for Amazon EC2 <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html>`_ guide.
302
303 Note that if you've launched an EC2 instance with an IAM role configured, there's no explicit configuration you need to set in Boto3 to use these credentials. Boto3 will automatically use IAM role credentials if it does not find credentials in any of the other places listed previously.
304
305
306 Best practices for configuring credentials
307 ------------------------------------------
308
309 If you're running on an EC2 instance, use AWS IAM roles. See the `IAM Roles for Amazon EC2 <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html>`_ guide for more information on how to set this up.
310
311 If you want to interoperate with multiple AWS SDKs (e.g Java, JavaScript, Ruby, PHP, .NET, AWS CLI, Go, C++), use the shared credentials file (``~/.aws/credentials``). By using the shared credentials file, you can use a single file for credentials that will work in all AWS SDKs.