ChainLaunch
Pro Feature

SSO / OIDC Integration

SSO and OIDC integration requires ChainLaunch Pro. Learn more about Pro features.

ChainLaunch Pro Feature

SSO and OIDC integration requires ChainLaunch Pro. Learn more about Pro features.

ChainLaunch Pro supports Single Sign-On via OpenID Connect (OIDC), letting your team log in with their existing identity provider.

Supported Providers

Provider Tested Notes
Okta Yes Full support including groups sync
Auth0 Yes Full support
Keycloak Yes Full support, self-hosted
Azure AD / Entra ID Yes Enterprise plan
Google Workspace Yes Basic OIDC
Any OIDC-compliant provider Yes Standard OIDC discovery

Configuration

Environment Variables

# Enable OIDC
export CHAINLAUNCH_OIDC_ENABLED=true
 
# Provider settings
export CHAINLAUNCH_OIDC_ISSUER_URL=https://your-provider.com
export CHAINLAUNCH_OIDC_CLIENT_ID=your-client-id
export CHAINLAUNCH_OIDC_CLIENT_SECRET=your-client-secret
export CHAINLAUNCH_OIDC_REDIRECT_URL=http://localhost:8100/api/v1/auth/callback
 
# Optional: Restrict to specific domain
export CHAINLAUNCH_OIDC_ALLOWED_DOMAINS=yourcompany.com

Provider-Specific Setup

Okta

  1. In Okta Admin, go to Applications > Create App Integration
  2. Select OIDC - OpenID Connect > Web Application
  3. Set the redirect URI: https://your-chainlaunch.com/api/v1/auth/callback
  4. Copy the Client ID and Client Secret
  5. Note the Issuer URL: https://your-org.okta.com
export CHAINLAUNCH_OIDC_ISSUER_URL=https://your-org.okta.com
export CHAINLAUNCH_OIDC_CLIENT_ID=0oaxxxxxxxx
export CHAINLAUNCH_OIDC_CLIENT_SECRET=xxxxxxxx

Auth0

  1. In Auth0 Dashboard, go to Applications > Create Application
  2. Select Regular Web Applications
  3. Set Allowed Callback URL: https://your-chainlaunch.com/api/v1/auth/callback
  4. Copy Domain, Client ID, Client Secret
export CHAINLAUNCH_OIDC_ISSUER_URL=https://your-tenant.auth0.com/
export CHAINLAUNCH_OIDC_CLIENT_ID=xxxxxxxx
export CHAINLAUNCH_OIDC_CLIENT_SECRET=xxxxxxxx

Keycloak

  1. In Keycloak Admin, create a new Client in your realm
  2. Set Access Type: confidential
  3. Set Valid Redirect URIs: https://your-chainlaunch.com/api/v1/auth/callback
  4. Copy Client ID and Secret from the Credentials tab
export CHAINLAUNCH_OIDC_ISSUER_URL=https://keycloak.yourcompany.com/realms/your-realm
export CHAINLAUNCH_OIDC_CLIENT_ID=chainlaunch
export CHAINLAUNCH_OIDC_CLIENT_SECRET=xxxxxxxx

Role Mapping

ChainLaunch maps OIDC groups/roles to its internal RBAC roles:

OIDC Group/Role ChainLaunch Role Permissions
chainlaunch-admins ADMIN Full access
chainlaunch-operators OPERATOR Manage nodes and networks
chainlaunch-viewers VIEWER Read-only access

Configure the group claim name:

export CHAINLAUNCH_OIDC_GROUPS_CLAIM=groups  # default
# Or for Auth0:
export CHAINLAUNCH_OIDC_GROUPS_CLAIM=https://your-namespace/roles

User Provisioning

When a user logs in via OIDC for the first time, ChainLaunch automatically creates a local account with the role mapped from their OIDC groups.

  • If no group matches, the user gets VIEWER role by default
  • Admins can override roles manually in Settings > Users
  • Users removed from the identity provider cannot log in on next attempt

Disabling Local Auth

Once SSO is configured, you can disable username/password login:

export CHAINLAUNCH_LOCAL_AUTH_DISABLED=true

Warning

Keep at least one local admin account as a break-glass emergency login. You can re-enable local auth via environment variable if OIDC fails.

Verify Configuration

# Check OIDC discovery endpoint
curl https://your-provider.com/.well-known/openid-configuration | jq
 
# Test login flow
# Open in browser: http://localhost:8100/login
# You should be redirected to your identity provider

Next Steps