Skip to main content

​
Overview

Aurora provides token management capabilities for both user authentication and cloud provider credentials. This includes password management and secure token storage using HashiCorp Vault.

​
Change Password

​
Endpoint

POST /api/auth/change-password
Allows authenticated users to change their password.

​
Headers

​
X-User-ID
string
required
User ID from Auth.js session

​
Request Body

​
currentPassword
string
required
User’s current password
​
newPassword
string
required
New password (minimum 8 characters)

​
Response

​
message
string
Success message confirming password change

​
Example Request

cURL
curl -X POST http://localhost:5080/api/auth/change-password \
  -H "Content-Type: application/json" \
  -H "X-User-ID: user-123" \
  -d '{
    "currentPassword": "oldPassword123",
    "newPassword": "newSecurePassword456"
  }'
JavaScript
const response = await fetch('http://localhost:5080/api/auth/change-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-User-ID': 'user-123',
  },
  body: JSON.stringify({
    currentPassword: 'oldPassword123',
    newPassword: 'newSecurePassword456',
  }),
});

const data = await response.json();
Python
import requests

response = requests.post(
    'http://localhost:5080/api/auth/change-password',
    headers={
        'Content-Type': 'application/json',
        'X-User-ID': 'user-123'
    },
    json={
        'currentPassword': 'oldPassword123',
        'newPassword': 'newSecurePassword456'
    }
)

data = response.json()

​
Example Response

{
  "message": "Password changed successfully"
}

​
Cloud Provider Token Management

Aurora securely manages cloud provider credentials using HashiCorp Vault.

​
Token Storage Architecture

  1. Vault Storage: Credentials stored in Vault’s KV v2 engine
  2. Database References: Only secret references stored in PostgreSQL
  3. Token Refresh: Automatic refresh for OAuth2 tokens (GCP, Azure)
  4. Encryption: All credentials encrypted at rest in Vault

​
Supported Providers

  • GCP: OAuth2 tokens with automatic refresh
  • AWS: IAM role assumption with STS credentials
  • Azure: Service principal credentials
  • Other Providers: Grafana, Datadog, Netdata, Scaleway, Tailscale, Splunk, Slack, Coroot, Bitbucket, ThousandEyes

​
Token Storage

Tokens are stored using the store_tokens_in_db function: 
from utils.auth.token_management import store_tokens_in_db

# Store GCP OAuth2 tokens
store_tokens_in_db(
    user_id="user-123",
    token_data={
        "access_token": "ya29.a0...",
        "refresh_token": "1//0g...",
        "expires_at": 1234567890,
        "email": "[email protected]"
    },
    provider="gcp"
)

# Store AWS credentials
store_tokens_in_db(
    user_id="user-123",
    token_data={
        "role_arn": "arn:aws:iam::123456789012:role/AuroraAccess",
        "external_id": "unique-external-id"
    },
    provider="aws"
)

# Store Azure credentials
store_tokens_in_db(
    user_id="user-123",
    token_data={
        "tenant_id": "tenant-uuid",
        "client_id": "client-uuid",
        "client_secret": "secret-value"
    },
    provider="azure",
    subscription_name="Production Subscription",
    subscription_id="sub-uuid"
)

​
Token Retrieval

Retrieve tokens using the get_token_data function: 
from utils.auth.token_management import get_token_data

# Get tokens for a specific provider
token_data = get_token_data(
    user_id="user-123",
    provider="gcp"
)

# Get tokens from multiple providers (first match)
token_data = get_token_data(
    user_id="user-123",
    provider=["gcp", "aws", "azure"]
)

​
Token Refresh

OAuth2 tokens are automatically refreshed: 
from utils.auth.token_refresh import refresh_token_if_needed

# Automatically refresh if expiring within 5 minutes
token_data = refresh_token_if_needed(
    user_id="user-123",
    provider="gcp"
)

​
Vault Configuration

Configure Vault using environment variables: 
# Vault server address
VAULT_ADDR=http://vault:8200

# Vault access token
VAULT_TOKEN=hvs.your-vault-token

# KV mount path (default: aurora)
VAULT_KV_MOUNT=aurora

# KV base path (default: users)
VAULT_KV_BASE_PATH=users

​
Secret References

Vault secrets are referenced in the database: 
vault:kv/data/aurora/users/aurora-dev-user123-gcp-token
The secret reference format:
  • vault: prefix indicates Vault storage
  • kv/data/ is the KV v2 API path
  • aurora/users/ is the base path
  • aurora-dev-user123-gcp-token is the secret name

​
Security Best Practices

​
Password Security

  1. Strong Passwords: Enforce minimum 8-character passwords
  2. Bcrypt Hashing: Use bcrypt with automatic salt generation
  3. No Plaintext: Never store or log passwords in plaintext
  4. Rate Limiting: Implement rate limiting on password change endpoint

​
Token Security

  1. Vault Storage: Store all credentials in Vault, not database
  2. Encryption: Enable encryption at rest in Vault
  3. Access Control: Use Vault policies to restrict access
  4. Secret Rotation: Regularly rotate credentials
  5. Audit Logging: Enable Vault audit logs

​
Error Handling

Status CodeDescription
200Operation successful
400Invalid request (validation error)
401Authentication required or invalid
404User or resource not found
500Internal server error

Authentication Overview

Learn about authentication

Login

Authenticate users

Vault Integration

HashiCorp Vault setup

Build docs developers (and LLMs) love

Get started for freeTalk to us