Authentication quickstart

Overview

Configure single sign-on (SSO) authentication with OIDC, OAuth2, or SAML 2.0 providers. This guide covers the essential steps to get authentication working quickly.

Choose your provider type

OIDC

RecommendedGoogle, Okta, Auth0, Azure AD, Keycloak

OAuth2

Legacy providersGitHub, GitLab, custom OAuth2

SAML 2.0

EnterpriseOkta, OneLogin, Azure AD

Quick setup

Step 1: Enable database-backed providers

Set the environment variable:

AUTH_PROVIDERS_SOURCE=db

Restart your application.

Step 2: Create OAuth credentials in your IdP

Google
Okta
Azure AD

Go to Google Cloud Console
Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
Select Web application

Add redirect URI:

https://your-domain.com/auth/openid_connect/callback

Copy the Client ID and Client Secret

Log in to Okta admin console
Go to Applications → Create App Integration
Select OIDC - OpenID Connect
Choose Web Application

Add redirect URI:

https://your-domain.com/auth/openid_connect/callback

Copy the Client ID and Client Secret

Go to Azure Portal
Navigate to Microsoft Entra ID → App registrations
Click New registration

Add redirect URI:

https://your-domain.com/auth/openid_connect/callback

Go to Certificates & secrets and create a client secret
Copy the Application ID and Client Secret

Step 3: Configure in admin UI

Navigate to /admin/sso_providers in your application
Click Add Provider
Fill in the details:

Provider name: Google Workspace
Provider ID: google
Strategy: openid_connect

Issuer URL: https://accounts.google.com
Client ID: [your-client-id]
Client Secret: [your-client-secret]
Scopes: openid profile email

Click Save

Step 4: Test the integration

Log out of your application
You should see a “Sign in with Google” button (or your provider name)
Click it and complete the authentication flow
You should be logged in successfully

Configuration options

Disable local email/password login to enforce SSO-only:

AUTH_LOCAL_LOGIN_ENABLED=false

Keep an emergency admin override:

AUTH_LOCAL_LOGIN_ENABLED=false
AUTH_LOCAL_ADMIN_OVERRIDE_ENABLED=true

JIT user provisioning

Control how new users are created:

# Allow account creation for any verified email (default)
AUTH_JIT_MODE=create_and_link

# Only link to existing users, no new account creation
AUTH_JIT_MODE=link_only

# Restrict to specific email domains
ALLOWED_OIDC_DOMAINS=example.com,company.com

Role mapping

Configure default roles for new users in the admin UI under Role Mapping:

Default Role: member (assigned to all new users)
Group Mappings: Map IdP groups to application roles

Example:

IdP Group: admin@company.com → Role: super_admin
IdP Group: developers@company.com → Role: admin

Common configurations

Pure SSO-only mode

AUTH_LOCAL_LOGIN_ENABLED=false
AUTH_LOCAL_ADMIN_OVERRIDE_ENABLED=false
AUTH_JIT_MODE=create_and_link

Users can only log in via SSO. No local passwords.

Hybrid mode (local + SSO)

AUTH_LOCAL_LOGIN_ENABLED=true
AUTH_JIT_MODE=create_and_link

Users can choose between local login or SSO.

Enterprise mode (restricted domains)

AUTH_LOCAL_LOGIN_ENABLED=false
AUTH_JIT_MODE=link_only
ALLOWED_OIDC_DOMAINS=company.com

Only users with @company.com emails can authenticate, and they must be pre-created by an admin.

Bootstrap first admin

The first super admin must be set via Rails console:

bin/rails console

User.find_by(email: "admin@example.com").update!(role: :super_admin)

Once set, super admins can promote other users via the web UI at /admin/users.

Troubleshooting

Verify AUTH_PROVIDERS_SOURCE=db is set
Check that the provider is enabled in /admin/sso_providers
Restart the application after setting environment variables

Authentication fails

Verify the redirect URI matches exactly in both systems
Check that client ID and secret are correct
Ensure the issuer URL is accessible from your server
Review logs at /admin/sso_audit_logs

User not created automatically

Check AUTH_JIT_MODE is set to create_and_link
Verify the email domain is allowed (if ALLOWED_OIDC_DOMAINS is set)
Ensure the IdP returns a verified email address
Check audit logs for JIT provisioning errors

Next steps

In-depth guide

Complete authentication reference with advanced features

User management

Manage users, roles, and connected accounts

Getting started

Key concepts

App features

Development

Authentication

Third party providers

Knowledge Base

Overview

Choose your provider type

OIDC

OAuth2

SAML 2.0

Quick setup

Step 1: Enable database-backed providers

Step 2: Create OAuth credentials in your IdP

Step 3: Configure in admin UI

Step 4: Test the integration

Configuration options

JIT user provisioning

Role mapping

Common configurations

Pure SSO-only mode

Hybrid mode (local + SSO)

Enterprise mode (restricted domains)

Bootstrap first admin

Troubleshooting

Authentication fails

User not created automatically

Next steps

In-depth guide

User management

​Overview

​Choose your provider type

OIDC

OAuth2

SAML 2.0

​Quick setup

​Step 1: Enable database-backed providers

​Step 2: Create OAuth credentials in your IdP

​Step 3: Configure in admin UI

​Step 4: Test the integration

​Configuration options

​Local login control

​JIT user provisioning

​Role mapping

​Common configurations

​Pure SSO-only mode

​Hybrid mode (local + SSO)

​Enterprise mode (restricted domains)

​Bootstrap first admin

​Troubleshooting

​Provider not appearing on login page

​Authentication fails

​User not created automatically

​Next steps

In-depth guide

User management

Overview

Choose your provider type

Quick setup

Step 1: Enable database-backed providers

Step 2: Create OAuth credentials in your IdP

Step 3: Configure in admin UI

Step 4: Test the integration

Configuration options

Local login control

JIT user provisioning

Role mapping

Common configurations

Pure SSO-only mode

Hybrid mode (local + SSO)

Enterprise mode (restricted domains)

Bootstrap first admin

Troubleshooting

Provider not appearing on login page

Authentication fails

User not created automatically

Next steps