MIZ OKI 3.0 - Unified Authentication Guide

Overview

As of November 13, 2025, MIZ OKI 3.0 has transitioned from a fragmented, cell-specific authentication model to a unified authentication system using Google Cloud Secret Manager. This significantly improves security, simplifies secret rotation, and reduces operational overhead.

Why Unified Authentication?
Architecture
Secret Configuration
Deployment
Migration from Cell-Specific Tokens
Security Best Practices
Troubleshooting

Why Unified Authentication?

Previous Architecture (Deprecated)

Problem: Each cell had its own authentication token in Secret Manager:

# ❌ OLD - Fragmented approach
- name: AUTH_TOKEN_CELL10_DEV
  valueFrom:
    secretKeyRef:
      name: mizoki-secrets
      key: auth-token-cell10-dev

- name: AUTH_TOKEN_CELL11_DEV
  valueFrom:
    secretKeyRef:
      name: mizoki-secrets
      key: auth-token-cell11-dev

Issues: - 28+ separate auth tokens to manage (one per cell) - Secret rotation nightmare: Updating tokens required changes to 28+ secrets - Increased attack surface: More secrets = more potential leak points - Operational complexity: No centralized audit trail - Inconsistent naming: AUTH_TOKEN_CELLXX_DEV varied across cells

New Architecture (Current)

Solution: Single unified authentication token for all cells:

# ✅ NEW - Unified approach
- name: MIZOKI_AUTH_TOKEN
  valueFrom:
    secretKeyRef:
      name: miz-oki-unified-auth
      key: miz-oki-auth-token

Benefits: - ✅ Single token for all 28+ cells - ✅ One-time secret rotation: Update once, applies everywhere - ✅ Reduced attack surface: 1 secret vs 28+ secrets - ✅ Simplified IAM management: One set of permissions - ✅ Consistent naming: MIZOKI_AUTH_TOKEN across all services - ✅ Easier audit trail: Single secret to monitor

Architecture

Components

┌────────────────────────────────────────────────────────┐
│       Google Cloud Secret Manager                      │
│                                                         │
│   Secret: miz-oki-unified-auth                         │
│   ├─ Key: miz-oki-auth-token                          │
│   └─ Value: <randomly-generated-token>                 │
│                                                         │
│   IAM Permissions:                                      │
│   - Default Compute SA: secretAccessor                  │
│   - Cell-specific SAs: secretAccessor (per cell)       │
└────────────────────────────────────────────────────────┘
                         │
                         │ (accessed via IAM)
                         ▼
┌────────────────────────────────────────────────────────┐
│               Cloud Run Services                        │
│                                                         │
│  Cell 01-32 Services:                                  │
│  - miz-oki-cell01                                      │
│  - miz-oki-cell02                                      │
│  - ...                                                  │
│  - miz-oki-cell32                                      │
│                                                         │
│  Environment Variable (all services):                   │
│  MIZOKI_AUTH_TOKEN = <value from secret>               │
└────────────────────────────────────────────────────────┘
                         │
                         │ (validates tokens)
                         ▼
┌────────────────────────────────────────────────────────┐
│          Inter-Cell Communication                       │
│                                                         │
│  Request Headers:                                       │
│  Authorization: Bearer ${MIZOKI_AUTH_TOKEN}            │
└────────────────────────────────────────────────────────┘

Secret Configuration

1. Create Unified Secret

The unified secret is created once and used by all cells:

# Generate a secure random token and create secret
openssl rand -base64 32 | \
  gcloud secrets create miz-oki-unified-auth \
    --data-file=- \
    --replication-policy="automatic"

Output:

Created version [1] of the secret [miz-oki-unified-auth].

2. Grant IAM Permissions

Grant secretAccessor role to service accounts that need access:

# Default Compute Service Account (for all cells)
gcloud secrets add-iam-policy-binding miz-oki-unified-auth \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

# Cell-specific Service Accounts (if using custom SAs)
for cell in cell01 cell02 cell03; do
  gcloud secrets add-iam-policy-binding miz-oki-unified-auth \
    --member="serviceAccount:miz-oki-${cell}-sa@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"
done

3. Verify Secret

# Describe the secret
gcloud secrets describe miz-oki-unified-auth

# List versions
gcloud secrets versions list miz-oki-unified-auth

# Check IAM policy
gcloud secrets get-iam-policy miz-oki-unified-auth

Deployment

Cloud Run Manifest Configuration

All cell manifests now follow this standardized pattern:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: miz-oki-cell10
  annotations:
    run.googleapis.com/ingress: "internal-and-cloud-load-balancing"
spec:
  template:
    spec:
      serviceAccountName: miz-oki-cell10-sa@${PROJECT_ID}.iam.gserviceaccount.com
      containers:
      - name: cell10-container
        image: us-central1-docker.pkg.dev/${PROJECT_ID}/miz-oki-cell10-repo/miz-oki-cell10:latest
        env:
        # ✅ Unified authentication token
        - name: MIZOKI_AUTH_TOKEN
          valueFrom:
            secretKeyRef:
              name: miz-oki-unified-auth
              key: miz-oki-auth-token
        # Other environment variables...
        - name: GCP_PROJECT_ID
          value: "${PROJECT_ID}"

Deploying a Cell

# Deploy using gcloud CLI
gcloud run services replace src/cells/cell10/cloud-run-cell10.yaml \
  --region=us-central1

# Or use Cloud Build
gcloud builds submit \
  --config=src/cells/cell10/cloudbuild.yaml \
  --region=us-central1 \
  .

Migration from Cell-Specific Tokens

Step 1: Identify Deprecated Secrets

Find all cell-specific auth token secrets:

gcloud secrets list --filter="name:auth-token-cell" --format="value(name)"

Step 2: Update Manifests

All cell manifests have been updated to use the unified token. Verify with:

# Check for deprecated cell-specific tokens
grep -r "AUTH_TOKEN_CELL" src/cells/*/cloud-run-*.yaml

# Should return no results (all updated to MIZOKI_AUTH_TOKEN)

Step 3: Redeploy Services

Redeploy all cells to use the new unified token:

# Deploy all cells (example for cell10-cell15)
for cell in $(seq -f "%02g" 10 15); do
  echo "Deploying cell${cell}..."
  gcloud run services replace \
    src/cells/cell${cell}/cloud-run-cell${cell}.yaml \
    --region=us-central1
done

Step 4: Verify Migration

# Check environment variables for deployed services
gcloud run services describe miz-oki-cell10 \
  --region=us-central1 \
  --format="yaml(spec.template.spec.containers[0].env)" | \
  grep -A 3 "MIZOKI_AUTH_TOKEN"

Expected output:

- name: MIZOKI_AUTH_TOKEN
  valueFrom:
    secretKeyRef:
      key: miz-oki-auth-token
      name: miz-oki-unified-auth

Step 5: Deprecate Old Secrets

⚠️ Only after verifying all services are using the new token:

# Disable old cell-specific secrets (DO NOT DELETE immediately)
for cell in $(seq -f "%02g" 1 32); do
  SECRET_NAME="auth-token-cell${cell}-dev"
  if gcloud secrets describe "$SECRET_NAME" &>/dev/null; then
    gcloud secrets versions disable latest --secret="$SECRET_NAME"
    echo "Disabled $SECRET_NAME"
  fi
done

Wait 30 days before deleting to ensure no services are still using them.

Security Best Practices

1. Secret Rotation

Rotate the unified token quarterly or when compromised:

# Generate new token
NEW_TOKEN=$(openssl rand -base64 32)

# Add new version to secret
echo -n "$NEW_TOKEN" | gcloud secrets versions add miz-oki-unified-auth --data-file=-

# New version is automatically used by Cloud Run (may take 1-2 minutes)

2. Audit Trail

Monitor secret access:

# View secret access logs
gcloud logging read \
  "resource.type=secret_manager_secret AND \
   resource.labels.secret_id=miz-oki-unified-auth" \
  --limit=50 \
  --format=json

3. Least Privilege Access

Only grant secretAccessor role to service accounts that need it:

# Review current IAM policy
gcloud secrets get-iam-policy miz-oki-unified-auth

# Revoke unnecessary access
gcloud secrets remove-iam-policy-binding miz-oki-unified-auth \
  --member="serviceAccount:unnecessary-sa@project.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

4. Network Security

All cells are configured with secure ingress:

annotations:
  run.googleapis.com/ingress: "internal-and-cloud-load-balancing"

This ensures services are NOT publicly accessible and require: - Internal VPC access, OR - Access via Cloud Load Balancer with proper authentication

Troubleshooting

Issue: Service cannot access secret

Symptoms:

ERROR: Failed to pull secret miz-oki-unified-auth: permission denied

Solution:

# Check service account
gcloud run services describe miz-oki-cell10 \
  --region=us-central1 \
  --format="value(spec.template.spec.serviceAccountName)"

# Grant access to the service account
gcloud secrets add-iam-policy-binding miz-oki-unified-auth \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/secretmanager.secretAccessor"

Issue: Token validation failures

Symptoms:

401 Unauthorized: Invalid authentication token

Solution: 1. Verify secret version is enabled: bash gcloud secrets versions list miz-oki-unified-auth

Check environment variable is set: bash gcloud run services describe miz-oki-cell10 \ --region=us-central1 \ --format="yaml(spec.template.spec.containers[0].env)" | \ grep MIZOKI_AUTH_TOKEN
Restart the service to pick up latest secret: bash gcloud run services update miz-oki-cell10 --region=us-central1

Issue: Manifest validation failures

Symptoms:

✗ cells/cell10/cloud-run-cell10.yaml:36: Cell-specific auth token found

Solution: Run the standardization script:

python3 scripts/validate_manifests.py

Fix any issues reported, then re-deploy:

gcloud run services replace src/cells/cell10/cloud-run-cell10.yaml \
  --region=us-central1

Changelog

Date	Change	Author
2025-11-13	Initial unified authentication implementation	Claude Code
2025-11-13	Added GitHub Actions validation workflow	Claude Code
2025-11-13	Migrated all 28 cells to unified token	Claude Code

Last Updated: November 13, 2025 Status: 🟡 In Progress - Critical fixes applied Coverage: 22/32 cells (68.8%) with manifests in src/cells/ Deployed Services: 51+ cell services deployed on Cloud Run (includes duplicates) Note: Additional cells deployed via services/ directory - audit in progress

MIZ OKI 3.0 - Unified Authentication Guide

Overview

Table of Contents

Why Unified Authentication?

Previous Architecture (Deprecated)

New Architecture (Current)

Architecture

Components

Secret Configuration

1. Create Unified Secret

2. Grant IAM Permissions

3. Verify Secret

Deployment

Cloud Run Manifest Configuration

Deploying a Cell

Migration from Cell-Specific Tokens

Step 1: Identify Deprecated Secrets

Step 2: Update Manifests

Step 3: Redeploy Services

Step 4: Verify Migration

Step 5: Deprecate Old Secrets

Security Best Practices

1. Secret Rotation

2. Audit Trail

3. Least Privilege Access

4. Network Security

Troubleshooting

Issue: Service cannot access secret

Issue: Token validation failures

Issue: Manifest validation failures

Related Documentation

Changelog