Authentication Guide

Overview

Keymaster supports multiple authentication methods, all unified behind a single login page per app. Users choose their preferred method; Keymaster handles the rest.

Supported Auth Methods

Apps choose which providers to enable via the Console. The login page only shows enabled providers.

OAuth2 Authorization Code Flow

This is the primary flow for web applications.

1. Initiate Login

Redirect the user to:

GET https://keymaster.cloud-monitor.com/login
    ?app_id={uuid}
    &redirect_uri={your_callback_url}

Optional parameters: - prompt=login — Force login screen even if SSO session exists (skip SSO fast path)

2. User Authenticates

Keymaster shows the branded login page. The user picks their auth method: - Password → email + password form - Magic Link → email input, receives link via email - OAuth → redirects to provider (Google, GitHub, etc.), returns to Keymaster

3. SSO Fast Path

If the user has an active km_sso session (logged in at Keymaster within the last 8 hours), Keymaster skips the login screen and immediately redirects back with tokens — true cross-app SSO.

This only happens if: - User has a valid km_sso cookie - User is enrolled in the target app - prompt=login is NOT set

4. Callback with Tokens

On success, Keymaster redirects to your redirect_uri:

{redirect_uri}?access_token={jwt}&refresh_token={opaque_token}

5. Error Handling

On failure, Keymaster redirects to the login page with an error parameter:

Registration Policies

Each app has a registration policy that controls how users gain access:

Cross-App SSO

Keymaster's SSO works via the km_sso httponly cookie on the Keymaster domain.

Flow: 1. User logs into App A → Keymaster sets km_sso cookie (8-hour lifetime) 2. User visits App B → App B redirects to Keymaster login 3. Keymaster sees valid km_sso → checks user is enrolled in App B 4. If enrolled → issues tokens and redirects back immediately (no login screen) 5. If not enrolled → shows login page with "You don't have access" message

SSO does NOT auto-enroll users. Each app controls its own enrollment via registration policy.

Password Policy

• Minimum length: 16 characters (platform default, configurable per tenant)
• Hashing: Argon2id
• No complexity requirements enforced (length is the primary defense)
• Password change revokes all SSO sessions (forces re-authentication everywhere)

Two-Factor Authentication (TOTP)

• Apps can require 2FA via the "Require 2FA" toggle in Console
• Users set up TOTP via the Account page (any authenticator app)
• 8-character backup codes provided (10 codes, single-use)
• When 2FA is required but not set up, login returns a structured error with a link to the Account page

Magic Links

Passwordless email login: 1. User enters email on login page 2. Keymaster sends a signed link (15-min expiry, single-use) 3. User clicks link → Keymaster verifies, creates session, redirects with tokens 4. Link is consumed — cannot be reused

Magic links are ideal for infrequent users or kiosk environments where typing passwords is impractical.

OAuth Provider Notes

Google

• Uses OpenID Connect (email + profile scopes)
• Email verified by Google is automatically marked verified in Keymaster
• prompt=select_account forces account picker

GitHub

• Uses GitHub's OAuth2 flow
• Email may require a separate API call if user's GitHub email is private

Microsoft

• Uses Microsoft Entra ID (formerly Azure AD)
• Supports both personal and work/school accounts
• prompt=select_account forces account picker

Apple

• Uses Sign in with Apple (JWT-based)
• Apple only sends the user's name on first login — Keymaster stores it
• Requires Apple Developer Program membership