Metadata-Version: 2.4
Name: aws-gcp-wif-auth
Version: 0.2.0
Summary: AWS-GCP Workload Identity Federation authentication for EKS, EC2, Lambda, and local development
Home-page: https://github.com/yourusername/aws-gcp-wif-auth
Author: Sajal Bera
Author-email: sajal.bera@nielsen.com
Keywords: aws gcp workload-identity authentication eks ec2 lambda wif
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3>=1.26.0
Requires-Dist: google-auth>=2.16.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AWS-GCP Workload Identity Federation Auth

Python library for exchanging AWS credentials for GCP credentials using Workload Identity Federation. Works with EKS, EC2, Lambda, and local development.

## Installation

```bash
pip install aws-gcp-wif-auth
```

## Authentication Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                     AWS Environment (EKS/EC2/Lambda)            │
│                                                                 │
│  ┌──────────────┐                                              │
│  │  IAM Role    │  1. Provides AWS credentials                 │
│  │  (Pod/EC2/   │     (Access Key, Secret, Token)              │
│  │   Lambda)    │                                              │
│  └──────┬───────┘                                              │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  aws_gcp_wif_auth.get_credentials()                      │  │
│  │  • Fetches AWS credentials via boto3                     │  │
│  │  • Auto-refreshes when expired                           │  │
│  └──────┬───────────────────────────────────────────────────┘  │
└─────────┼───────────────────────────────────────────────────────┘
          │
          │ 2. Exchange AWS credentials for GCP token
          ▼
┌─────────────────────────────────────────────────────────────────┐
│              GCP Workload Identity Federation                   │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  STS Token Exchange (sts.googleapis.com)                 │  │
│  │  • Validates AWS credentials                             │  │
│  │  • Issues federated GCP token                            │  │
│  └──────┬───────────────────────────────────────────────────┘  │
│         │                                                       │
│         │ 3. Impersonate service account                        │
│         ▼                                                       │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Service Account Impersonation                           │  │
│  │  • Uses federated token                                  │  │
│  │  • Returns service account credentials                   │  │
│  └──────┬───────────────────────────────────────────────────┘  │
└─────────┼───────────────────────────────────────────────────────┘
          │
          │ 4. Access GCP APIs
          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      GCP Services                               │
│  • Vertex AI    • Cloud Storage    • BigQuery                  │
│  • Pub/Sub      • Cloud Run        • Any GCP API               │
└─────────────────────────────────────────────────────────────────┘
```

## Usage

### Auto-detect Environment (Recommended)

```python
from aws_gcp_wif_auth import get_credentials

# Automatically uses WIF in AWS, ADC locally
credentials = get_credentials(
    project_number="123456789",
    pool_id="my-wif-pool",
    provider_id="my-wif-provider",
    service_account_email="my-sa@project.iam.gserviceaccount.com"
)
```

### Explicit WIF (AWS Environments)

```python
from aws_gcp_wif_auth import get_wif_credentials

credentials = get_wif_credentials(
    project_number="123456789",
    pool_id="my-wif-pool",
    provider_id="my-wif-provider",
    service_account_email="my-sa@project.iam.gserviceaccount.com",
    aws_region="us-east-1"
)
```

### Local Development (ADC)

```python
from aws_gcp_wif_auth import get_adc_credentials

# Uses: gcloud auth application-default login
credentials = get_adc_credentials()
```

### Authenticated Session

```python
from aws_gcp_wif_auth import get_authed_session

# Get session with auto-refreshing credentials
session = get_authed_session(
    project_number="123456789",
    pool_id="my-wif-pool",
    provider_id="my-wif-provider",
    service_account_email="my-sa@project.iam.gserviceaccount.com"
)

# Make API requests
response = session.get("https://storage.googleapis.com/storage/v1/b")
```

### Environment Detection

```python
from aws_gcp_wif_auth import is_eks_environment

if is_eks_environment():
    print("Running in AWS (EKS/EC2/Lambda)")
else:
    print("Running locally")
```

### Use with Google Cloud Libraries

```python
from google.cloud import storage
from aws_gcp_wif_auth import get_credentials

credentials = get_credentials(
    project_number="123456789",
    pool_id="my-pool",
    provider_id="my-provider",
    service_account_email="sa@project.iam.gserviceaccount.com"
)

client = storage.Client(credentials=credentials)
buckets = list(client.list_buckets())
```

## Supported AWS Environments

- **EKS (Elastic Kubernetes Service)** - IAM roles for service accounts
- **EC2** - Instance profiles with IAM roles
- **Lambda** - Execution roles
- **Local Development** - Application Default Credentials (ADC)

## API Reference

### `get_credentials()`
Auto-detect environment and return appropriate credentials.

**Parameters:**
- `project_number`: GCP project number (required for WIF)
- `pool_id`: Workload Identity Pool ID (required for WIF)
- `provider_id`: Workload Identity Provider ID (required for WIF)
- `service_account_email`: GCP service account email (required for WIF)
- `aws_region`: AWS region (default: "us-east-1")
- `scopes`: OAuth scopes list (default: cloud-platform)
- `use_adc`: Force ADC instead of auto-detection (default: False)

### `get_wif_credentials()`
Explicitly use Workload Identity Federation.

### `get_adc_credentials()`
Explicitly use Application Default Credentials.

### `get_authed_session()`
Get authenticated session with auto-refreshing credentials.

### `is_eks_environment()`
Check if running in AWS environment (EKS/EC2/Lambda).

## Requirements

- Python 3.8+
- AWS environment with IAM role (for WIF)
- GCP Workload Identity Pool configured for AWS (for WIF)
- `gcloud auth application-default login` (for local ADC)

## License

MIT
