Amazon Web Services (AWS)

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

AWS Account

You need an AWS account with administrative access

Aurora AWS Account

Aurora must have AWS credentials configured (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)

IAM Permissions

You need permissions to create IAM roles and trust policies in your AWS account

Environment Variables

Configure these environment variables in Aurora’s .env file:

# 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

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.

Authentication Flow

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

Create IAM Role

In your AWS account, create an IAM role with a trust policy that allows Aurora to assume it

Configure External ID

Use the External ID provided by Aurora in the workspace settings (prevents confused deputy attacks)

Attach Policies

Attach necessary IAM policies to the role (ReadOnlyAccess for Ask mode, PowerUserAccess for Do mode)

Provide Role ARN

Enter the Role ARN in Aurora’s UI

Validate Assumption

Aurora validates it can assume the role using STS AssumeRole API

Store Connection

Role ARN is stored in the user_connections table (single source of truth)

Setup Instructions

Step 1: Get Your External ID

Open Aurora Workspace Settings

Navigate to your workspace in the Aurora UI

Find AWS Section

Go to the AWS integration settings

Copy External ID

Copy the External ID displayed (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890)

Step 2: Create IAM Role in AWS Console

Open IAM Console

Go to AWS IAM Console > Roles > Create role

Select Trusted Entity

Choose AWS account as the trusted entity type

Enter Aurora Account ID

Enter Aurora’s AWS account ID (displayed in the Aurora UI)

Require External ID

Check Require external ID and paste the External ID from Aurora

Attach Permissions

For Ask mode (read-only): Attach ReadOnlyAccess managed policyFor Do mode (full management): Attach PowerUserAccess or create a custom policy

Name the Role

Name it something like AuroraAccessRole

Create Role

Click Create role and copy the Role ARN

Step 3: Configure Aurora

Enter Role ARN

In Aurora UI, paste the Role ARN (e.g., arn:aws:iam::123456789012:role/AuroraAccessRole)

Optional: Read-Only Role

For Ask mode, optionally provide a separate read-only Role ARN

Test Connection

Click Connect to validate Aurora can assume the role

Verify Access

Aurora will call sts:GetCallerIdentity to verify the assumption works

Trust Policy Example

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

{
  "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

GET /aws/env/check

Returns whether Aurora has AWS credentials configured.

Get Onboarding Info

GET /workspaces/{workspace_id}/aws/links
Headers: X-User-ID: your-user-id

Returns workspace External ID and Aurora account ID.

Set Role ARN

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

GET /workspaces/{workspace_id}/aws/status
Headers: X-User-ID: your-user-id

Returns current AWS connection status and configured role ARN.

Disconnect AWS

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:

Verify Trust Policy: Ensure the role’s trust policy includes Aurora’s account ID
Check External ID: Confirm the External ID in the trust policy matches your workspace’s External ID
Validate Principal: Trust policy principal should be arn:aws:iam::AURORA_ACCOUNT_ID:root
Review IAM Permissions: Aurora’s credentials must have sts:AssumeRole permission
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:

Test the role assumption manually:

aws sts assume-role \
  --role-arn "arn:aws:iam::123456789012:role/AuroraAccessRole" \
  --role-session-name "test-session" \
  --external-id "your-external-id"

Check CloudTrail logs for detailed error messages
Verify the role has not been deleted
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:

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

Get Started

Core Features

Architecture

Deployment

Configuration

Integrations

Cloud Providers

Observability

Development

Guides

Reference

Help

​Overview

​What Aurora Can Access

​Prerequisites

​Environment Variables

​Authentication Flow

​Setup Instructions

​Step 1: Get Your External ID

​Step 2: Create IAM Role in AWS Console

​Step 3: Configure Aurora

​Trust Policy Example

​Permission Policies

​Read-Only Access (Ask Mode)

​Full Access (Do Mode)

​API Endpoints

​Check Environment

​Get Onboarding Info

​Set Role ARN

​Get Connection Status

​Disconnect AWS

​Troubleshooting

​Aurora Account Not Configured

​Access Denied

​Invalid Role ARN Format

​Role Assumption Failed

​Insufficient Permissions

​Session Token Expiration

​Security Considerations

​Connection Storage

​Next Steps

Build docs developers (and LLMs) love

Overview

What Aurora Can Access

Prerequisites

Environment Variables

Authentication Flow

Setup Instructions

Step 1: Get Your External ID

Step 2: Create IAM Role in AWS Console

Step 3: Configure Aurora

Trust Policy Example

Permission Policies

Read-Only Access (Ask Mode)

Full Access (Do Mode)

API Endpoints

Check Environment

Get Onboarding Info

Set Role ARN

Get Connection Status

Disconnect AWS

Troubleshooting

Aurora Account Not Configured

Access Denied

Invalid Role ARN Format

Role Assumption Failed

Insufficient Permissions

Session Token Expiration

Security Considerations

Connection Storage

Next Steps