Authentication

Stategraph supports OAuth 2.0 authentication to secure access to the UI and API.

Overview

Without authentication configured, Stategraph is accessible to anyone with network access. For production deployments, you should configure authentication.

Stategraph supports three authentication modes:

Authentication Flow

┌──────────┐     ┌─────────────┐     ┌──────────────┐     ┌────────────────┐
│  User    │────▶│  Stategraph │────▶│ OAuth2 Proxy │────▶│ OAuth Provider │
│  Browser │     │     UI      │     │              │     │ (Google/OIDC)  │
└──────────┘     └─────────────┘     └──────────────┘     └────────────────┘
     │                                      │                     │
     │                                      │◀─── Token ──────────│
     │◀─── Session Cookie ──────────────────│
     │
     │ Authenticated requests
     ▼
┌─────────────┐
│  Stategraph │
│     API     │
└─────────────┘

1. User accesses Stategraph
2. If not authenticated, redirected to OAuth provider
3. User authenticates with their identity provider
4. Provider returns token to oauth2-proxy
5. Stategraph creates the user (if new) and adds them to the Default tenant
6. Session cookie set in browser
7. Subsequent requests include session cookie

New User Onboarding

When a user logs in via OAuth for the first time:

1. User account created - Stategraph creates a user record linked to the OAuth identity
2. Added to Default tenant - The user is automatically added to the shared "Default" tenant
3. Ready to use - The user can immediately access states and create API keys

All users share the Default tenant, making collaboration simple. This means new users can immediately start using Stategraph after their first login. To use the CLI or Terraform:

1. Log in via OAuth in your browser
2. Go to Settings and create an API key
3. Use the API key with STATEGRAPH_API_KEY environment variable

Quick Configuration

Google OAuth

# Required
STATEGRAPH_OAUTH_TYPE=google
STATEGRAPH_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
STATEGRAPH_OAUTH_CLIENT_SECRET=your-client-secret

# Optional
STATEGRAPH_OAUTH_EMAIL_DOMAIN=yourcompany.com  # Restrict to domain
STATEGRAPH_OAUTH_DISPLAY_NAME="Sign in with Google"

Detailed Google OAuth setup

Generic OIDC

# Required
STATEGRAPH_OAUTH_TYPE=oidc
STATEGRAPH_OAUTH_CLIENT_ID=your-client-id
STATEGRAPH_OAUTH_CLIENT_SECRET=your-client-secret
STATEGRAPH_OAUTH_OIDC_ISSUER_URL=https://your-provider.com

# Optional
STATEGRAPH_OAUTH_EMAIL_DOMAIN=yourcompany.com
STATEGRAPH_OAUTH_DISPLAY_NAME="Sign in with SSO"

Detailed OIDC setup

Authentication Components

UI Authentication

Web browser access is authenticated via cookies:

1. User clicks login button
2. Redirected to OAuth provider
3. After authentication, session cookie is set
4. Cookie is sent with each request

API Authentication

The Stategraph API accepts two authentication methods:

API Key (Bearer Token): For CLI, Terraform, and programmatic access

curl -H "Authorization: Bearer $STATEGRAPH_API_KEY" http://localhost:8080/api/v1/...

Session Cookie: For browser-based access (handled automatically by the browser)

Terraform Authentication

Terraform uses HTTP Basic Auth with API keys:

terraform {
  backend "http" {
    username = "session"
    password = "<your-api-key>"
  }
}

API Keys

Stategraph supports two types of API credentials:

Both types generate tokens that do not expire.

Personal API Keys

Personal API keys are tied to your OAuth user account. Good for CLI access and personal use.

Via UI (recommended): 1. Log in to Stategraph via OAuth 2. Navigate to Settings 3. In the API Keys section, click Create API Key 4. Copy the generated token (it's only shown once)

Via API (requires active browser session):

curl -X POST http://localhost:8080/api/v1/user/access-tokens \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -d '{"name": "my-api-key"}'

Response:

{"token": "<your-api-key>"}

Service Accounts

Service accounts are dedicated API identities for CI/CD pipelines. Unlike personal API keys, service accounts:

• Are separate user identities (type: api)
• Survive employee turnover
• Provide clear audit trails ("ci-production" made this change vs "john@example.com")
• Can be managed independently from human users

Via UI: 1. Log in to Stategraph via OAuth 2. Navigate to Settings 3. In the Service Accounts section, enter a name (e.g., "ci-production", "github-actions") 4. Click Create 5. Copy the generated token (it's only shown once)

Via API:

curl -X POST http://localhost:8080/api/v1/api-users \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -d '{"name": "ci-production", "tenant_id": "<tenant-uuid>"}'

Response:

{"user_id": "<uuid>", "token": "<your-api-key>"}

Recommendation: Use service accounts for CI/CD pipelines and shared automation. Use personal API keys for individual CLI access.

Using API Keys

With the CLI:

export STATEGRAPH_API_KEY="<your-api-key>"
stategraph tenant list

With the API:

curl -H "Authorization: Bearer $STATEGRAPH_API_KEY" http://localhost:8080/api/v1/...

With Terraform:

terraform {
  backend "http" {
    username = "session"
    password = "<your-api-key>"
  }
}

Token Properties

• Tokens require no prefix (use directly as Bearer token)
• Tokens do not expire
• Each token creates audit trail entries
• Tokens cannot be listed or revoked after creation

CI/CD Setup

For CI/CD pipelines, we recommend using service accounts instead of personal API keys:

1. Create a service account: Log in to Stategraph UI, go to Settings > Service Accounts, and create one (e.g., "github-actions")
2. Store as secret: Add the token as a secret in your CI/CD platform (e.g., STATEGRAPH_API_KEY)
3. Configure the pipeline: Set the environment variable

# GitHub Actions example
env:
  STATEGRAPH_API_BASE: https://stategraph.example.com
  STATEGRAPH_API_KEY: ${{ secrets.STATEGRAPH_API_KEY }}

# For Terraform
env:
  TF_HTTP_PASSWORD: ${{ secrets.STATEGRAPH_API_KEY }}

Using a service account instead of a personal API key means: - The token remains valid even if the employee who created it leaves - Audit logs clearly show "github-actions" made the change, not a person's name - You can create separate service accounts for different pipelines (staging vs production)

Email Domain Restriction

Limit access to specific email domains:

# Single domain
STATEGRAPH_OAUTH_EMAIL_DOMAIN=yourcompany.com

# Allow all domains
STATEGRAPH_OAUTH_EMAIL_DOMAIN=*

Users with email addresses outside the allowed domain will be denied access.

Redirect URLs

The OAuth redirect URL must be configured in your OAuth provider. The URL includes the provider type:

For Google OAuth:

https://stategraph.example.com/oauth2/google/callback

For OIDC providers:

https://stategraph.example.com/oauth2/oidc/callback

If using a different base URL or port, set:

STATEGRAPH_OAUTH_REDIRECT_BASE=https://stategraph.example.com

Troubleshooting

"Invalid redirect URI"

The callback URL in your OAuth provider doesn't match. Verify: - Protocol (http vs https) - Hostname matches STATEGRAPH_UI_BASE - Path is /oauth2/google/callback (for Google) or /oauth2/oidc/callback (for OIDC)

"Access denied"

Check: - Email domain restrictions - User is in allowed group (Google Groups) - OAuth app is approved in organization

Session not persisting

Verify: - Cookies are enabled in browser - STATEGRAPH_UI_BASE matches the URL you're accessing - No proxy stripping cookies

Security Considerations

1. Use HTTPS in production
2. Restrict email domains to your organization
3. API keys do not expire - treat them as long-lived secrets
4. Audit token usage via transaction logs
5. Don't commit API keys to version control

Next Steps

• Local Authentication - Email/password authentication with user management
• Google OAuth Setup - For Google Workspace organizations
• OIDC Setup - For other identity providers
• Environment Variables Reference