kiarina-lib-google 2.2.1

Google Cloud client library for kiarina namespace

kiarina-lib-google

English | 日本語

A Python library for Google Cloud authentication with configuration management using pydantic-settings-manager.

Features

• Multiple Authentication Methods: Default credentials (ADC), service accounts, and user accounts
• Service Account Impersonation: Delegated access with configurable scopes
• Configuration Management: Flexible configuration with pydantic-settings-manager
• Credentials Caching: Automatic caching and refresh for user accounts
• Self-Signed JWT: Generate JWTs for service account authentication
• Type Safety: Full type hints and Pydantic validation

Installation

pip install kiarina-lib-google

Quick Start

Default Credentials (ADC)

from kiarina.lib.google import get_credentials

# Uses Application Default Credentials
credentials = get_credentials()

Service Account

from kiarina.lib.google import get_credentials, GoogleSettings

# From key file
credentials = get_credentials(
    settings=GoogleSettings(
        type="service_account",
        service_account_file="~/path/to/key.json"
    )
)

# From JSON data
credentials = get_credentials(
    settings=GoogleSettings(
        type="service_account",
        service_account_data='{"type":"service_account",...}'
    )
)

User Account (OAuth2)

# From authorized user file
credentials = get_credentials(
    settings=GoogleSettings(
        type="user_account",
        authorized_user_file="~/.config/gcloud/application_default_credentials.json",
        scopes=["https://www.googleapis.com/auth/drive"]
    )
)

Service Account Impersonation

# Impersonate a service account
credentials = get_credentials(
    settings=GoogleSettings(
        type="service_account",
        service_account_file="~/source-key.json",
        impersonate_service_account="[e-mail]",
        scopes=["https://www.googleapis.com/auth/cloud-platform"]
    )
)

Note: Source principal requires roles/iam.serviceAccountTokenCreator role.

Credentials Caching

from kiarina.lib.google import CredentialsCache

class InMemoryCache(CredentialsCache):
    def __init__(self):
        self._cache: str | None = None

    def get(self) -> str | None:
        return self._cache

    def set(self, value: str) -> None:
        self._cache = value

# Use cache for user account credentials
credentials = get_credentials(
    settings=GoogleSettings(
        type="user_account",
        authorized_user_file="~/authorized-user.json",
        scopes=["https://www.googleapis.com/auth/drive"]
    ),
    cache=InMemoryCache()
)

Self-Signed JWT

from kiarina.lib.google import get_self_signed_jwt

jwt_token = get_self_signed_jwt(
    settings=GoogleSettings(
        type="service_account",
        service_account_file="~/key.json"
    ),
    audience="https://your-service.example.com/"
)

Configuration

YAML Configuration (Recommended)

kiarina.lib.google:
  development:
    type: user_account
    authorized_user_file: ~/.config/gcloud/application_default_credentials.json
    scopes:
      - https://www.googleapis.com/auth/cloud-platform

  production:
    type: service_account
    service_account_file: /secrets/prod-sa-key.json
    project_id: your-project-id
    scopes:
      - https://www.googleapis.com/auth/cloud-platform

  impersonation:
    type: service_account
    service_account_file: ~/source-key.json
    impersonate_service_account: [e-mail]
    scopes:
      - https://www.googleapis.com/auth/cloud-platform

Load configuration:

from pydantic_settings_manager import load_user_configs
import yaml

with open("config.yaml") as f:
    config = yaml.safe_load(f)
    load_user_configs(config)

# Use configured credentials
from kiarina.lib.google import get_credentials
credentials = get_credentials("production")

Environment Variables

export KIARINA_LIB_GOOGLE_TYPE="service_account"
export KIARINA_LIB_GOOGLE_SERVICE_ACCOUNT_FILE="~/key.json"
export KIARINA_LIB_GOOGLE_PROJECT_ID="your-project-id"
export KIARINA_LIB_GOOGLE_SCOPES="https://www.googleapis.com/auth/cloud-platform"

Programmatic Configuration

from kiarina.lib.google import settings_manager

settings_manager.user_config = {
    "dev": {
        "type": "user_account",
        "authorized_user_file": "~/.config/gcloud/application_default_credentials.json"
    },
    "prod": {
        "type": "service_account",
        "service_account_file": "/secrets/key.json"
    }
}

settings_manager.active_key = "prod"
credentials = get_credentials()

API Reference

Main Functions

get_credentials(settings_key=None, *, settings=None, scopes=None, cache=None)

Get Google Cloud credentials based on configuration.

Parameters:

• settings_key (str | None): Configuration key for multi-config setup
• settings (GoogleSettings | None): Settings object (overrides settings_key)
• scopes (list[str] | None): OAuth2 scopes (overrides settings.scopes)
• cache (CredentialsCache | None): Credentials cache for user accounts

Returns: Credentials - Google Cloud credentials

get_self_signed_jwt(settings_key=None, *, settings=None, audience)

Generate a self-signed JWT for service account authentication.

Parameters:

• settings_key (str | None): Configuration key
• settings (GoogleSettings | None): Settings object
• audience (str): JWT audience (target service URL)

Returns: str - Self-signed JWT token

Utility Functions

get_default_credentials()

Get default credentials using Application Default Credentials (ADC).

Returns: Credentials

get_service_account_credentials(*, service_account_file=None, service_account_data=None)

Get service account credentials from file or data.

Returns: google.oauth2.service_account.Credentials

get_user_account_credentials(*, authorized_user_file=None, authorized_user_data=None, scopes=None, cache=None)

Get user account credentials from file or data with optional caching.

Returns: google.oauth2.credentials.Credentials

Configuration

GoogleSettings

Pydantic settings model for authentication configuration.

Key Fields:

• type: Authentication type ("default", "service_account", "user_account")
• service_account_file: Path to service account key file
• service_account_data: Service account key data (JSON string, SecretStr)
• authorized_user_file: Path to authorized user file
• authorized_user_data: Authorized user data (JSON string, SecretStr)
• impersonate_service_account: Target service account email for impersonation
• scopes: OAuth2 scopes (default: empty)
• project_id: GCP project ID

Helper Methods:

• get_service_account_data(): Parse service_account_data JSON
• get_client_secret_data(): Parse client_secret_data JSON
• get_authorized_user_data(): Parse authorized_user_data JSON

CredentialsCache (Protocol)

Protocol for implementing credentials cache.

Methods:

• get() -> str | None: Retrieve cached credentials (JSON string)
• set(value: str) -> None: Store credentials (JSON string)

Authentication Priority

Default Credentials

Uses Application Default Credentials (ADC) in this order:

1. GOOGLE_APPLICATION_CREDENTIALS environment variable (service account)
2. gcloud auth application-default login credentials (user account)
3. Compute Engine metadata server (compute engine)

Default Scopes

No scopes are requested by default. Specify only the scopes required by the application in configuration or the function call.

User account credentials reuse scopes stored in the authorized user data when no scopes are specified. Service account impersonation requires at least one explicit scope.

Testing

Setup Test Configuration

[!Note] ADC tests Tests that depend on default credentials (ADC) require you to be authenticated with Google Cloud. Run gcloud auth application-default login before running the tests.

# Copy sample configuration
cp packages/kiarina-lib-google/test_settings.sample.yaml \
   packages/kiarina-lib-google/test_settings.yaml

# Edit with your credentials
# Set environment variable
export KIARINA_LIB_GOOGLE_TEST_SETTINGS_FILE="packages/kiarina-lib-google/test_settings.yaml"

Run Tests

# Run all checks
mise run package:check kiarina-lib-google

# Run tests with coverage
mise run package:test kiarina-lib-google --coverage

Dependencies

• google-api-python-client - Google API client
• pydantic-settings - Settings management
• pydantic-settings-manager - Advanced settings management

License

MIT License - see the LICENSE file for details.

Related Projects

• kiarina-python - Main monorepo
• pydantic-settings-manager - Configuration management library