Connecting Cloud Accounts

Connect AWS, GCP, and Azure accounts to Aurora for incident investigation

Aurora needs access to your cloud infrastructure to investigate incidents. This guide covers connecting AWS, GCP, and Azure accounts.

Why Connect Cloud Accounts?

Cloud provider access enables Aurora to:

• Query logs from CloudWatch, Cloud Logging, or Azure Monitor
• Fetch metrics and traces
• Inspect resource configurations (EC2 instances, K8s clusters, databases)
• Execute diagnostic commands (kubectl, aws cli, gcloud)
• Apply automated fixes to infrastructure

Authentication Architecture

Aurora stores credentials securely:

• Vault: User tokens stored in HashiCorp Vault (KV v2 engine)
• Database references: PostgreSQL stores Vault paths like vault:kv/data/aurora/users/{secret_name}
• Runtime resolution: Credentials fetched from Vault when needed

# docker-compose.yaml:266-302
vault:
  image: hashicorp/vault:1.15
  volumes:
    - vault-data:/vault/data
    - vault-init:/vault/init

Connecting AWS

1. Create an IAM role for Aurora

   Aurora needs read access to CloudWatch, EC2, ECS, EKS, and RDS:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "logs:DescribeLogGroups",
           "logs:DescribeLogStreams",
           "logs:FilterLogEvents",
           "cloudwatch:GetMetricStatistics",
           "cloudwatch:ListMetrics",
           "ec2:DescribeInstances",
           "ecs:DescribeClusters",
           "ecs:DescribeTasks",
           "eks:DescribeCluster",
           "eks:ListClusters",
           "rds:DescribeDBInstances"
         ],
         "Resource": "*"
       }
     ]
   }
   
2. Configure credentials

   Set environment variables in .env:

   AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
   AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
   AWS_DEFAULT_REGION=us-east-1
   

   Or use IAM role assumption for cross-account access.

3. Test the connection

   Aurora will verify credentials on first use. Check logs:

   docker logs aurora-server | grep "AWS"
   

   Successful connection shows:

   [INFO] AWS credentials configured for region: us-east-1
   

Connecting GCP

Aurora supports GCP via OAuth2 or service accounts.

Option 1: OAuth2 (Recommended for Development)

1. Configure OAuth credentials

   Set in .env:

   CLIENT_ID=your-oauth-client-id.apps.googleusercontent.com
   CLIENT_SECRET=your-client-secret
   
2. Authorize via UI

   Navigate to Settings → Integrations → GCP and click “Connect”.

   Aurora requests these scopes:

   # server/connectors/gcp_connector/auth.py:24-28
   CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform"
   USERINFO_EMAIL_SCOPE = "https://www.googleapis.com/auth/userinfo.email"
   OPENID_SCOPE = "openid"
   
3. Select projects

   Choose which GCP projects Aurora can access for investigations.

Option 2: Service Account (Recommended for Production)

1. Create a service account

   gcloud iam service-accounts create aurora-investigator \
     --display-name="Aurora Incident Investigator"
   
2. Grant permissions

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:aurora-investigator@PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/logging.viewer"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:aurora-investigator@PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/monitoring.viewer"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:aurora-investigator@PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/container.viewer"
   
3. Download the key

   gcloud iam service-accounts keys create ~/aurora-sa-key.json \
     --iam-account=aurora-investigator@PROJECT_ID.iam.gserviceaccount.com
   

   Place the JSON file in server/connectors/gcp_connector/.

Connecting Azure

1. Register an app in Azure AD

   1. Go to Azure Portal → Azure Active Directory → App registrations
   2. Click “New registration”
   3. Set redirect URI to https://your-aurora-url/api/azure/callback
2. Create a client secret

   Under “Certificates & secrets”, create a new client secret and save it.

3. Grant API permissions

   Required permissions:

   • Azure Service Management → user_impersonation
   • Microsoft Graph → User.Read
4. Configure Aurora

   Add to .env:

   AZURE_TENANT_ID=your-tenant-id
   AZURE_CLIENT_ID=your-client-id
   AZURE_CLIENT_SECRET=your-client-secret
   
5. Authorize subscriptions

   Grant the app “Reader” role on subscriptions you want Aurora to access:

   az role assignment create \
     --assignee YOUR_CLIENT_ID \
     --role Reader \
     --scope /subscriptions/YOUR_SUBSCRIPTION_ID
   

Credential Storage

All credentials are stored in Vault, not the database:

# server/utils/storage/storage.py patterns apply to Vault too
# Credentials stored as: vault:kv/data/aurora/users/{user_id}/{provider}

Database stores only references:

SELECT provider, client_id FROM user_tokens WHERE user_id = ?;
-- client_id may contain Vault reference or metadata only

Vault init happens automatically:

# docker-compose.yaml:289-302
vault-init:
  image: busybox:latest
  command: ["sh", "/vault-init.sh"]
  environment:
    VAULT_ADDR: http://vault:8200
    VAULT_KV_MOUNT: ${VAULT_KV_MOUNT}

Multi-Account and Cross-Account Access

AWS Role Assumption

For multiple AWS accounts:

# Use STS to assume roles in other accounts
sts_client = boto3.client('sts')
response = sts_client.assume_role(
    RoleArn='arn:aws:iam::123456789012:role/AuroraInvestigator',
    RoleSessionName='aurora-incident-session'
)

GCP Service Account Impersonation

gcloud iam service-accounts add-iam-policy-binding \
  [e-mail] \
  --member="serviceAccount:[e-mail]" \
  --role="roles/iam.serviceAccountTokenCreator"

Azure Lighthouse

Use Azure Lighthouse for managing multiple tenants from a single Aurora instance.

Verifying Connections

AWS

Test AWS CLI access:

docker exec -it aurora-server aws sts get-caller-identity

Should return your account ID and ARN.

GCP

Test gcloud access:

docker exec -it aurora-server gcloud projects list

Should list accessible projects.

Azure

Test Azure CLI:

docker exec -it aurora-server az account show

Should display subscription details.

Credential Caching

Aurora caches credentials for performance:

# .env configuration
AURORA_SETUP_CACHE_ENABLED=true
AURORA_SETUP_CACHE_TTL=3600  # 1 hour
AURORA_CACHE_TOKEN_IN_REDIS=true

Cache keys stored in Redis:

setup:cache:v1:{user_id}:{provider}

Troubleshooting

AWS credentials not working

Check:

1. Environment variables are set correctly
2. IAM role has required permissions
3. Region is correct for your resources

View detailed errors:

docker logs aurora-celery_worker-1 | grep "botocore"

GCP OAuth fails

Verify:

• CLIENT_ID and CLIENT_SECRET are correct
• Redirect URI matches OAuth config
• Required scopes are enabled in GCP Console

Check Aurora server logs for OAuth errors:

docker logs aurora-server | grep "OAuth"

Vault connection issues

Ensure Vault is initialized:

docker logs aurora-vault-init

Check Vault token:

echo $VAULT_TOKEN
docker exec aurora-vault vault status

Permission denied errors

Aurora logs will show which API calls are failing. Example:

ClientError: An error occurred (AccessDenied) when calling the DescribeLogGroups operation

Add the missing permission to your IAM policy/role.

Security Best Practices

Never commit credentials to version control. Use environment variables and Vault.

1. Use least-privilege permissions - Grant only what Aurora needs
2. Rotate credentials regularly - Set up automatic rotation for long-lived keys
3. Enable MFA for privileged actions - Require MFA for destructive operations
4. Audit access logs - Monitor CloudTrail, Cloud Audit Logs, and Azure Activity Logs
5. Use temporary credentials - Prefer STS/OAuth tokens over long-lived keys

Next Steps

Set Up Monitoring

Connect Datadog, Grafana, or PagerDuty

First Investigation

Run your first incident investigation