Admin Service Setup

Set up production infrastructure for the Admin service on admin.getorcha.com.

What Gets Created

The admin infrastructure includes:

  1. Separate Cognito User Pool - Google-only auth with Internal OAuth app restriction
  2. Admin ACM Certificate - Covers admin.prod.getorcha.com + admin.getorcha.com
  3. Admin Target Group - Routes traffic to port 7777
  4. ALB Host-Based Routing - Routes admin.* to admin target group
  5. Admin CloudWatch Log Group - /v1-orcha/admin for admin service logs
  6. Monitoring Alarms - Health check and certificate expiry alarms

When to Run

After Phase 1-3 deployment (foundation, data, compute, ops stacks exist).

This is a one-time setup for adding admin service to an existing environment.

Prerequisites

  1. AWS CLI configured with prod profile (orcha-prod)
  2. CDK deployed - Foundation, Data, Compute, Ops stacks exist
  3. Access to Google Cloud Console for creating Internal OAuth app
  4. Access to AWS ACM for certificate creation
  5. DNS management access for both prod zone and management zone

Steps

Phase 0: Manual Prerequisites

0.1 Create Admin ACM Certificate

Create a certificate that covers both admin domains. This requires cross-account DNS validation.

Using the helper script (recommended):

cd /home/volrath/code/orcha/orcha/infra
./scripts/create-cross-account-cert.sh \
    --name admin \
    --primary-domain admin.prod.getorcha.com \
    --san admin.getorcha.com

The script will request the certificate, add validation records to both zones, wait for validation, and output the ARN.

See acm-certificates.md for manual steps or troubleshooting.

0.2 Create Admin Google OAuth App (Internal)

Create a separate Google OAuth app for admin authentication. Configure it as Internal to restrict access to @getorcha.com Workspace users only.

  1. Go to Google Cloud Console - Credentials

  2. Configure OAuth Consent Screen (if creating new app):

  3. Create OAuth 2.0 Client ID:

  4. Note the Client ID and Client Secret - these go into:

Phase 1: Deploy CDK Changes

Before deploying, update the admin certificate ARN in stacks/compute_stack.py:

# Replace <ADMIN_CERTIFICATE_ARN> with actual ARN from Phase 0.1
self.admin_certificate = acm.Certificate.from_certificate_arn(
    self,
    "AdminCertificate",
    certificate_arn="arn:aws:acm:eu-central-1:700558745280:certificate/xxxx",
)

Deploy all stacks:

cd /home/volrath/code/orcha/orcha/infra
cdk deploy --all --context env_name=prod

Phase 2: Configure Admin Cognito

2.1 Store OAuth Credentials in SSM

Add to your secrets file:

/v1-orcha/admin-cognito-google-client-id=<FROM_CONSOLE>
/v1-orcha/admin-cognito-google-client-secret=<FROM_CONSOLE>

Then run:

./scripts/update-secrets.sh --from-file secrets --profile orcha-prod

2.2 Run Admin Cognito Setup Script

# Dry run first
./scripts/setup-admin-cognito-idp.sh --profile orcha-prod --dry-run

# Apply changes
./scripts/setup-admin-cognito-idp.sh --profile orcha-prod

Phase 3: DNS Configuration

Add CNAME for vanity domain in management account (getorcha.com zone):

admin.getorcha.com  CNAME  admin.prod.getorcha.com  TTL=300

Use the /delegate-subdomain skill or AWS CLI:

aws route53 change-resource-record-sets \
    --profile orcha-management \
    --hosted-zone-id <MANAGEMENT_ZONE_ID> \
    --change-batch '{
      "Changes": [{
        "Action": "CREATE",
        "ResourceRecordSet": {
          "Name": "admin.getorcha.com",
          "Type": "CNAME",
          "TTL": 300,
          "ResourceRecords": [{"Value": "admin.prod.getorcha.com"}]
        }
      }]
    }'

Verification

Certificate Status

aws acm describe-certificate \
    --profile orcha-prod \
    --region eu-central-1 \
    --certificate-arn <ADMIN_CERT_ARN> \
    --query 'Certificate.Status'
# Expected: "ISSUED"

Target Group Health

aws elbv2 describe-target-health \
    --profile orcha-prod \
    --target-group-arn $(aws elbv2 describe-target-groups \
        --profile orcha-prod \
        --names v1-orcha-admin-tg \
        --query 'TargetGroups[0].TargetGroupArn' --output text)
# Expected: State="healthy"

Admin Cognito Pool

aws cognito-idp describe-user-pool \
    --profile orcha-prod \
    --user-pool-id $(aws ssm get-parameter \
        --profile orcha-prod \
        --name /v1-orcha/admin-cognito-user-pool-id \
        --query 'Parameter.Value' --output text)

DNS Resolution

dig admin.getorcha.com
dig admin.prod.getorcha.com
# Both should resolve to ALB

End-to-End Test

  1. Visit https://admin.getorcha.com
  2. Should redirect to Cognito hosted UI with Google login button only
  3. Login with @getorcha.com Google account
  4. Should redirect back to admin dashboard
  5. Verify non-@getorcha.com users cannot authenticate (Internal app restriction)

Troubleshooting

"Certificate pending validation"

Cause: DNS validation records not added or not propagated.

Fix:

  1. Verify validation CNAMEs are in both zones (prod and management)
  2. Wait for DNS propagation (up to 30 minutes)
  3. Check record values match exactly

"Google login fails" (non-getorcha.com users)

Expected behavior! The Internal OAuth app restricts access to @getorcha.com Workspace users only.

"redirect_uri_mismatch" on Google login

Cause: Redirect URI in Google Console doesn't match Cognito callback.

Fix: Ensure the Google OAuth app has this exact redirect URI:

https://v1-orcha-admin-auth.auth.eu-central-1.amazoncognito.com/oauth2/idpresponse

Target group shows unhealthy

Cause: Admin service not running on port 7777 or /health endpoint not responding.

Fix:

  1. Check admin service is deployed and running
  2. Verify service listens on port 7777
  3. Check /health endpoint returns 200 OK

SSM parameter not found

Cause: CDK deployment created placeholders but real credentials not stored.

Fix:

  1. Complete Phase 0.2 (create Google OAuth app)
  2. Store credentials: ./scripts/update-secrets.sh --from-file secrets
  3. Run setup script: ./scripts/setup-admin-cognito-idp.sh --profile orcha-prod

Reference

Resource Prod Value
Admin User Pool Name v1-orcha-admin-pool
Admin Cognito Domain v1-orcha-admin-auth
Admin Google IdP Name Google
Admin Redirect URI https://v1-orcha-admin-auth.auth.eu-central-1.amazoncognito.com/oauth2/idpresponse
Admin Target Group v1-orcha-admin-tg
Admin Port 7777
Admin Log Group /v1-orcha/admin
Setup Script scripts/setup-admin-cognito-idp.sh
Admin URL (prod) https://admin.prod.getorcha.com
Admin URL (vanity) https://admin.getorcha.com