0
# Credentials and Authentication
1

2
Comprehensive credential management supporting multiple AWS authentication methods including environment variables, shared credentials, IAM roles, SSO, and external credential providers. Botocore automatically discovers and manages credentials through a configurable provider chain.
3

4
## Capabilities
5

6
### Core Credential Classes
7

8
Basic credential containers for AWS authentication.
9

10
```python { .api }
11
class Credentials:
12
    def __init__(
13
        self, 
14
        access_key: str, 
15
        secret_key: str, 
16
        token: str = None
17
    ):
18
        """
19
        Initialize AWS credentials.
20
        
21
        Args:
22
            access_key: AWS access key ID
23
            secret_key: AWS secret access key
24
            token: AWS session token (optional)
25
        """
26
    
27
    @property
28
    def access_key(self) -> str:
29
        """AWS access key ID."""
30
    
31
    @property
32
    def secret_key(self) -> str:
33
        """AWS secret access key."""
34
    
35
    @property
36
    def token(self) -> str:
37
        """AWS session token (may be None)."""
38

39
class RefreshableCredentials(Credentials):
40
    def __init__(
41
        self,
42
        access_key: str,
43
        secret_key: str,
44
        token: str,
45
        expiry_time: datetime,
46
        refresh_using: callable,
47
        method: str,
48
        time_fetcher: callable = None
49
    ):
50
        """
51
        Initialize refreshable credentials.
52
        
53
        Args:
54
            access_key: AWS access key ID
55
            secret_key: AWS secret access key
56
            token: AWS session token
57
            expiry_time: Credential expiration time
58
            refresh_using: Function to refresh credentials
59
            method: Method used to obtain credentials
60
            time_fetcher: Function to get current time
61
        """
62
    
63
    def get_frozen_credentials(self) -> Credentials:
64
        """
65
        Get non-refreshable credentials snapshot.
66
        
67
        Returns:
68
            Credentials: Static credentials at current time
69
        """
70
    
71
    def refresh_needed(self) -> bool:
72
        """
73
        Check if credentials need to be refreshed.
74
        
75
        Returns:
76
            bool: True if refresh is needed
77
        """
78
```
79

80
### Credential Resolution
81

82
Central credential provider resolver that manages the credential provider chain.
83

84
```python { .api }
85
class CredentialResolver:
86
    def __init__(self, providers: List[CredentialProvider] = None):
87
        """
88
        Initialize credential resolver.
89
        
90
        Args:
91
            providers: List of credential providers to use
92
        """
93
    
94
    def load_credentials(self) -> Credentials:
95
        """
96
        Load credentials from provider chain.
97
        
98
        Returns:
99
            Credentials: AWS credentials or None if not found
100
        """
101
    
102
    def insert_before(
103
        self, 
104
        name: str, 
105
        credential_provider: CredentialProvider
106
    ) -> None:
107
        """
108
        Insert credential provider before named provider.
109
        
110
        Args:
111
            name: Provider name to insert before
112
            credential_provider: Provider to insert
113
        """
114
    
115
    def insert_after(
116
        self, 
117
        name: str, 
118
        credential_provider: CredentialProvider
119
    ) -> None:
120
        """
121
        Insert credential provider after named provider.
122
        
123
        Args:
124
            name: Provider name to insert after
125
            credential_provider: Provider to insert
126
        """
127
    
128
    def remove(self, name: str) -> None:
129
        """
130
        Remove credential provider by name.
131
        
132
        Args:
133
            name: Provider name to remove
134
        """
135
```
136

137
### Environment Variable Provider
138

139
Credential provider that reads from environment variables.
140

141
```python { .api }
142
class EnvProvider:
143
    METHOD = 'env'
144
    
145
    def __init__(self, environ: dict = None, mapping: dict = None):
146
        """
147
        Initialize environment variable provider.
148
        
149
        Args:
150
            environ: Environment variables dictionary
151
            mapping: Variable name mapping
152
        """
153
    
154
    def load(self) -> Credentials:
155
        """
156
        Load credentials from environment variables.
157
        
158
        Expected variables:
159
        - AWS_ACCESS_KEY_ID
160
        - AWS_SECRET_ACCESS_KEY  
161
        - AWS_SESSION_TOKEN (optional)
162
        
163
        Returns:
164
            Credentials: AWS credentials or None
165
        """
166
```
167

168
### Shared Credentials Provider
169

170
Credential provider that reads from AWS shared credentials file.
171

172
```python { .api }
173
class SharedCredentialProvider:
174
    METHOD = 'shared-credentials-file'
175
    
176
    def __init__(
177
        self, 
178
        creds_filename: str = None, 
179
        profile_name: str = None
180
    ):
181
        """
182
        Initialize shared credentials provider.
183
        
184
        Args:
185
            creds_filename: Path to credentials file
186
            profile_name: AWS profile name
187
        """
188
    
189
    def load(self) -> Credentials:
190
        """
191
        Load credentials from shared credentials file.
192
        
193
        Default location: ~/.aws/credentials
194
        
195
        Returns:
196
            Credentials: AWS credentials or None
197
        """
198
```
199

200
### Config File Provider
201

202
Credential provider that reads from AWS config file.
203

204
```python { .api }
205
class ConfigProvider:
206
    METHOD = 'config-file'
207
    
208
    def __init__(
209
        self, 
210
        config_filename: str = None, 
211
        profile_name: str = None
212
    ):
213
        """
214
        Initialize config file provider.
215
        
216
        Args:
217
            config_filename: Path to config file
218
            profile_name: AWS profile name
219
        """
220
    
221
    def load(self) -> Credentials:
222
        """
223
        Load credentials from config file.
224
        
225
        Default location: ~/.aws/config
226
        
227
        Returns:
228
            Credentials: AWS credentials or None
229
        """
230
```
231

232
### Instance Metadata Provider
233

234
Credential provider for EC2 instance metadata service (IMDS).
235

236
```python { .api }
237
class InstanceMetadataProvider:
238
    METHOD = 'iam-role'
239
    
240
    def __init__(
241
        self, 
242
        iam_role_fetcher: IMDSFetcher = None,
243
        advisory_timeout: float = 1.0,
244
        max_retry_attempts: int = 1
245
    ):
246
        """
247
        Initialize instance metadata provider.
248
        
249
        Args:
250
            iam_role_fetcher: IMDS fetcher instance
251
            advisory_timeout: Timeout for metadata requests
252
            max_retry_attempts: Maximum retry attempts
253
        """
254
    
255
    def load(self) -> RefreshableCredentials:
256
        """
257
        Load credentials from EC2 instance metadata.
258
        
259
        Returns:
260
            RefreshableCredentials: Auto-refreshing credentials or None
261
        """
262
```
263

264
### Container Provider
265

266
Credential provider for container environments (ECS, Fargate).
267

268
```python { .api }
269
class ContainerProvider:
270
    METHOD = 'container-role'
271
    
272
    def __init__(self, environ: dict = None, fetcher: ContainerMetadataFetcher = None):
273
        """
274
        Initialize container provider.
275
        
276
        Args:
277
            environ: Environment variables
278
            fetcher: Container metadata fetcher
279
        """
280
    
281
    def load(self) -> RefreshableCredentials:
282
        """
283
        Load credentials from container metadata.
284
        
285
        Uses AWS_CONTAINER_CREDENTIALS_RELATIVE_URI or 
286
        AWS_CONTAINER_CREDENTIALS_FULL_URI environment variables.
287
        
288
        Returns:
289
            RefreshableCredentials: Auto-refreshing credentials or None
290
        """
291
```
292

293
### AssumeRole Provider
294

295
Credential provider for AWS STS AssumeRole operations.
296

297
```python { .api }
298
class AssumeRoleProvider:
299
    METHOD = 'assume-role'
300
    
301
    def __init__(
302
        self,
303
        load_config: callable,
304
        client_creator: callable,
305
        cache: dict = None,
306
        profile_name: str = None
307
    ):
308
        """
309
        Initialize AssumeRole provider.
310
        
311
        Args:
312
            load_config: Function to load configuration
313
            client_creator: Function to create STS client
314
            cache: Credential cache
315
            profile_name: AWS profile name
316
        """
317
    
318
    def load(self) -> RefreshableCredentials:
319
        """
320
        Load credentials via STS AssumeRole.
321
        
322
        Returns:
323
            RefreshableCredentials: Temporary credentials or None
324
        """
325
```
326

327
### Process Provider
328

329
Credential provider that executes external processes to obtain credentials.
330

331
```python { .api }
332
class ProcessProvider:
333
    METHOD = 'external'
334
    
335
    def __init__(self, profile_name: str = None, load_config: callable = None):
336
        """
337
        Initialize process provider.
338
        
339
        Args:
340
            profile_name: AWS profile name
341
            load_config: Function to load configuration
342
        """
343
    
344
    def load(self) -> Credentials:
345
        """
346
        Load credentials from external process.
347
        
348
        Executes command specified in credential_process configuration.
349
        
350
        Returns:
351
            Credentials: AWS credentials or None
352
        """
353
```
354

355
### SSO Provider
356

357
Credential provider for AWS Single Sign-On (SSO).
358

359
```python { .api }
360
class SSOProvider:
361
    METHOD = 'sso'
362
    
363
    def __init__(
364
        self,
365
        load_config: callable,
366
        client_creator: callable,
367
        profile_name: str = None,
368
        cache: dict = None,
369
        token_cache: dict = None
370
    ):
371
        """
372
        Initialize SSO provider.
373
        
374
        Args:
375
            load_config: Function to load configuration
376
            client_creator: Function to create SSO client
377
            profile_name: AWS profile name
378
            cache: Credential cache
379
            token_cache: Token cache
380
        """
381
    
382
    def load(self) -> RefreshableCredentials:
383
        """
384
        Load credentials from AWS SSO.
385
        
386
        Returns:
387
            RefreshableCredentials: SSO-based credentials or None
388
        """
389
```
390

391
## Usage Examples
392

393
### Environment Variable Credentials
394

395
```python
396
import os
397

398
# Set environment variables
399
os.environ['AWS_ACCESS_KEY_ID'] = 'AKIAIOSFODNN7EXAMPLE'
400
os.environ['AWS_SECRET_ACCESS_KEY'] = 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
401
os.environ['AWS_SESSION_TOKEN'] = 'optional-session-token'
402

403
# Credentials will be automatically discovered
404
from botocore.session import get_session
405
session = get_session()
406
credentials = session.get_credentials()
407
```
408

409
### Shared Credentials File
410

411
```ini
412
# ~/.aws/credentials
413
[default]
414
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
415
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
416

417
[production]
418
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
419
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
420
```
421

422
```python
423
# Use specific profile
424
session = get_session()
425
session.profile = 'production'
426
credentials = session.get_credentials()
427
```
428

429
### AssumeRole Configuration
430

431
```ini
432
# ~/.aws/config
433
[profile crossaccount]
434
role_arn = arn:aws:iam::123456789012:role/CrossAccountRole
435
source_profile = default
436
region = us-east-1
437
```
438

439
```python
440
# AssumeRole credentials automatically handled
441
session = get_session()
442
session.profile = 'crossaccount'
443
client = session.create_client('s3')  # Uses assumed role
444
```
445

446
### Manual Credential Creation
447

448
```python
449
from botocore.credentials import Credentials
450
from botocore.session import get_session
451

452
# Create credentials manually
453
credentials = Credentials(
454
    access_key='AKIAIOSFODNN7EXAMPLE',
455
    secret_key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
456
    token='optional-session-token'
457
)
458

459
# Use with client
460
session = get_session()
461
client = session.create_client(
462
    's3',
463
    aws_access_key_id=credentials.access_key,
464
    aws_secret_access_key=credentials.secret_key,
465
    aws_session_token=credentials.token
466
)
467
```
468

469
### Custom Credential Provider
470

471
```python
472
from botocore.credentials import CredentialProvider, Credentials
473

474
class CustomProvider(CredentialProvider):
475
    METHOD = 'custom'
476
    
477
    def load(self):
478
        # Custom credential logic
479
        access_key = get_access_key_from_custom_source()
480
        secret_key = get_secret_key_from_custom_source()
481
        return Credentials(access_key, secret_key)
482

483
# Add to resolver
484
session = get_session()
485
resolver = session.get_component('credential_resolver')
486
resolver.insert_before('env', CustomProvider())
487
```
488

489
### Credential Refresh Handling
490

491
```python
492
try:
493
    credentials = session.get_credentials()
494
    if isinstance(credentials, RefreshableCredentials):
495
        if credentials.refresh_needed():
496
            # Credentials will be automatically refreshed on next use
497
            pass
498
        
499
        # Get snapshot for thread-safe usage
500
        frozen_creds = credentials.get_frozen_credentials()
501
        
502
except NoCredentialsError:
503
    print("No AWS credentials found")
504
except CredentialRetrievalError as e:
505
    print(f"Failed to retrieve credentials: {e}")
506
```