> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```yaml theme={null}
# docker-compose.yaml:266-302
vault:
  image: hashicorp/vault:1.15
  volumes:
    - vault-data:/vault/data
    - vault-init:/vault/init
```

## Connecting AWS

<Steps>
  <Step title="Create an IAM role for Aurora">
    Aurora needs read access to CloudWatch, EC2, ECS, EKS, and RDS:

    ```json theme={null}
    {
      "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": "*"
        }
      ]
    }
    ```
  </Step>

  <Step title="Configure credentials">
    Set environment variables in `.env`:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Test the connection">
    Aurora will verify credentials on first use. Check logs:

    ```bash theme={null}
    docker logs aurora-server | grep "AWS"
    ```

    Successful connection shows:

    ```
    [INFO] AWS credentials configured for region: us-east-1
    ```
  </Step>
</Steps>

## Connecting GCP

Aurora supports GCP via OAuth2 or service accounts.

### Option 1: OAuth2 (Recommended for Development)

<Steps>
  <Step title="Configure OAuth credentials">
    Set in `.env`:

    ```bash theme={null}
    CLIENT_ID=your-oauth-client-id.apps.googleusercontent.com
    CLIENT_SECRET=your-client-secret
    ```
  </Step>

  <Step title="Authorize via UI">
    Navigate to Settings → Integrations → GCP and click "Connect".

    Aurora requests these scopes:

    ```python theme={null}
    # 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"
    ```
  </Step>

  <Step title="Select projects">
    Choose which GCP projects Aurora can access for investigations.
  </Step>
</Steps>

### Option 2: Service Account (Recommended for Production)

<Steps>
  <Step title="Create a service account">
    ```bash theme={null}
    gcloud iam service-accounts create aurora-investigator \
      --display-name="Aurora Incident Investigator"
    ```
  </Step>

  <Step title="Grant permissions">
    ```bash theme={null}
    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"
    ```
  </Step>

  <Step title="Download the key">
    ```bash theme={null}
    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/`.
  </Step>
</Steps>

## Connecting Azure

<Steps>
  <Step title="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`
  </Step>

  <Step title="Create a client secret">
    Under "Certificates & secrets", create a new client secret and save it.
  </Step>

  <Step title="Grant API permissions">
    Required permissions:

    * `Azure Service Management` → `user_impersonation`
    * `Microsoft Graph` → `User.Read`
  </Step>

  <Step title="Configure Aurora">
    Add to `.env`:

    ```bash theme={null}
    AZURE_TENANT_ID=your-tenant-id
    AZURE_CLIENT_ID=your-client-id
    AZURE_CLIENT_SECRET=your-client-secret
    ```
  </Step>

  <Step title="Authorize subscriptions">
    Grant the app "Reader" role on subscriptions you want Aurora to access:

    ```bash theme={null}
    az role assignment create \
      --assignee YOUR_CLIENT_ID \
      --role Reader \
      --scope /subscriptions/YOUR_SUBSCRIPTION_ID
    ```
  </Step>
</Steps>

## Credential Storage

All credentials are stored in Vault, not the database:

```python theme={null}
# 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:**

```sql theme={null}
SELECT provider, client_id FROM user_tokens WHERE user_id = ?;
-- client_id may contain Vault reference or metadata only
```

**Vault init happens automatically:**

```yaml theme={null}
# 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:

```python theme={null}
# 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

```bash theme={null}
gcloud iam service-accounts add-iam-policy-binding \
  target-sa@project.iam.gserviceaccount.com \
  --member="serviceAccount:aurora-investigator@project.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountTokenCreator"
```

### Azure Lighthouse

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

## Verifying Connections

<Tabs>
  <Tab title="AWS">
    Test AWS CLI access:

    ```bash theme={null}
    docker exec -it aurora-server aws sts get-caller-identity
    ```

    Should return your account ID and ARN.
  </Tab>

  <Tab title="GCP">
    Test gcloud access:

    ```bash theme={null}
    docker exec -it aurora-server gcloud projects list
    ```

    Should list accessible projects.
  </Tab>

  <Tab title="Azure">
    Test Azure CLI:

    ```bash theme={null}
    docker exec -it aurora-server az account show
    ```

    Should display subscription details.
  </Tab>
</Tabs>

## Credential Caching

Aurora caches credentials for performance:

```bash theme={null}
# .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

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    docker logs aurora-celery_worker-1 | grep "botocore"
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    docker logs aurora-server | grep "OAuth"
    ```
  </Accordion>

  <Accordion title="Vault connection issues">
    Ensure Vault is initialized:

    ```bash theme={null}
    docker logs aurora-vault-init
    ```

    Check Vault token:

    ```bash theme={null}
    echo $VAULT_TOKEN
    docker exec aurora-vault vault status
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Security Best Practices

<Warning>
  **Never commit credentials to version control.** Use environment variables and Vault.
</Warning>

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

<CardGroup cols={2}>
  <Card title="Set Up Monitoring" icon="chart-line" href="/guides/setting-up-monitoring">
    Connect Datadog, Grafana, or PagerDuty
  </Card>

  <Card title="First Investigation" icon="play" href="/guides/first-investigation">
    Run your first incident investigation
  </Card>
</CardGroup>