Single Sign-On (SSO)

Sign in to SysTeam HealthChecks using your existing identity provider. Supports GitHub, Google, SAML 2.0, and OpenID Connect (OIDC).

Overview

SSO allows users to authenticate using external identity providers instead of (or in addition to) a local password. Benefits include:

• Centralized access control — manage who can access HealthChecks from your IdP
• Reduced credential fatigue — one fewer password to remember
• Compliance — enforce organization-wide authentication policies
• Just-In-Time provisioning — auto-create accounts and org memberships on first SSO login

Supported Providers

Logging In with SSO

If your administrator has configured SSO providers, you will see SSO buttons on the login page below the standard email/password form.

1. Go to the Login page
2. Click the SSO button for your provider (e.g., "Continue with GitHub")
3. You will be redirected to your identity provider to authenticate
4. After successful authentication, you will be redirected back to HealthChecks and logged in

First-Time SSO Login

What happens on your first SSO login depends on the provider configuration:

• Existing account with same email: Your SSO identity is automatically linked to your existing HealthChecks account.
• No existing account + auto-registration enabled: A new account is created automatically. You will be an SSO-only user (no password set).
• No existing account + auto-registration disabled: Login is rejected. An administrator must create your account first.

Linking & Unlinking SSO Accounts

You can link multiple SSO providers to your account, allowing you to sign in with any of them.

Linking an SSO Account

1. Go to Profile in the sidebar
2. Scroll to the Linked Accounts section
3. Click Link next to the provider you want to connect
4. Authenticate with the provider
5. You will be redirected back and the account will be linked

Unlinking an SSO Account

1. Go to Profile → Linked Accounts
2. Click Unlink next to the provider you want to disconnect

Administrator Setup

SSO providers are managed by superadmins via the admin panel. Each provider needs to be configured with credentials from the identity provider.

Accessing the Admin Panel

1. Log in as a superadmin user
2. Go to Admin → SSO Providers in the sidebar
3. Click Add Provider to create a new SSO provider

Common Fields

Configuring GitHub SSO

1. Go to GitHub Developer Settings → OAuth Apps → New OAuth App
2. Fill in the application details:
   • Application name: SysTeam HealthChecks
   • Homepage URL: Your HealthChecks domain (e.g., https://checks.example.com)
   • Authorization callback URL: https://checks.example.com/auth/sso/callback/github
3. After creating the app, note the Client ID and generate a Client Secret

Configuring Google SSO

1. Go to the Google Cloud Console → APIs & Services → Credentials
2. Click Create Credentials → OAuth 2.0 Client ID
3. Choose Web application as the application type
4. Under Authorized redirect URIs, add: https://checks.example.com/auth/sso/callback/google
5. Note the Client ID and Client Secret

Configuring SAML 2.0

SAML 2.0 is commonly used with enterprise identity providers like Okta, Azure AD, OneLogin, and ADFS.

Step 1: Get SP Metadata

After creating the SAML provider in the admin panel, download the SP (Service Provider) metadata from:

GET /api/auth/sso/saml/{slug}/metadata

Import this XML into your IdP, or manually configure:

• ACS URL: https://checks.example.com/api/auth/sso/saml/callback/{slug}
• Entity ID: https://checks.example.com

Step 2: Configure IdP Details

From your IdP, obtain:

Attribute Mapping

SAML providers can customize which IdP attributes map to HealthChecks fields using the Attribute Mapping JSON field. Defaults:

{
  "email": "email",
  "name": "name",
  "first_name": "firstName",
  "last_name": "lastName"
}

Configuring OpenID Connect (OIDC)

OIDC is supported for any provider that implements the OpenID Connect standard. If your provider has a .well-known/openid-configuration endpoint, configuration is simplified — just provide the discovery URL.

If your provider does not support auto-discovery, you can manually specify the URLs:

Just-In-Time (JIT) Provisioning

When an SSO provider is scoped to an organization, JIT provisioning can automatically add new users to that organization on their first SSO login.

To enable JIT provisioning:

1. Go to Organization Settings
2. Enable SSO JIT Provisioning
3. Set the Default SSO Role (e.g., MEMBER, VIEWER)

Users who log in via the org-scoped SSO provider will automatically be added to the organization with the default role, without needing a manual invite.

Organization SSO Policies

Organization admins can configure SSO policies in Organization Settings:

Security Considerations

• State tokens — All SSO flows use cryptographic state tokens (CSRF protection) that expire after 10 minutes
• Encrypted secrets — Client secrets are encrypted at rest using Fernet symmetric encryption
• Domain restrictions — Use Allowed Domains to prevent unauthorized email domains from logging in
• MFA + SSO — Users with 2FA enabled will be prompted after SSO redirect for additional security
• Unlink safety — SSO-only users cannot unlink their last provider (prevents lockout)
• PKCE support — State tokens can store code verifiers for PKCE-enabled flows

SSO API Endpoints

The SSO system exposes the following REST API endpoints:

# Get the authorization URL
curl https://checks.example.com/api/auth/sso/init/github

# Response:
{
  "authorize_url": "https://github.com/login/oauth/authorize?client_id=...&state=...",
  "state": "abc123..."
}

# Frontend POSTs code + state after redirect
curl -X POST https://checks.example.com/api/auth/sso/callback/github \
  -H "Content-Type: application/json" \
  -d '{"code": "code_from_provider", "state": "abc123..."}'

# Response (success):
{
  "message": "SSO login successful",
  "token_type": "cookie",
  "expires_in": 900
}

# Response (MFA required):
{
  "mfa_required": true,
  "mfa_token": "eyJ..."
}

Next Steps

• Security features (2FA, PAT, audit log)
• Organization management
• Full API reference