Single Sign-On (Generic OIDC / SAML SSO)

LockMyCal supports the standardized OpenID Connect (OIDC) protocol, which enables seamless connection to any enterprise identity provider (IdP), such as:

Keycloak (Self-hosted)
Authentik (Self-hosted)
Authelia (Self-hosted)
Okta / Auth0
GitLab / JumpCloud / OneLogin

How OIDC works in LockMyCal

sequenceDiagram
    participant U as User
    participant L as LockMyCal
    participant I as Your Identity Provider (Keycloak/Authentik)

    U->>L: Clicks "Company sign-in (SSO)"
    L->>I: Redirect to the authorization URL with OIDC scopes (openid profile email)
    U->>I: Enters company credentials + MFA
    I->>L: Callback with an authorization code (/auth/oauth/callback)
    L->>I: Exchange of the code for an ID Token / UserInfo
    I-->>L: User profile (email, name, unique sub)
    L->>U: Sign-in to the LockMyCal dashboard

1. Registering a client in your IdP

In your identity provider, create a new client (Client / Application) of the type OpenID Connect / Confidential:

Client ID: lockmycal
Client Authentication: On (Client Secret)

Valid Redirect URI:

https://bookings.yourdomain.com/auth/oauth/callback

Scopes: openid, profile, email

2. Configuring the variables in LockMyCal

Set in your .env file:

# Enable the generic OAuth/OIDC module
ENABLE_OAUTH_AUTH=true

# Client keys
OAUTH_CLIENT_ID=lockmycal
OAUTH_CLIENT_SECRET=your_generated_secret_key

# Your provider's endpoints (must be HTTPS; you'll find them in the .well-known/openid-configuration
# document of your IdP — but LockMyCal doesn't load it itself, so the endpoints must be entered manually)
OAUTH_AUTHORIZE_URL=https://sso.yourdomain.com/realms/master/protocol/openid-connect/auth
OAUTH_TOKEN_URL=https://sso.yourdomain.com/realms/master/protocol/openid-connect/token
OAUTH_USERINFO_URL=https://sso.yourdomain.com/realms/master/protocol/openid-connect/userinfo

# Optional: the permission scope (default "openid email profile")
OAUTH_SCOPE="openid email profile"

# Optional: the base URL, only if the endpoints above are entered relatively (e.g. /token)
# OAUTH_PROVIDER_URL=https://sso.yourdomain.com

# Optional: how to trust the email_verified claim (trust_absent / require / ignore)
# Some providers (Authentik, Entra ID, some Keycloak setups) don't send it.
# OAUTH_EMAIL_VERIFIED_CLAIM=trust_absent

# Optional: accept "id"/"user_id" instead of "sub" (only for non-OIDC providers)
# OAUTH_ALLOW_ID_FALLBACK=false

Tip

With PASSWORD_AUTH_ENABLED=false, SSO remains the only way to sign in – before turning off passwords, verify that signing in via SSO works.

Note

LockMyCal has no automatic OIDC discovery — the address of the authorization, token and userinfo endpoints always has to be entered manually, even if the provider offers them through the standard .well-known/openid-configuration document.

3. Cloudron

If LockMyCal runs on Cloudron with a connected user directory, single sign-on is set up by itself: the application takes the credentials and endpoints from the CLOUDRON_OIDC_* variables when OAUTH_* are not set. The sign-in button is named after the name of the identity provider you entered in Cloudron; outside Cloudron it is called “SSO”.