tessl/pypi-botocore
Low-level, data-driven core of boto 3 providing foundational AWS service access.
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
credentials.mddocs/
Credentials and Authentication
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.
Capabilities
Core Credential Classes
Basic credential containers for AWS authentication.
class Credentials:
def __init__(
self,
access_key: str,
secret_key: str,
token: str = None
):
"""
Initialize AWS credentials.
Args:
access_key: AWS access key ID
secret_key: AWS secret access key
token: AWS session token (optional)
"""
@property
def access_key(self) -> str:
"""AWS access key ID."""
@property
def secret_key(self) -> str:
"""AWS secret access key."""
@property
def token(self) -> str:
"""AWS session token (may be None)."""
class RefreshableCredentials(Credentials):
def __init__(
self,
access_key: str,
secret_key: str,
token: str,
expiry_time: datetime,
refresh_using: callable,
method: str,
time_fetcher: callable = None
):
"""
Initialize refreshable credentials.
Args:
access_key: AWS access key ID
secret_key: AWS secret access key
token: AWS session token
expiry_time: Credential expiration time
refresh_using: Function to refresh credentials
method: Method used to obtain credentials
time_fetcher: Function to get current time
"""
def get_frozen_credentials(self) -> Credentials:
"""
Get non-refreshable credentials snapshot.
Returns:
Credentials: Static credentials at current time
"""
def refresh_needed(self) -> bool:
"""
Check if credentials need to be refreshed.
Returns:
bool: True if refresh is needed
"""Credential Resolution
Central credential provider resolver that manages the credential provider chain.
class CredentialResolver:
def __init__(self, providers: List[CredentialProvider] = None):
"""
Initialize credential resolver.
Args:
providers: List of credential providers to use
"""
def load_credentials(self) -> Credentials:
"""
Load credentials from provider chain.
Returns:
Credentials: AWS credentials or None if not found
"""
def insert_before(
self,
name: str,
credential_provider: CredentialProvider
) -> None:
"""
Insert credential provider before named provider.
Args:
name: Provider name to insert before
credential_provider: Provider to insert
"""
def insert_after(
self,
name: str,
credential_provider: CredentialProvider
) -> None:
"""
Insert credential provider after named provider.
Args:
name: Provider name to insert after
credential_provider: Provider to insert
"""
def remove(self, name: str) -> None:
"""
Remove credential provider by name.
Args:
name: Provider name to remove
"""Environment Variable Provider
Credential provider that reads from environment variables.
class EnvProvider:
METHOD = 'env'
def __init__(self, environ: dict = None, mapping: dict = None):
"""
Initialize environment variable provider.
Args:
environ: Environment variables dictionary
mapping: Variable name mapping
"""
def load(self) -> Credentials:
"""
Load credentials from environment variables.
Expected variables:
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- AWS_SESSION_TOKEN (optional)
Returns:
Credentials: AWS credentials or None
"""Shared Credentials Provider
Credential provider that reads from AWS shared credentials file.
class SharedCredentialProvider:
METHOD = 'shared-credentials-file'
def __init__(
self,
creds_filename: str = None,
profile_name: str = None
):
"""
Initialize shared credentials provider.
Args:
creds_filename: Path to credentials file
profile_name: AWS profile name
"""
def load(self) -> Credentials:
"""
Load credentials from shared credentials file.
Default location: ~/.aws/credentials
Returns:
Credentials: AWS credentials or None
"""Config File Provider
Credential provider that reads from AWS config file.
class ConfigProvider:
METHOD = 'config-file'
def __init__(
self,
config_filename: str = None,
profile_name: str = None
):
"""
Initialize config file provider.
Args:
config_filename: Path to config file
profile_name: AWS profile name
"""
def load(self) -> Credentials:
"""
Load credentials from config file.
Default location: ~/.aws/config
Returns:
Credentials: AWS credentials or None
"""Instance Metadata Provider
Credential provider for EC2 instance metadata service (IMDS).
class InstanceMetadataProvider:
METHOD = 'iam-role'
def __init__(
self,
iam_role_fetcher: IMDSFetcher = None,
advisory_timeout: float = 1.0,
max_retry_attempts: int = 1
):
"""
Initialize instance metadata provider.
Args:
iam_role_fetcher: IMDS fetcher instance
advisory_timeout: Timeout for metadata requests
max_retry_attempts: Maximum retry attempts
"""
def load(self) -> RefreshableCredentials:
"""
Load credentials from EC2 instance metadata.
Returns:
RefreshableCredentials: Auto-refreshing credentials or None
"""Container Provider
Credential provider for container environments (ECS, Fargate).
class ContainerProvider:
METHOD = 'container-role'
def __init__(self, environ: dict = None, fetcher: ContainerMetadataFetcher = None):
"""
Initialize container provider.
Args:
environ: Environment variables
fetcher: Container metadata fetcher
"""
def load(self) -> RefreshableCredentials:
"""
Load credentials from container metadata.
Uses AWS_CONTAINER_CREDENTIALS_RELATIVE_URI or
AWS_CONTAINER_CREDENTIALS_FULL_URI environment variables.
Returns:
RefreshableCredentials: Auto-refreshing credentials or None
"""AssumeRole Provider
Credential provider for AWS STS AssumeRole operations.
class AssumeRoleProvider:
METHOD = 'assume-role'
def __init__(
self,
load_config: callable,
client_creator: callable,
cache: dict = None,
profile_name: str = None
):
"""
Initialize AssumeRole provider.
Args:
load_config: Function to load configuration
client_creator: Function to create STS client
cache: Credential cache
profile_name: AWS profile name
"""
def load(self) -> RefreshableCredentials:
"""
Load credentials via STS AssumeRole.
Returns:
RefreshableCredentials: Temporary credentials or None
"""Process Provider
Credential provider that executes external processes to obtain credentials.
class ProcessProvider:
METHOD = 'external'
def __init__(self, profile_name: str = None, load_config: callable = None):
"""
Initialize process provider.
Args:
profile_name: AWS profile name
load_config: Function to load configuration
"""
def load(self) -> Credentials:
"""
Load credentials from external process.
Executes command specified in credential_process configuration.
Returns:
Credentials: AWS credentials or None
"""SSO Provider
Credential provider for AWS Single Sign-On (SSO).
class SSOProvider:
METHOD = 'sso'
def __init__(
self,
load_config: callable,
client_creator: callable,
profile_name: str = None,
cache: dict = None,
token_cache: dict = None
):
"""
Initialize SSO provider.
Args:
load_config: Function to load configuration
client_creator: Function to create SSO client
profile_name: AWS profile name
cache: Credential cache
token_cache: Token cache
"""
def load(self) -> RefreshableCredentials:
"""
Load credentials from AWS SSO.
Returns:
RefreshableCredentials: SSO-based credentials or None
"""Usage Examples
Environment Variable Credentials
import os
# Set environment variables
os.environ['AWS_ACCESS_KEY_ID'] = 'AKIAIOSFODNN7EXAMPLE'
os.environ['AWS_SECRET_ACCESS_KEY'] = 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
os.environ['AWS_SESSION_TOKEN'] = 'optional-session-token'
# Credentials will be automatically discovered
from botocore.session import get_session
session = get_session()
credentials = session.get_credentials()Shared Credentials File
# ~/.aws/credentials
[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
[production]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY# Use specific profile
session = get_session()
session.profile = 'production'
credentials = session.get_credentials()AssumeRole Configuration
# ~/.aws/config
[profile crossaccount]
role_arn = arn:aws:iam::123456789012:role/CrossAccountRole
source_profile = default
region = us-east-1# AssumeRole credentials automatically handled
session = get_session()
session.profile = 'crossaccount'
client = session.create_client('s3') # Uses assumed roleManual Credential Creation
from botocore.credentials import Credentials
from botocore.session import get_session
# Create credentials manually
credentials = Credentials(
access_key='AKIAIOSFODNN7EXAMPLE',
secret_key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
token='optional-session-token'
)
# Use with client
session = get_session()
client = session.create_client(
's3',
aws_access_key_id=credentials.access_key,
aws_secret_access_key=credentials.secret_key,
aws_session_token=credentials.token
)Custom Credential Provider
from botocore.credentials import CredentialProvider, Credentials
class CustomProvider(CredentialProvider):
METHOD = 'custom'
def load(self):
# Custom credential logic
access_key = get_access_key_from_custom_source()
secret_key = get_secret_key_from_custom_source()
return Credentials(access_key, secret_key)
# Add to resolver
session = get_session()
resolver = session.get_component('credential_resolver')
resolver.insert_before('env', CustomProvider())Credential Refresh Handling
try:
credentials = session.get_credentials()
if isinstance(credentials, RefreshableCredentials):
if credentials.refresh_needed():
# Credentials will be automatically refreshed on next use
pass
# Get snapshot for thread-safe usage
frozen_creds = credentials.get_frozen_credentials()
except NoCredentialsError:
print("No AWS credentials found")
except CredentialRetrievalError as e:
print(f"Failed to retrieve credentials: {e}")Install with Tessl CLI
npx tessl i tessl/pypi-botocore