tessl/pypi-google-auth

Google Authentication Library providing comprehensive authentication mechanisms for Google APIs and services including OAuth 2.0, JWT, and service account credentials

—

Pending

Overview

Eval results

Files

External Account Credentials

Name: tessl/pypi-google-auth
Author: tessl

Workload identity and external identity provider integration for multi-cloud and hybrid scenarios. Enables applications running outside Google Cloud to authenticate using external identity providers like AWS, Azure, or OIDC providers.

Capabilities

Base External Account Credentials

Base class for external account credentials supporting workload identity pools and external identity providers.

class Credentials(
    google.auth.credentials.Scoped,
    google.auth.credentials.CredentialsWithQuotaProject
):
    """External account credentials for workload identity."""
    
    def __init__(
        self,
        audience,
        subject_token_type,
        token_url,
        service_account_impersonation_url=None,
        client_id=None,
        **kwargs
    ):
        """
        Initialize external account credentials.
        
        Args:
            audience (str): The STS audience which is usually the fully specified
                resource name of the workload identity pool
            subject_token_type (str): The subject token type
            token_url (str): The token server endpoint URI
            service_account_impersonation_url (str): The optional STS impersonation endpoint
            client_id (str): The STS endpoint client ID
        """
    
    @classmethod
    def from_file(cls, filename, **kwargs):
        """
        Create credentials from external account file.
        
        Args:
            filename (str): Path to external account JSON file
            **kwargs: Additional arguments
            
        Returns:
            Credentials: The constructed external account credentials
        """
    
    @classmethod
    def from_info(cls, info, **kwargs):
        """
        Create credentials from external account info.
        
        Args:
            info (Mapping[str, str]): External account info in JSON format
            **kwargs: Additional arguments
            
        Returns: 
            Credentials: The constructed external account credentials
        """

AWS Credentials

External account credentials for AWS workload identity, enabling applications running on AWS to authenticate to Google Cloud.

class Credentials(google.auth.external_account.Credentials):
    """AWS workload identity credentials."""
    
    def __init__(
        self,
        audience,
        subject_token_type,
        token_url,
        aws_region=None,
        aws_role_arn=None,
        aws_session_name=None,
        **kwargs
    ):
        """
        Initialize AWS external account credentials.
        
        Args:
            audience (str): The STS audience (workload identity pool)
            subject_token_type (str): The subject token type
            token_url (str): The token server endpoint URI
            aws_region (str): The AWS region for the credentials
            aws_role_arn (str): The AWS role ARN to assume
            aws_session_name (str): The AWS session name
        """
    
    @classmethod
    def from_file(cls, filename, **kwargs):
        """
        Create AWS credentials from file.
        
        Args:
            filename (str): Path to AWS external account JSON file
            **kwargs: Additional arguments
            
        Returns:
            Credentials: The constructed AWS credentials
        """

Usage example:

from google.auth import aws

# Create AWS workload identity credentials
credentials = aws.Credentials.from_file(
    '/path/to/aws-config.json',
    scopes=['https://www.googleapis.com/auth/cloud-platform']
)

# Use with service account impersonation
credentials = aws.Credentials(
    audience='//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider',
    subject_token_type='urn:ietf:params:aws:token-type:aws4_request',
    token_url='https://sts.googleapis.com/v1/token',
    aws_region='us-east-1',
    service_account_impersonation_url='https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/my-sa@project.iam.gserviceaccount.com:generateAccessToken'
)

Identity Pool Credentials

Workload identity pool credentials for generic OIDC and SAML providers.

class Credentials(google.auth.external_account.Credentials):
    """Workload identity pool credentials."""
    
    def __init__(
        self,
        audience,
        subject_token_type,
        token_url,
        credential_source,
        **kwargs
    ):
        """
        Initialize identity pool credentials.
        
        Args:
            audience (str): The STS audience (workload identity pool)
            subject_token_type (str): The subject token type
            token_url (str): The token server endpoint URI
            credential_source (Mapping[str, str]): The credential source configuration
        """
    
    @classmethod
    def from_file(cls, filename, **kwargs):
        """
        Create identity pool credentials from file.
        
        Args:
            filename (str): Path to identity pool JSON file
            **kwargs: Additional arguments
            
        Returns:
            Credentials: The constructed identity pool credentials
        """

Usage example:

from google.auth import identity_pool

# Create identity pool credentials
credentials = identity_pool.Credentials.from_file(
    '/path/to/identity-pool-config.json'
)

# With credential source configuration
credentials = identity_pool.Credentials(
    audience='//iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/my-pool/providers/my-provider',
    subject_token_type='urn:ietf:params:oauth:token-type:id_token',
    token_url='https://sts.googleapis.com/v1/token',
    credential_source={
        'file': '/var/run/secrets/token',
        'format': {'type': 'text'}
    }
)

External Account Authorized User

External account credentials for authorized users with refresh tokens.

class Credentials(google.auth.credentials.Credentials):
    """External account authorized user credentials."""
    
    def __init__(
        self,
        token,
        refresh_token,
        client_id,
        client_secret,
        token_url,
        **kwargs
    ):
        """
        Initialize external account authorized user credentials.
        
        Args:
            token (str): The OAuth 2.0 access token
            refresh_token (str): The refresh token
            client_id (str): The OAuth 2.0 client identifier
            client_secret (str): The OAuth 2.0 client secret
            token_url (str): The token server endpoint URI
        """
    
    @classmethod
    def from_file(cls, filename, **kwargs):
        """
        Create credentials from external account authorized user file.
        
        Args:
            filename (str): Path to external account authorized user JSON file
            **kwargs: Additional arguments
            
        Returns:
            Credentials: The constructed credentials
        """

Pluggable Credentials

Third-party pluggable credential source for custom external authentication providers.

class Credentials(google.auth.external_account.Credentials):
    """Third-party pluggable credentials."""
    
    def __init__(
        self,
        audience,
        subject_token_type,
        token_url,
        pluggable_source,
        **kwargs
    ):
        """
        Initialize pluggable credentials.
        
        Args:
            audience (str): The STS audience
            subject_token_type (str): The subject token type
            token_url (str): The token server endpoint URI  
            pluggable_source (Mapping[str, str]): The pluggable source configuration
        """

External Account Configuration

External account configuration file format:

ExternalAccountInfo = TypedDict('ExternalAccountInfo', {
    'type': str,                           # Always "external_account"
    'audience': str,                       # Workload identity pool audience
    'subject_token_type': str,             # Subject token type
    'token_url': str,                      # STS token endpoint
    'credential_source': Dict[str, Any],   # Credential source configuration
    'service_account_impersonation_url': str,  # Optional impersonation URL
    'client_id': str,                      # Optional client ID
    'quota_project_id': str,               # Optional quota project
}, total=False)

CredentialSource = TypedDict('CredentialSource', {
    'file': str,                    # File-based credential source
    'url': str,                     # URL-based credential source  
    'headers': Dict[str, str],      # Optional headers for URL source
    'format': Dict[str, str],       # Token format configuration
    'regional_cred_verification_url': str,  # AWS regional verification URL
}, total=False)

STS (Security Token Service)

Token exchange functionality for external account flows:

class Client:
    """STS client for token exchange."""
    
    def __init__(self, token_url):
        """
        Initialize STS client.
        
        Args:
            token_url (str): The STS token endpoint URL
        """
    
    def exchange_token(
        self,
        request,
        grant_type,
        subject_token,
        subject_token_type,
        audience,
        scopes=None,
        **kwargs
    ):
        """
        Exchange a subject token for a Google access token.
        
        Args:
            request (google.auth.transport.Request): HTTP transport
            grant_type (str): The OAuth 2.0 grant type
            subject_token (str): The subject token to exchange
            subject_token_type (str): The subject token type
            audience (str): The STS audience
            scopes (Sequence[str]): Optional scopes
            
        Returns:
            Mapping[str, str]: The STS token response
        """

def exchange_token(
    request,
    token_url,
    grant_type,
    subject_token,
    subject_token_type,
    audience,
    **kwargs
):
    """
    Exchange subject token for access token via STS.
    
    Args:
        request (google.auth.transport.Request): HTTP transport
        token_url (str): The STS token endpoint
        grant_type (str): The OAuth 2.0 grant type
        subject_token (str): The subject token
        subject_token_type (str): The subject token type
        audience (str): The STS audience
        
    Returns:
        Mapping[str, str]: The token response
    """

Error Handling

class RefreshError(google.auth.exceptions.GoogleAuthError):
    """Raised when external account credentials cannot be refreshed."""
    
class DefaultCredentialsError(google.auth.exceptions.GoogleAuthError):
    """Raised when external account credentials cannot be loaded."""

Common external account error scenarios: