OIDC Configuration

Configure Stategraph to authenticate users via any OpenID Connect (OIDC) compatible identity provider.

Supported Providers

Any OIDC-compliant provider works, including:

Okta
Auth0
Azure Active Directory (Entra ID)
Keycloak
OneLogin
PingIdentity
AWS Cognito
GitLab

Basic Configuration

Required Environment Variables

# Enable OIDC
STATEGRAPH_OAUTH_TYPE=oidc

# Your OIDC provider's issuer URL
STATEGRAPH_OAUTH_OIDC_ISSUER_URL=https://your-provider.com

# OAuth client credentials
STATEGRAPH_OAUTH_CLIENT_ID=your-client-id
STATEGRAPH_OAUTH_CLIENT_SECRET=your-client-secret

# Your Stategraph URL
STATEGRAPH_UI_BASE=https://stategraph.example.com

Optional Environment Variables

# Restrict to email domain
STATEGRAPH_OAUTH_EMAIL_DOMAIN=yourcompany.com

# Custom login button text
STATEGRAPH_OAUTH_DISPLAY_NAME="Sign in with SSO"

# Callback URL base (if different from UI base)
STATEGRAPH_OAUTH_REDIRECT_BASE=https://stategraph.example.com

Provider-Specific Setup

Okta

Create Application

Go to Okta Admin Console
Navigate to Applications > Create App Integration
Select OIDC - OpenID Connect
Select Web Application
Configure:
App integration name: Stategraph
Grant type: Authorization Code
Sign-in redirect URIs: https://stategraph.example.com/oauth2/oidc/callback
Sign-out redirect URIs: https://stategraph.example.com
Save and copy Client ID and Client Secret

Configuration

STATEGRAPH_OAUTH_TYPE=oidc
STATEGRAPH_OAUTH_OIDC_ISSUER_URL=https://your-org.okta.com
STATEGRAPH_OAUTH_CLIENT_ID=0oaxxxxxxxxxxxxxx
STATEGRAPH_OAUTH_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Auth0

Create Application

Go to Auth0 Dashboard
Navigate to Applications > Create Application
Select Regular Web Applications
In Settings:
Allowed Callback URLs: https://stategraph.example.com/oauth2/oidc/callback
Allowed Logout URLs: https://stategraph.example.com
Copy Domain, Client ID, and Client Secret

Configuration

STATEGRAPH_OAUTH_TYPE=oidc
STATEGRAPH_OAUTH_OIDC_ISSUER_URL=https://your-tenant.auth0.com
STATEGRAPH_OAUTH_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
STATEGRAPH_OAUTH_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Azure AD (Entra ID)

Register Application

Go to Azure Portal > Azure Active Directory
Navigate to App registrations > New registration
Configure:
Name: Stategraph
Supported account types: Accounts in this organizational directory only
Redirect URI: Web - https://stategraph.example.com/oauth2/oidc/callback
After creation:
Copy Application (client) ID
Go to Certificates & secrets > New client secret
Copy the secret value

Configuration

STATEGRAPH_OAUTH_TYPE=oidc
STATEGRAPH_OAUTH_OIDC_ISSUER_URL=https://login.microsoftonline.com/{tenant-id}/v2.0
STATEGRAPH_OAUTH_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
STATEGRAPH_OAUTH_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Replace {tenant-id} with your Azure AD tenant ID.

Keycloak

Create Client

Go to Keycloak Admin Console
Select your realm
Navigate to Clients > Create client
Configure:
Client ID: stategraph
Client Protocol: openid-connect
Root URL: https://stategraph.example.com
After creation:
Set Valid Redirect URIs: https://stategraph.example.com/oauth2/oidc/callback
Enable Client authentication
Copy the client secret from Credentials tab

Configuration

STATEGRAPH_OAUTH_TYPE=oidc
STATEGRAPH_OAUTH_OIDC_ISSUER_URL=https://keycloak.example.com/realms/your-realm
STATEGRAPH_OAUTH_CLIENT_ID=stategraph
STATEGRAPH_OAUTH_CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

AWS Cognito

Create User Pool and App Client

Go to AWS Cognito Console
Create or select a User Pool
Navigate to App clients > Create app client
Configure:
App client name: stategraph
Enable Generate client secret
Under App integration > Domain, set up a Cognito domain or custom domain
Configure callback URL: https://stategraph.example.com/oauth2/oidc/callback

Configuration

STATEGRAPH_OAUTH_TYPE=oidc
STATEGRAPH_OAUTH_OIDC_ISSUER_URL=https://cognito-idp.{region}.amazonaws.com/{user-pool-id}
STATEGRAPH_OAUTH_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx
STATEGRAPH_OAUTH_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GitLab

Create Application

Go to GitLab > User Settings > Applications (Or Admin Area > Applications for instance-wide)
Configure:
Name: Stategraph
Redirect URI: https://stategraph.example.com/oauth2/oidc/callback
Scopes: openid, email, profile
Save and copy Application ID and Secret

Configuration

STATEGRAPH_OAUTH_TYPE=oidc
STATEGRAPH_OAUTH_OIDC_ISSUER_URL=https://gitlab.com
# Or your self-hosted GitLab URL
STATEGRAPH_OAUTH_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
STATEGRAPH_OAUTH_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Finding the Issuer URL

The issuer URL is the base URL of your OIDC provider. Most providers publish their configuration at:

{issuer_url}/.well-known/openid-configuration

For example: - Okta: https://your-org.okta.com/.well-known/openid-configuration - Auth0: https://your-tenant.auth0.com/.well-known/openid-configuration - Azure AD: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration

This endpoint returns the OIDC discovery document with authorization endpoints.

Docker Compose Example

services:
  server:
    image: ghcr.io/stategraph/stategraph-server:<version>
    environment:
      DB_HOST: "db"
      DB_PORT: "5432"
      DB_USER: "stategraph"
      DB_PASS: "stategraph"
      DB_NAME: "stategraph"

      STATEGRAPH_UI_BASE: "https://stategraph.example.com"

      STATEGRAPH_OAUTH_TYPE: "oidc"
      STATEGRAPH_OAUTH_OIDC_ISSUER_URL: "https://your-provider.com"
      STATEGRAPH_OAUTH_CLIENT_ID: "your-client-id"
      STATEGRAPH_OAUTH_CLIENT_SECRET: "${OIDC_CLIENT_SECRET}"
      STATEGRAPH_OAUTH_EMAIL_DOMAIN: "yourcompany.com"
      STATEGRAPH_OAUTH_DISPLAY_NAME: "Sign in with SSO"
    ports:
      - "8080:8080"

Troubleshooting

"Invalid issuer"

The issuer URL is incorrect or unreachable.

Solutions: - Verify the issuer URL is correct - Test with: curl {issuer_url}/.well-known/openid-configuration - Check network connectivity from Stategraph to the provider

"Invalid client"

The client ID or secret is incorrect.

Solutions: - Verify credentials from your provider's dashboard - Check for whitespace or newlines in values - Ensure the client hasn't been deleted or disabled

"Redirect URI mismatch"

The callback URL doesn't match what's configured in the provider.

Solutions: - The exact URL must match: https://stategraph.example.com/oauth2/oidc/callback - Check protocol (http vs https) - Check hostname and port - No trailing slash

"Access denied" after authentication

User was authenticated but denied access.

Solutions: - Check STATEGRAPH_OAUTH_EMAIL_DOMAIN setting - Verify user's email is in the allowed domain - Check provider's group/role assignments if applicable

Session not persisting

Cookies not being set correctly.

Solutions: - Verify STATEGRAPH_UI_BASE matches the access URL exactly - Use HTTPS in production - Check for proxy interference

Verifying Configuration

Test OIDC Discovery

curl https://your-provider.com/.well-known/openid-configuration | jq

Should return a JSON document with endpoints:

{
  "issuer": "https://your-provider.com",
  "authorization_endpoint": "https://your-provider.com/authorize",
  "token_endpoint": "https://your-provider.com/oauth/token",
  "userinfo_endpoint": "https://your-provider.com/userinfo",
  "jwks_uri": "https://your-provider.com/.well-known/jwks.json"
}

Check Stategraph Logs

docker compose logs server | grep -i oauth

Look for errors or successful authentication messages.

Security Best Practices

Use HTTPS for both Stategraph and callback URLs
Restrict email domains to your organization
Use secrets management for client secrets
Enable MFA at the identity provider level
Regular audits of authorized users
Rotate client secrets periodically

Next Steps

Google OAuth Setup for Google-specific features
Environment Variables Reference
API Reference