0
# Credentials and Authentication
1
2
Comprehensive credential management system supporting multiple authentication methods, credential providers, and flexible credential chaining. The MinIO SDK provides secure, automatic credential management for various deployment environments.
3
4
## Capabilities
5
6
### Core Credential Classes
7
8
Base credential classes providing the foundation for authentication across all MinIO operations.
9
10
```python { .api }
11
class Credentials:
12
"""Represents access key, secret key and session token credentials."""
13
def __init__(
14
self,
15
access_key: str,
16
secret_key: str,
17
session_token: str | None = None,
18
expiration: datetime.datetime | None = None
19
) -> None:
20
"""
21
Initialize credentials.
22
23
Args:
24
access_key: Access key string
25
secret_key: Secret key string
26
session_token: Optional session token for temporary credentials
27
expiration: Optional expiration time for temporary credentials
28
"""
29
30
access_key: str
31
secret_key: str
32
session_token: str | None
33
expiration: datetime.datetime | None
34
35
def is_expired(self) -> bool:
36
"""
37
Check if credentials are expired.
38
39
Returns:
40
True if credentials are expired, False otherwise
41
"""
42
43
class Provider(Protocol):
44
"""Base protocol for credential providers."""
45
def retrieve(self) -> Credentials | None:
46
"""
47
Retrieve credentials from the provider.
48
49
Returns:
50
Credentials object or None if not available
51
52
Raises:
53
Exception: If credential retrieval fails
54
"""
55
```
56
57
### Static Credential Providers
58
59
Providers for explicitly configured credentials, ideal for development and testing environments.
60
61
```python { .api }
62
class StaticProvider(Provider):
63
"""Provides static credentials that don't change."""
64
def __init__(
65
self,
66
access_key: str,
67
secret_key: str,
68
session_token: str | None = None
69
) -> None:
70
"""
71
Initialize static credential provider.
72
73
Args:
74
access_key: Static access key
75
secret_key: Static secret key
76
session_token: Optional static session token
77
"""
78
79
def retrieve(self) -> Credentials | None:
80
"""
81
Retrieve the configured static credentials.
82
83
Returns:
84
Credentials object with static values
85
"""
86
```
87
88
### Environment Variable Providers
89
90
Providers that read credentials from environment variables, supporting both AWS and MinIO conventions.
91
92
```python { .api }
93
class EnvAWSProvider(Provider):
94
"""Provides credentials from AWS environment variables."""
95
def retrieve(self) -> Credentials | None:
96
"""
97
Retrieve credentials from AWS environment variables.
98
99
Environment variables used:
100
- AWS_ACCESS_KEY_ID: Access key
101
- AWS_SECRET_ACCESS_KEY: Secret key
102
- AWS_SESSION_TOKEN: Session token (optional)
103
104
Returns:
105
Credentials from environment or None if not available
106
"""
107
108
class EnvMinioProvider(Provider):
109
"""Provides credentials from MinIO environment variables."""
110
def retrieve(self) -> Credentials | None:
111
"""
112
Retrieve credentials from MinIO environment variables.
113
114
Environment variables used:
115
- MINIO_ACCESS_KEY: Access key
116
- MINIO_SECRET_KEY: Secret key
117
118
Returns:
119
Credentials from environment or None if not available
120
"""
121
```
122
123
### Configuration File Providers
124
125
Providers that read credentials from standard configuration files used by AWS and MinIO tools.
126
127
```python { .api }
128
class AWSConfigProvider(Provider):
129
"""Provides credentials from AWS configuration files."""
130
def __init__(
131
self,
132
filename: str | None = None,
133
profile: str = "default"
134
) -> None:
135
"""
136
Initialize AWS config provider.
137
138
Args:
139
filename: Path to credentials file (defaults to ~/.aws/credentials)
140
profile: AWS profile to use (default: "default")
141
"""
142
143
def retrieve(self) -> Credentials | None:
144
"""
145
Retrieve credentials from AWS config files.
146
147
Searches in order:
148
1. ~/.aws/credentials file
149
2. ~/.aws/config file
150
151
Returns:
152
Credentials from config files or None if not available
153
"""
154
155
class MinioClientConfigProvider(Provider):
156
"""Provides credentials from MinIO client configuration files."""
157
def __init__(
158
self,
159
filename: str | None = None,
160
alias: str = "s3"
161
) -> None:
162
"""
163
Initialize MinIO client config provider.
164
165
Args:
166
filename: Path to config file (defaults to ~/.mc/config.json)
167
alias: MinIO client alias to use (default: "s3")
168
"""
169
170
def retrieve(self) -> Credentials | None:
171
"""
172
Retrieve credentials from MinIO client config.
173
174
Uses ~/.mc/config.json by default.
175
176
Returns:
177
Credentials from MinIO config or None if not available
178
"""
179
```
180
181
### AWS IAM and STS Providers
182
183
Providers for advanced AWS authentication including IAM roles, STS, and web identity tokens.
184
185
```python { .api }
186
class IamAwsProvider(Provider):
187
"""Provides credentials from AWS IAM instance metadata service."""
188
def __init__(self, custom_endpoint: str | None = None) -> None:
189
"""
190
Initialize IAM provider.
191
192
Args:
193
custom_endpoint: Custom metadata endpoint (optional)
194
"""
195
196
def retrieve(self) -> Credentials | None:
197
"""
198
Retrieve credentials from EC2 instance metadata service.
199
200
Uses AWS Instance Metadata Service (IMDS) to get temporary
201
credentials for the attached IAM role.
202
203
Returns:
204
Temporary credentials from IAM role or None if not available
205
"""
206
207
class AssumeRoleProvider(Provider):
208
"""Provides credentials via AWS STS AssumeRole operation."""
209
def __init__(
210
self,
211
credentials: Provider,
212
role_arn: str,
213
role_session_name: str,
214
duration: datetime.timedelta | None = None,
215
policy: str | None = None,
216
region: str | None = None
217
) -> None:
218
"""
219
Initialize AssumeRole provider.
220
221
Args:
222
credentials: Base credentials provider
223
role_arn: ARN of role to assume
224
role_session_name: Session name for the assumed role
225
duration: Session duration (default: 1 hour)
226
policy: Optional policy to further restrict permissions
227
region: AWS region for STS requests
228
"""
229
230
def retrieve(self) -> Credentials | None:
231
"""
232
Retrieve temporary credentials by assuming a role.
233
234
Returns:
235
Temporary credentials from STS AssumeRole or None if failed
236
"""
237
238
class WebIdentityProvider(Provider):
239
"""Provides credentials via web identity token exchange."""
240
def __init__(
241
self,
242
jwt_token: str,
243
role_arn: str,
244
role_session_name: str,
245
region: str | None = None
246
) -> None:
247
"""
248
Initialize web identity provider.
249
250
Args:
251
jwt_token: JWT token for identity verification
252
role_arn: ARN of role to assume
253
role_session_name: Session name for the assumed role
254
region: AWS region for STS requests
255
"""
256
257
def retrieve(self) -> Credentials | None:
258
"""
259
Retrieve credentials using web identity token.
260
261
Returns:
262
Temporary credentials from web identity or None if failed
263
"""
264
```
265
266
### MinIO-Specific Providers
267
268
Credential providers for MinIO-specific authentication methods and identity systems.
269
270
```python { .api }
271
class ClientGrantsProvider(Provider):
272
"""Provides credentials via MinIO client grants flow."""
273
def __init__(
274
self,
275
jwt_token: str,
276
sts_endpoint: str,
277
duration: datetime.timedelta | None = None
278
) -> None:
279
"""
280
Initialize client grants provider.
281
282
Args:
283
jwt_token: JWT token from identity provider
284
sts_endpoint: MinIO STS endpoint URL
285
duration: Token duration (optional)
286
"""
287
288
def retrieve(self) -> Credentials | None:
289
"""
290
Retrieve credentials using client grants flow.
291
292
Returns:
293
Temporary credentials from client grants or None if failed
294
"""
295
296
class LdapIdentityProvider(Provider):
297
"""Provides credentials via LDAP identity verification."""
298
def __init__(
299
self,
300
username: str,
301
password: str,
302
sts_endpoint: str,
303
ldap_username: str | None = None,
304
ldap_password: str | None = None
305
) -> None:
306
"""
307
Initialize LDAP identity provider.
308
309
Args:
310
username: LDAP username
311
password: LDAP password
312
sts_endpoint: MinIO STS endpoint URL
313
ldap_username: Alternative LDAP username format
314
ldap_password: Alternative LDAP password
315
"""
316
317
def retrieve(self) -> Credentials | None:
318
"""
319
Retrieve credentials via LDAP authentication.
320
321
Returns:
322
Temporary credentials from LDAP auth or None if failed
323
"""
324
325
class CertificateIdentityProvider(Provider):
326
"""Provides credentials via client certificate authentication."""
327
def __init__(
328
self,
329
certificate_file: str,
330
private_key_file: str,
331
sts_endpoint: str,
332
duration: datetime.timedelta | None = None
333
) -> None:
334
"""
335
Initialize certificate identity provider.
336
337
Args:
338
certificate_file: Path to client certificate file
339
private_key_file: Path to private key file
340
sts_endpoint: MinIO STS endpoint URL
341
duration: Token duration (optional)
342
"""
343
344
def retrieve(self) -> Credentials | None:
345
"""
346
Retrieve credentials using client certificate.
347
348
Returns:
349
Temporary credentials from certificate auth or None if failed
350
"""
351
```
352
353
### Credential Chaining
354
355
Provider that chains multiple credential providers for flexible authentication fallback.
356
357
```python { .api }
358
class ChainedProvider(Provider):
359
"""Chains multiple providers, trying each in sequence until one succeeds."""
360
def __init__(self, providers: list[Provider]) -> None:
361
"""
362
Initialize chained provider.
363
364
Args:
365
providers: List of providers to try in order
366
"""
367
368
def retrieve(self) -> Credentials | None:
369
"""
370
Retrieve credentials from the first successful provider.
371
372
Tries each provider in the configured order until one returns
373
valid credentials.
374
375
Returns:
376
Credentials from first successful provider or None if all fail
377
"""
378
```
379
380
## Usage Examples
381
382
### Basic Authentication
383
384
```python
385
from minio import Minio
386
from minio.credentials import StaticProvider, EnvAWSProvider, ChainedProvider
387
388
# Static credentials (development/testing)
389
static_provider = StaticProvider(
390
access_key="minio",
391
secret_key="minio123"
392
)
393
394
client = Minio(
395
"localhost:9000",
396
credentials=static_provider
397
)
398
399
# Environment variables (production)
400
env_provider = EnvAWSProvider()
401
client_env = Minio(
402
"s3.amazonaws.com",
403
credentials=env_provider
404
)
405
```
406
407
### Credential Chaining
408
409
```python
410
from minio.credentials import (
411
ChainedProvider, EnvAWSProvider, EnvMinioProvider,
412
AWSConfigProvider, IamAwsProvider
413
)
414
415
# Create a credential chain for maximum flexibility
416
provider_chain = ChainedProvider([
417
EnvAWSProvider(), # Try AWS environment variables first
418
EnvMinioProvider(), # Then MinIO environment variables
419
AWSConfigProvider(), # Then AWS config files
420
IamAwsProvider(), # Finally try IAM instance metadata
421
])
422
423
client = Minio(
424
"s3.amazonaws.com",
425
credentials=provider_chain
426
)
427
428
# The client will automatically try each provider in order
429
try:
430
buckets = client.list_buckets()
431
print("Authentication successful")
432
for bucket in buckets:
433
print(f"Bucket: {bucket.name}")
434
except Exception as e:
435
print(f"All credential providers failed: {e}")
436
```
437
438
### AWS Configuration Files
439
440
```python
441
from minio.credentials import AWSConfigProvider
442
443
# Use specific AWS profile
444
profile_provider = AWSConfigProvider(profile="production")
445
446
# Use custom credentials file
447
custom_provider = AWSConfigProvider(
448
filename="/path/to/custom/credentials",
449
profile="my-profile"
450
)
451
452
client = Minio(
453
"s3.amazonaws.com",
454
credentials=profile_provider
455
)
456
```
457
458
### MinIO Client Configuration
459
460
```python
461
from minio.credentials import MinioClientConfigProvider
462
463
# Use MinIO client configuration
464
mc_provider = MinioClientConfigProvider(alias="myminio")
465
466
client = Minio(
467
"minio.example.com:9000",
468
credentials=mc_provider
469
)
470
```
471
472
### IAM Roles and STS
473
474
```python
475
import datetime
476
from minio.credentials import IamAwsProvider, AssumeRoleProvider, StaticProvider
477
478
# Use IAM instance metadata (for EC2 instances)
479
iam_provider = IamAwsProvider()
480
481
# Assume a role with base credentials
482
base_provider = StaticProvider("base-access-key", "base-secret-key")
483
assume_role_provider = AssumeRoleProvider(
484
credentials=base_provider,
485
role_arn="arn:aws:iam::123456789012:role/MyRole",
486
role_session_name="MySession",
487
duration=datetime.timedelta(hours=2)
488
)
489
490
client = Minio(
491
"s3.amazonaws.com",
492
credentials=assume_role_provider
493
)
494
```
495
496
### Web Identity and OIDC
497
498
```python
499
from minio.credentials import WebIdentityProvider
500
501
# Use OIDC/JWT token for authentication
502
jwt_token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6..."
503
504
web_identity_provider = WebIdentityProvider(
505
jwt_token=jwt_token,
506
role_arn="arn:aws:iam::123456789012:role/WebIdentityRole",
507
role_session_name="WebSession"
508
)
509
510
client = Minio(
511
"s3.amazonaws.com",
512
credentials=web_identity_provider
513
)
514
```
515
516
### MinIO Identity Providers
517
518
```python
519
from minio.credentials import ClientGrantsProvider, LdapIdentityProvider
520
521
# Client grants flow with JWT
522
client_grants_provider = ClientGrantsProvider(
523
jwt_token="eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...",
524
sts_endpoint="http://localhost:9000"
525
)
526
527
# LDAP authentication
528
ldap_provider = LdapIdentityProvider(
529
username="john.doe",
530
password="password123",
531
sts_endpoint="http://localhost:9000"
532
)
533
534
client_jwt = Minio(
535
"localhost:9000",
536
credentials=client_grants_provider
537
)
538
539
client_ldap = Minio(
540
"localhost:9000",
541
credentials=ldap_provider
542
)
543
```
544
545
### Certificate-Based Authentication
546
547
```python
548
from minio.credentials import CertificateIdentityProvider
549
550
# Client certificate authentication
551
cert_provider = CertificateIdentityProvider(
552
certificate_file="/path/to/client.crt",
553
private_key_file="/path/to/client.key",
554
sts_endpoint="http://localhost:9000"
555
)
556
557
client = Minio(
558
"localhost:9000",
559
credentials=cert_provider
560
)
561
```
562
563
### Credential Refresh and Expiry Handling
564
565
```python
566
import datetime
567
from minio.credentials import Credentials
568
569
# Working with temporary credentials
570
temp_creds = Credentials(
571
access_key="AKIAIOSFODNN7EXAMPLE",
572
secret_key="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
573
session_token="AQoEXAMPLEH4aoAH0gNCAPyJxz...",
574
expiration=datetime.datetime.utcnow() + datetime.timedelta(hours=1)
575
)
576
577
# Check if credentials are expired
578
if temp_creds.is_expired():
579
print("Credentials are expired, need to refresh")
580
# Re-retrieve from provider
581
new_creds = provider.retrieve()
582
else:
583
print("Credentials are still valid")
584
585
# The MinIO client automatically handles credential refresh
586
# when using providers that support it
587
```
588
589
### Production Environment Setup
590
591
```python
592
import os
593
from minio import Minio
594
from minio.credentials import ChainedProvider, EnvAWSProvider, AWSConfigProvider
595
596
# Production-ready credential setup
597
def create_production_client(endpoint: str) -> Minio:
598
"""Create MinIO client with production credential chain."""
599
600
# Configure credential chain based on environment
601
providers = [EnvAWSProvider()]
602
603
# Add AWS config if available
604
aws_config_path = os.path.expanduser("~/.aws/credentials")
605
if os.path.exists(aws_config_path):
606
providers.append(AWSConfigProvider())
607
608
# Add IAM for EC2 instances
609
if os.path.exists("/opt/aws/bin/ec2-metadata"):
610
from minio.credentials import IamAwsProvider
611
providers.append(IamAwsProvider())
612
613
credential_chain = ChainedProvider(providers)
614
615
return Minio(endpoint, credentials=credential_chain)
616
617
# Usage
618
client = create_production_client("s3.amazonaws.com")
619
```