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. Use the callback URL shown for the provider in Sure; for this example:
https://your-domain.com/auth/google/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. Use the callback URL shown for the provider in Sure; for this example:
https://your-domain.com/auth/okta/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. Use the callback URL shown for the provider in Sure; for this example:
https://your-domain.com/auth/azure/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 user to register on a fresh instance is automatically assigned the super_admin role. No Rails console step is needed. If you are using SSO with JIT provisioning, the first user whose login creates a new family is also automatically assigned super_admin. Subsequent users get the role defined by your provider’s default role setting. Once a super admin exists, they can promote other users via the web UI at /admin/users. If you need to promote a user to super_admin on an existing instance (for example, after a data migration), use the Rails console:

bin/rails console

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

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
For database-backed providers, the redirect URI is https://your-domain.com/auth/<provider-id>/callback; copy the exact value shown in /admin/sso_providers
Check that client ID and secret are correct
Ensure the issuer URL is accessible from your server
Review logs at /admin/sso_audit_logs

Do not change SECRET_KEY_BASE on an existing instance. Self-hosted Sure derives Active Record encryption keys from it by default, and changing it prevents lookup of encrypted fields such as user email addresses.
If you added dedicated ACTIVE_RECORD_ENCRYPTION_* keys after the instance already had data, run the encryption backfill task once. See Turning on Active Record encryption after first boot.
If the keys were changed accidentally, restore the previous SECRET_KEY_BASE or previous ACTIVE_RECORD_ENCRYPTION_* values and restart the app.

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

​Email/password login fails after enabling encryption

​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

Email/password login fails after enabling encryption

User not created automatically

Next steps