Skip to main content

SSO / OIDC Integration (Pro)

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​

ProviderTestedNotes
OktaYesFull support including groups sync
Auth0YesFull support
KeycloakYesFull support, self-hosted
Azure AD / Entra IDYesEnterprise plan
Google WorkspaceYesBasic OIDC
Any OIDC-compliant providerYesStandard 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/RoleChainLaunch RolePermissions
chainlaunch-adminsADMINFull access
chainlaunch-operatorsOPERATORManage nodes and networks
chainlaunch-viewersVIEWERRead-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​