CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-minio

MinIO Python SDK for Amazon S3 Compatible Cloud Storage

—

Pending
Overview
Eval results
Files

credentials-auth.mddocs/

Credentials and Authentication

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.

Capabilities

Core Credential Classes

Base credential classes providing the foundation for authentication across all MinIO operations.

class Credentials:
    """Represents access key, secret key and session token credentials."""
    def __init__(
        self,
        access_key: str,
        secret_key: str,
        session_token: str | None = None,
        expiration: datetime.datetime | None = None
    ) -> None:
        """
        Initialize credentials.
        
        Args:
            access_key: Access key string
            secret_key: Secret key string
            session_token: Optional session token for temporary credentials
            expiration: Optional expiration time for temporary credentials
        """
    
    access_key: str
    secret_key: str
    session_token: str | None
    expiration: datetime.datetime | None
    
    def is_expired(self) -> bool:
        """
        Check if credentials are expired.
        
        Returns:
            True if credentials are expired, False otherwise
        """

class Provider(Protocol):
    """Base protocol for credential providers."""
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials from the provider.
        
        Returns:
            Credentials object or None if not available
            
        Raises:
            Exception: If credential retrieval fails
        """

Static Credential Providers

Providers for explicitly configured credentials, ideal for development and testing environments.

class StaticProvider(Provider):
    """Provides static credentials that don't change."""
    def __init__(
        self,
        access_key: str,
        secret_key: str,
        session_token: str | None = None
    ) -> None:
        """
        Initialize static credential provider.
        
        Args:
            access_key: Static access key
            secret_key: Static secret key
            session_token: Optional static session token
        """
    
    def retrieve(self) -> Credentials | None:
        """
        Retrieve the configured static credentials.
        
        Returns:
            Credentials object with static values
        """

Environment Variable Providers

Providers that read credentials from environment variables, supporting both AWS and MinIO conventions.

class EnvAWSProvider(Provider):
    """Provides credentials from AWS environment variables."""
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials from AWS environment variables.
        
        Environment variables used:
        - AWS_ACCESS_KEY_ID: Access key
        - AWS_SECRET_ACCESS_KEY: Secret key  
        - AWS_SESSION_TOKEN: Session token (optional)
        
        Returns:
            Credentials from environment or None if not available
        """

class EnvMinioProvider(Provider):
    """Provides credentials from MinIO environment variables."""
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials from MinIO environment variables.
        
        Environment variables used:
        - MINIO_ACCESS_KEY: Access key
        - MINIO_SECRET_KEY: Secret key
        
        Returns:
            Credentials from environment or None if not available
        """

Configuration File Providers

Providers that read credentials from standard configuration files used by AWS and MinIO tools.

class AWSConfigProvider(Provider):
    """Provides credentials from AWS configuration files."""
    def __init__(
        self,
        filename: str | None = None,
        profile: str = "default"
    ) -> None:
        """
        Initialize AWS config provider.
        
        Args:
            filename: Path to credentials file (defaults to ~/.aws/credentials)
            profile: AWS profile to use (default: "default")
        """
    
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials from AWS config files.
        
        Searches in order:
        1. ~/.aws/credentials file
        2. ~/.aws/config file
        
        Returns:
            Credentials from config files or None if not available
        """

class MinioClientConfigProvider(Provider):
    """Provides credentials from MinIO client configuration files."""
    def __init__(
        self,
        filename: str | None = None,
        alias: str = "s3"
    ) -> None:
        """
        Initialize MinIO client config provider.
        
        Args:
            filename: Path to config file (defaults to ~/.mc/config.json)
            alias: MinIO client alias to use (default: "s3")
        """
    
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials from MinIO client config.
        
        Uses ~/.mc/config.json by default.
        
        Returns:
            Credentials from MinIO config or None if not available
        """

AWS IAM and STS Providers

Providers for advanced AWS authentication including IAM roles, STS, and web identity tokens.

class IamAwsProvider(Provider):
    """Provides credentials from AWS IAM instance metadata service."""
    def __init__(self, custom_endpoint: str | None = None) -> None:
        """
        Initialize IAM provider.
        
        Args:
            custom_endpoint: Custom metadata endpoint (optional)
        """
    
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials from EC2 instance metadata service.
        
        Uses AWS Instance Metadata Service (IMDS) to get temporary
        credentials for the attached IAM role.
        
        Returns:
            Temporary credentials from IAM role or None if not available
        """

class AssumeRoleProvider(Provider):
    """Provides credentials via AWS STS AssumeRole operation."""
    def __init__(
        self,
        credentials: Provider,
        role_arn: str,
        role_session_name: str,
        duration: datetime.timedelta | None = None,
        policy: str | None = None,
        region: str | None = None
    ) -> None:
        """
        Initialize AssumeRole provider.
        
        Args:
            credentials: Base credentials provider
            role_arn: ARN of role to assume
            role_session_name: Session name for the assumed role
            duration: Session duration (default: 1 hour)
            policy: Optional policy to further restrict permissions
            region: AWS region for STS requests
        """
    
    def retrieve(self) -> Credentials | None:
        """
        Retrieve temporary credentials by assuming a role.
        
        Returns:
            Temporary credentials from STS AssumeRole or None if failed
        """

class WebIdentityProvider(Provider):
    """Provides credentials via web identity token exchange."""
    def __init__(
        self,
        jwt_token: str,
        role_arn: str,
        role_session_name: str,
        region: str | None = None
    ) -> None:
        """
        Initialize web identity provider.
        
        Args:
            jwt_token: JWT token for identity verification
            role_arn: ARN of role to assume
            role_session_name: Session name for the assumed role
            region: AWS region for STS requests
        """
    
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials using web identity token.
        
        Returns:
            Temporary credentials from web identity or None if failed
        """

MinIO-Specific Providers

Credential providers for MinIO-specific authentication methods and identity systems.

class ClientGrantsProvider(Provider):
    """Provides credentials via MinIO client grants flow."""
    def __init__(
        self,
        jwt_token: str,
        sts_endpoint: str,
        duration: datetime.timedelta | None = None
    ) -> None:
        """
        Initialize client grants provider.
        
        Args:
            jwt_token: JWT token from identity provider
            sts_endpoint: MinIO STS endpoint URL
            duration: Token duration (optional)
        """
    
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials using client grants flow.
        
        Returns:
            Temporary credentials from client grants or None if failed
        """

class LdapIdentityProvider(Provider):
    """Provides credentials via LDAP identity verification."""
    def __init__(
        self,
        username: str,
        password: str,
        sts_endpoint: str,
        ldap_username: str | None = None,
        ldap_password: str | None = None
    ) -> None:
        """
        Initialize LDAP identity provider.
        
        Args:
            username: LDAP username
            password: LDAP password
            sts_endpoint: MinIO STS endpoint URL
            ldap_username: Alternative LDAP username format
            ldap_password: Alternative LDAP password
        """
    
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials via LDAP authentication.
        
        Returns:
            Temporary credentials from LDAP auth or None if failed
        """

class CertificateIdentityProvider(Provider):
    """Provides credentials via client certificate authentication."""
    def __init__(
        self,
        certificate_file: str,
        private_key_file: str,
        sts_endpoint: str,
        duration: datetime.timedelta | None = None
    ) -> None:
        """
        Initialize certificate identity provider.
        
        Args:
            certificate_file: Path to client certificate file
            private_key_file: Path to private key file
            sts_endpoint: MinIO STS endpoint URL
            duration: Token duration (optional)
        """
    
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials using client certificate.
        
        Returns:
            Temporary credentials from certificate auth or None if failed
        """

Credential Chaining

Provider that chains multiple credential providers for flexible authentication fallback.

class ChainedProvider(Provider):
    """Chains multiple providers, trying each in sequence until one succeeds."""
    def __init__(self, providers: list[Provider]) -> None:
        """
        Initialize chained provider.
        
        Args:
            providers: List of providers to try in order
        """
    
    def retrieve(self) -> Credentials | None:
        """
        Retrieve credentials from the first successful provider.
        
        Tries each provider in the configured order until one returns
        valid credentials.
        
        Returns:
            Credentials from first successful provider or None if all fail
        """

Usage Examples

Basic Authentication

from minio import Minio
from minio.credentials import StaticProvider, EnvAWSProvider, ChainedProvider

# Static credentials (development/testing)
static_provider = StaticProvider(
    access_key="minio",
    secret_key="minio123"
)

client = Minio(
    "localhost:9000",
    credentials=static_provider
)

# Environment variables (production)
env_provider = EnvAWSProvider()
client_env = Minio(
    "s3.amazonaws.com",
    credentials=env_provider
)

Credential Chaining

from minio.credentials import (
    ChainedProvider, EnvAWSProvider, EnvMinioProvider,
    AWSConfigProvider, IamAwsProvider
)

# Create a credential chain for maximum flexibility
provider_chain = ChainedProvider([
    EnvAWSProvider(),           # Try AWS environment variables first
    EnvMinioProvider(),         # Then MinIO environment variables
    AWSConfigProvider(),        # Then AWS config files
    IamAwsProvider(),          # Finally try IAM instance metadata
])

client = Minio(
    "s3.amazonaws.com",
    credentials=provider_chain
)

# The client will automatically try each provider in order
try:
    buckets = client.list_buckets()
    print("Authentication successful")
    for bucket in buckets:
        print(f"Bucket: {bucket.name}")
except Exception as e:
    print(f"All credential providers failed: {e}")

AWS Configuration Files

from minio.credentials import AWSConfigProvider

# Use specific AWS profile
profile_provider = AWSConfigProvider(profile="production")

# Use custom credentials file
custom_provider = AWSConfigProvider(
    filename="/path/to/custom/credentials",
    profile="my-profile"
)

client = Minio(
    "s3.amazonaws.com",
    credentials=profile_provider
)

MinIO Client Configuration

from minio.credentials import MinioClientConfigProvider

# Use MinIO client configuration
mc_provider = MinioClientConfigProvider(alias="myminio")

client = Minio(
    "minio.example.com:9000",
    credentials=mc_provider
)

IAM Roles and STS

import datetime
from minio.credentials import IamAwsProvider, AssumeRoleProvider, StaticProvider

# Use IAM instance metadata (for EC2 instances)
iam_provider = IamAwsProvider()

# Assume a role with base credentials
base_provider = StaticProvider("base-access-key", "base-secret-key")
assume_role_provider = AssumeRoleProvider(
    credentials=base_provider,
    role_arn="arn:aws:iam::123456789012:role/MyRole",
    role_session_name="MySession",
    duration=datetime.timedelta(hours=2)
)

client = Minio(
    "s3.amazonaws.com",
    credentials=assume_role_provider
)

Web Identity and OIDC

from minio.credentials import WebIdentityProvider

# Use OIDC/JWT token for authentication
jwt_token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6..."

web_identity_provider = WebIdentityProvider(
    jwt_token=jwt_token,
    role_arn="arn:aws:iam::123456789012:role/WebIdentityRole",
    role_session_name="WebSession"
)

client = Minio(
    "s3.amazonaws.com",
    credentials=web_identity_provider
)

MinIO Identity Providers

from minio.credentials import ClientGrantsProvider, LdapIdentityProvider

# Client grants flow with JWT
client_grants_provider = ClientGrantsProvider(
    jwt_token="eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...",
    sts_endpoint="http://localhost:9000"
)

# LDAP authentication
ldap_provider = LdapIdentityProvider(
    username="john.doe",
    password="password123",
    sts_endpoint="http://localhost:9000"
)

client_jwt = Minio(
    "localhost:9000",
    credentials=client_grants_provider
)

client_ldap = Minio(
    "localhost:9000", 
    credentials=ldap_provider
)

Certificate-Based Authentication

from minio.credentials import CertificateIdentityProvider

# Client certificate authentication
cert_provider = CertificateIdentityProvider(
    certificate_file="/path/to/client.crt",
    private_key_file="/path/to/client.key",
    sts_endpoint="http://localhost:9000"
)

client = Minio(
    "localhost:9000",
    credentials=cert_provider
)

Credential Refresh and Expiry Handling

import datetime
from minio.credentials import Credentials

# Working with temporary credentials
temp_creds = Credentials(
    access_key="AKIAIOSFODNN7EXAMPLE",
    secret_key="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    session_token="AQoEXAMPLEH4aoAH0gNCAPyJxz...",
    expiration=datetime.datetime.utcnow() + datetime.timedelta(hours=1)
)

# Check if credentials are expired
if temp_creds.is_expired():
    print("Credentials are expired, need to refresh")
    # Re-retrieve from provider
    new_creds = provider.retrieve()
else:
    print("Credentials are still valid")

# The MinIO client automatically handles credential refresh
# when using providers that support it

Production Environment Setup

import os
from minio import Minio
from minio.credentials import ChainedProvider, EnvAWSProvider, AWSConfigProvider

# Production-ready credential setup
def create_production_client(endpoint: str) -> Minio:
    """Create MinIO client with production credential chain."""
    
    # Configure credential chain based on environment
    providers = [EnvAWSProvider()]
    
    # Add AWS config if available
    aws_config_path = os.path.expanduser("~/.aws/credentials")
    if os.path.exists(aws_config_path):
        providers.append(AWSConfigProvider())
    
    # Add IAM for EC2 instances
    if os.path.exists("/opt/aws/bin/ec2-metadata"):
        from minio.credentials import IamAwsProvider
        providers.append(IamAwsProvider())
    
    credential_chain = ChainedProvider(providers)
    
    return Minio(endpoint, credentials=credential_chain)

# Usage
client = create_production_client("s3.amazonaws.com")

Install with Tessl CLI

npx tessl i tessl/pypi-minio

docs

admin-operations.md

advanced-operations.md

client-operations.md

configuration.md

credentials-auth.md

error-handling.md

index.md

tile.json