Skip to main content

​
Overview

Aurora integrates with Google Cloud Platform using OAuth 2.0 to securely access your GCP projects. Once connected, Aurora can manage GKE clusters, Cloud Run services, and other GCP resources across all your projects.

​
What Aurora Can Access

Once authenticated, Aurora can discover and manage:
  • GKE Clusters: Kubernetes clusters in Google Kubernetes Engine
  • Cloud Run Services: Serverless container deployments
  • Compute Engine: VM instances and instance groups
  • Cloud Storage: Buckets and objects
  • Cloud Functions: Serverless functions
  • BigQuery: Data warehouse and analytics
  • Cloud SQL: Managed database instances
  • VPC Networks: Virtual Private Cloud networking
  • IAM: Service accounts and permissions
  • Billing: Project billing information and usage

​
Prerequisites

1

GCP Account

You need a Google Cloud Platform account with at least one active project
2

Billing Enabled

At least one project must have billing enabled for Aurora to manage resources
3

Required Permissions

You need Owner or Editor role on your GCP projects to grant Aurora the necessary permissions

​
Environment Variables

Configure these environment variables in Aurora’s .env file: 
# Google Cloud OAuth Credentials (from Google Cloud Console)
CLIENT_ID=your-google-oauth-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-google-oauth-client-secret

# Backend URL for OAuth callbacks
NEXT_PUBLIC_BACKEND_URL=https://your-aurora-backend.com

# Frontend URL for post-auth redirects
FRONTURL=https://your-aurora-frontend.com/chat

​
Creating OAuth Credentials

1

Open Google Cloud Console

Go to Google Cloud Console and select your project
2

Enable APIs

Navigate to APIs & Services > Library and enable:
  • Google Cloud Resource Manager API
  • Identity and Access Management (IAM) API
  • Service Usage API
3

Create OAuth Client

Go to APIs & Services > Credentials and click Create Credentials > OAuth client ID
4

Configure OAuth Consent Screen

If prompted, configure the OAuth consent screen with your application details
5

Set Application Type

Choose Web application as the application type
6

Add Authorized Redirect URIs

Add your Aurora backend callback URL:
https://your-aurora-backend.com/callback
7

Save Credentials

Copy the Client ID and Client Secret to your .env file

​
Authentication Flow

Aurora uses the OAuth 2.0 authorization code flow for GCP authentication:
1

User Initiates Login

Click the “Connect GCP” button in Aurora’s UI
2

Redirect to Google

Aurora redirects you to Google’s OAuth consent page
3

Grant Permissions

Review and grant Aurora the requested permissions:
  • https://www.googleapis.com/auth/cloud-platform (Full GCP access)
  • https://www.googleapis.com/auth/userinfo.email (Email address)
  • openid (OpenID Connect authentication)
4

Authorization Code Exchange

Google redirects back to Aurora with an authorization code
5

Token Storage

Aurora exchanges the code for access and refresh tokens, storing them securely in HashiCorp Vault
6

Post-Auth Setup

Aurora automatically performs setup tasks:
  • Validates projects and billing status
  • Enables required APIs (25 APIs across all projects)
  • Creates Aurora service accounts for secure access
  • Configures IAM permissions
  • Updates organization policies for Cloud Run public access
  • Verifies permission propagation
  • Triggers infrastructure discovery

​
Post-Authentication Setup

After OAuth callback, Aurora runs an asynchronous Celery task (gcp_post_auth_setup_task) that:

​
1. Project Validation

  • Fetches all accessible GCP projects
  • Filters projects with active billing
  • If more than 5 eligible projects, prompts for manual selection

​
2. API Enablement

Enables 25 required Google Cloud APIs across all selected projects:
  • Cloud Resource Manager API
  • Compute Engine API
  • Kubernetes Engine API
  • Cloud Run Admin API
  • Cloud Functions API
  • Cloud Storage API
  • Cloud SQL Admin API
  • Cloud Billing API
  • IAM API
  • Service Usage API
  • And 15+ more services

​
3. Service Account Creation

  • Creates Aurora-managed service accounts in your root project
  • Grants necessary IAM roles across all projects
  • Configures service account impersonation

​
4. Organization Policy Updates

  • Updates org policies to allow Cloud Run public access (allUsers principal)
  • Configures domain-restricted sharing policies if needed

​
5. Permission Verification

  • Verifies service account permissions have propagated (max 20 attempts, 30s intervals)
  • Tests token generation for each project
  • Reports partial or full verification status

​
Root Project Selection

Aurora automatically selects a “root project” for service account creation using this priority:
  1. User Preference: Previously selected root project (stored in user_preferences table)
  2. Billing + IAM: First project with both billing enabled and IAM permissions
  3. Fallback: First accessible project
You can override the root project selection through the Aurora UI.

​
API Endpoints

​
Login

POST /login
Content-Type: application/json

{
  "userId": "user-id-here"
}
Returns OAuth authorization URL with state parameter for CSRF protection.

​
OAuth Callback

GET /callback?code=AUTH_CODE&state=USER_ID
Handles OAuth callback, exchanges code for tokens, and triggers post-auth setup.

​
Setup Status

GET /gcp/setup/status/{task_id}
Checks the progress of post-authentication setup tasks.

​
Force Disconnect

POST /api/gcp/force-disconnect
Headers: X-User-ID: your-user-id
Removes GCP tokens and clears cached credentials.

​
Troubleshooting

​
No Projects Found

Error: “No GCP projects found during login” Solution: Ensure you have at least one GCP project in your account. Create one at Google Cloud Console.

​
No Billing Enabled

Error: “No GCP project with active billing found” Solution: Enable billing on at least one project:
  1. Go to Billing in Google Cloud Console
  2. Link a billing account to your project
  3. Verify billing is active

​
Token Refresh Failed

Error: “No refresh token available. Please re-authenticate.” Solution:
  • Re-authenticate through the Aurora UI
  • Ensure OAuth consent screen includes access_type=offline and prompt=consent parameters
  • Check that refresh tokens are being stored in Vault

​
API Enablement Errors

Error: “Error enabling required APIs” Solution:
  1. Verify you have Service Usage Admin role
  2. Check project quotas and limits
  3. Manually enable APIs through Cloud Console if needed
  4. Wait a few minutes for API propagation

​
Permission Propagation Timeout

Warning: “Propagation verification: PARTIAL (X/Y projects)” Solution:
  • IAM permissions can take up to 10 minutes to propagate
  • Aurora will retry automatically (20 attempts over ~10 minutes)
  • If partial verification persists, check service account IAM bindings manually
  • Some projects may have org policies blocking service account access

​
Organization Policy Conflicts

Error: “Org Policy update failed for some projects” Solution:
  1. Check if your organization has strict domain policies
  2. Verify you have Organization Policy Administrator role if using org-level policies
  3. Some projects may inherit conflicting policies from parent folders/organizations
  4. You may need to manually update iam.allowedPolicyMemberDomains constraint

​
Service Account Errors

Error: “Aurora full-access setup had errors” Solution:
  • Verify you have Service Account Admin and Project IAM Admin roles
  • Check project-level IAM permissions
  • Ensure service accounts can be created in the root project
  • Review Cloud Console audit logs for detailed error messages

​
Security Considerations

  • Tokens: Access and refresh tokens are stored securely in HashiCorp Vault with encryption at rest
  • Scopes: Aurora requests cloud-platform scope for full GCP access - review carefully before granting
  • Service Accounts: Aurora creates service accounts in your projects - audit them regularly
  • IAM Roles: Review the roles granted to Aurora service accounts in your IAM policies
  • Org Policies: Aurora may modify organization policies for Cloud Run - review changes in your org policy logs

​
Token Management

  • Access Tokens: Valid for ~1 hour, automatically refreshed using refresh tokens
  • Refresh Tokens: Long-lived, stored securely, used to obtain new access tokens
  • Token Rotation: Aurora automatically handles token refresh when access tokens expire
  • Cache Invalidation: Redis cache is cleared after OAuth reconnect to ensure fresh credentials

​
Required OAuth Scopes

https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/userinfo.email
openid

​
Next Steps

After connecting GCP:
  1. Aurora will automatically discover your infrastructure
  2. View discovered resources in the Aurora dashboard
  3. Use Aurora’s AI agent to manage GCP resources
  4. Deploy applications to GKE clusters or Cloud Run
  5. Monitor costs and optimize resource usage

Build docs developers (and LLMs) love

Get started for freeTalk to us