> ## 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.

# Amazon Web Services (AWS)

> Connect Aurora to your AWS account using IAM role assumption

## Overview

Aurora integrates with AWS using IAM role assumption with an External ID for secure cross-account access. Unlike traditional access keys, this method provides better security and auditability.

## What Aurora Can Access

Once authenticated, Aurora can discover and manage:

* **EKS Clusters**: Elastic Kubernetes Service clusters
* **EC2 Instances**: Virtual machines and auto-scaling groups
* **RDS Databases**: Relational database instances
* **S3 Buckets**: Object storage
* **Lambda Functions**: Serverless compute
* **VPCs**: Virtual Private Cloud networking
* **ECS/Fargate**: Container orchestration services
* **CloudFormation Stacks**: Infrastructure as code
* **IAM Roles**: Identity and access management
* **All AWS Resources**: Via Resource Explorer 2 API

## Prerequisites

<Steps>
  <Step title="AWS Account">
    You need an AWS account with administrative access
  </Step>

  <Step title="Aurora AWS Account">
    Aurora must have AWS credentials configured (`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`)
  </Step>

  <Step title="IAM Permissions">
    You need permissions to create IAM roles and trust policies in your AWS account
  </Step>
</Steps>

## Environment Variables

Configure these environment variables in Aurora's `.env` file:

```bash theme={null}
# Aurora's AWS Credentials (used to assume roles in your account)
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Optional: Default AWS region
AWS_DEFAULT_REGION=us-east-1
```

<Warning>
  These credentials should belong to Aurora's AWS account, NOT your user account. They are used by Aurora to assume the role you create in your account.
</Warning>

## Authentication Flow

Aurora uses IAM role assumption with External ID for secure cross-account access:

<Steps>
  <Step title="Create IAM Role">
    In your AWS account, create an IAM role with a trust policy that allows Aurora to assume it
  </Step>

  <Step title="Configure External ID">
    Use the External ID provided by Aurora in the workspace settings (prevents confused deputy attacks)
  </Step>

  <Step title="Attach Policies">
    Attach necessary IAM policies to the role (ReadOnlyAccess for Ask mode, PowerUserAccess for Do mode)
  </Step>

  <Step title="Provide Role ARN">
    Enter the Role ARN in Aurora's UI
  </Step>

  <Step title="Validate Assumption">
    Aurora validates it can assume the role using STS AssumeRole API
  </Step>

  <Step title="Store Connection">
    Role ARN is stored in the `user_connections` table (single source of truth)
  </Step>
</Steps>

## Setup Instructions

### Step 1: Get Your External ID

<Steps>
  <Step title="Open Aurora Workspace Settings">
    Navigate to your workspace in the Aurora UI
  </Step>

  <Step title="Find AWS Section">
    Go to the AWS integration settings
  </Step>

  <Step title="Copy External ID">
    Copy the External ID displayed (e.g., `a1b2c3d4-e5f6-7890-abcd-ef1234567890`)
  </Step>
</Steps>

### Step 2: Create IAM Role in AWS Console

<Steps>
  <Step title="Open IAM Console">
    Go to [AWS IAM Console](https://console.aws.amazon.com/iam/) > Roles > Create role
  </Step>

  <Step title="Select Trusted Entity">
    Choose **AWS account** as the trusted entity type
  </Step>

  <Step title="Enter Aurora Account ID">
    Enter Aurora's AWS account ID (displayed in the Aurora UI)
  </Step>

  <Step title="Require External ID">
    Check **Require external ID** and paste the External ID from Aurora
  </Step>

  <Step title="Attach Permissions">
    For **Ask mode** (read-only): Attach `ReadOnlyAccess` managed policy

    For **Do mode** (full management): Attach `PowerUserAccess` or create a custom policy
  </Step>

  <Step title="Name the Role">
    Name it something like `AuroraAccessRole`
  </Step>

  <Step title="Create Role">
    Click **Create role** and copy the Role ARN
  </Step>
</Steps>

### Step 3: Configure Aurora

<Steps>
  <Step title="Enter Role ARN">
    In Aurora UI, paste the Role ARN (e.g., `arn:aws:iam::123456789012:role/AuroraAccessRole`)
  </Step>

  <Step title="Optional: Read-Only Role">
    For Ask mode, optionally provide a separate read-only Role ARN
  </Step>

  <Step title="Test Connection">
    Click **Connect** to validate Aurora can assume the role
  </Step>

  <Step title="Verify Access">
    Aurora will call `sts:GetCallerIdentity` to verify the assumption works
  </Step>
</Steps>

## Trust Policy Example

The IAM role in your account should have a trust policy like this:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::AURORA_ACCOUNT_ID:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        }
      }
    }
  ]
}
```

Replace:

* `AURORA_ACCOUNT_ID`: Aurora's AWS account ID (shown in UI)
* `sts:ExternalId`: Your workspace's External ID (shown in UI)

## Permission Policies

### Read-Only Access (Ask Mode)

Use the AWS managed policy:

```
arn:aws:iam::aws:policy/ReadOnlyAccess
```

This allows Aurora to:

* Describe and list all AWS resources
* View configurations and metadata
* Read CloudWatch metrics and logs
* Cannot make any changes to your infrastructure

### Full Access (Do Mode)

Use AWS managed policy or create custom:

```
arn:aws:iam::aws:policy/PowerUserAccess
```

This allows Aurora to:

* Create, modify, and delete resources
* Manage EC2, EKS, RDS, Lambda, etc.
* Deploy applications and infrastructure
* Cannot modify IAM users/roles (for security)

For custom policies, include permissions for:

* `ec2:*`
* `eks:*`
* `rds:*`
* `s3:*`
* `lambda:*`
* `ecs:*`
* `cloudformation:*`
* `resource-explorer-2:Search`

## API Endpoints

### Check Environment

```http theme={null}
GET /aws/env/check
```

Returns whether Aurora has AWS credentials configured.

### Get Onboarding Info

```http theme={null}
GET /workspaces/{workspace_id}/aws/links
Headers: X-User-ID: your-user-id
```

Returns workspace External ID and Aurora account ID.

### Set Role ARN

```http theme={null}
POST /workspaces/{workspace_id}/aws/role
Headers: X-User-ID: your-user-id
Content-Type: application/json

{
  "roleArn": "arn:aws:iam::123456789012:role/AuroraAccessRole",
  "readOnlyRoleArn": "arn:aws:iam::123456789012:role/AuroraReadOnlyRole"
}
```

Validates role assumption and stores the role ARN.

### Get Connection Status

```http theme={null}
GET /workspaces/{workspace_id}/aws/status
Headers: X-User-ID: your-user-id
```

Returns current AWS connection status and configured role ARN.

### Disconnect AWS

```http theme={null}
POST /workspaces/{workspace_id}/aws/cleanup
Headers: X-User-ID: your-user-id
```

Removes AWS connection from Aurora (does not delete IAM role in your account).

## Troubleshooting

### Aurora Account Not Configured

**Error**: "Server configuration error: Unable to determine Aurora's AWS account ID"

**Solution**:

* Ensure Aurora has `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` configured
* Restart Aurora server after adding credentials
* Verify credentials are valid using `aws sts get-caller-identity`

### Access Denied

**Error**: "Access denied when assuming role"

**Solution**:

1. **Verify Trust Policy**: Ensure the role's trust policy includes Aurora's account ID
2. **Check External ID**: Confirm the External ID in the trust policy matches your workspace's External ID
3. **Validate Principal**: Trust policy principal should be `arn:aws:iam::AURORA_ACCOUNT_ID:root`
4. **Review IAM Permissions**: Aurora's credentials must have `sts:AssumeRole` permission
5. **Check Role Name**: Ensure the Role ARN is correct and the role exists

### Invalid Role ARN Format

**Error**: "Invalid role ARN format"

**Solution**:

* Role ARN must start with `arn:aws:iam::`
* Format: `arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME`
* Do not include session name or other suffixes

### Role Assumption Failed

**Error**: "AWS role assumption failed"

**Solution**:

1. Test the role assumption manually:
   ```bash theme={null}
   aws sts assume-role \
     --role-arn "arn:aws:iam::123456789012:role/AuroraAccessRole" \
     --role-session-name "test-session" \
     --external-id "your-external-id"
   ```
2. Check CloudTrail logs for detailed error messages
3. Verify the role has not been deleted
4. Ensure the role is in the correct AWS account

### Insufficient Permissions

**Error**: "Failed to list resources" or similar permission errors

**Solution**:

* Verify the role has the necessary permission policies attached
* For resource discovery, ensure `resource-explorer-2:Search` permission
* For EKS, ensure `eks:DescribeCluster` and `eks:ListClusters`
* Review CloudTrail for specific API calls that failed

### Session Token Expiration

**Error**: "Session token expired"

**Solution**:

* Aurora automatically refreshes session tokens (default 1 hour duration)
* If sessions expire prematurely, check for IAM policy duration limits
* Maximum session duration can be set on the IAM role (up to 12 hours)

## Security Considerations

* **External ID**: Always use the External ID provided by Aurora to prevent confused deputy attacks
* **Least Privilege**: Only grant the minimum permissions needed for your use case
* **Audit Logs**: Monitor CloudTrail for all actions performed by Aurora
* **Role Naming**: Use descriptive role names for easy identification in IAM
* **Rotation**: Regularly review and rotate Aurora's AWS credentials
* **Read-Only Mode**: Use separate read-only roles for Ask mode to limit blast radius

## Connection Storage

AWS connections are stored in the `user_connections` table with:

* **Provider**: `aws`
* **Account ID**: Extracted from Role ARN
* **Role ARN**: Full IAM role ARN
* **Read-Only Role ARN**: Optional separate role for Ask mode
* **Workspace External ID**: Stored in `workspaces` table for STS calls

## Next Steps

After connecting AWS:

1. Aurora will discover your AWS infrastructure using Resource Explorer 2
2. View discovered resources in the Aurora dashboard
3. Use Aurora's AI agent to manage AWS resources
4. Deploy applications to EKS clusters
5. Monitor costs and optimize resource usage