Skip to main content
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.
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.
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 \
  [email protected] \
  --member="serviceAccount:[email protected]" \
  --role="roles/iam.serviceAccountTokenCreator"

​
Azure Lighthouse

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

​
Verifying Connections

Test AWS CLI access:
docker exec -it aurora-server aws sts get-caller-identity
Should return your account ID and ARN.

​
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

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"
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"
Ensure Vault is initialized:
docker logs aurora-vault-init
Check Vault token:
echo $VAULT_TOKEN
docker exec aurora-vault vault status
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

Build docs developers (and LLMs) love

Get started for freeTalk to us