Back to Overview

Generic SSO (OAuth / OIDC)

Connect Tymeslot to any OAuth 2.0 / OpenID Connect identity provider for single sign-on, including Keycloak, Authentik, Lemonldap::NG, Okta and Microsoft Entra ID.

Luka Breitig, Software Engineer & AI Developer
Luka Breitig

Aggiornato il 4 marzo 2026

Before you begin

  • An identity provider (IdP) that supports OAuth 2.0 / OpenID Connect
  • Admin access to create an OAuth client/application in your IdP
  • A domain with HTTPS configured
  • Tymeslot installed and running at your domain

By the end of this guide, users can sign in to Tymeslot through your organisation's identity provider, alongside or instead of email and password.

How it works

Tymeslot uses the standard OAuth 2.0 Authorization Code flow, with PKCE. When a user clicks the SSO button:

  1. Tymeslot sends the user to your IdP's authorisation endpoint.
  2. The user signs in at the IdP (password, MFA and so on).
  3. The IdP sends the user back to Tymeslot with an authorisation code.
  4. Tymeslot exchanges the code for an access token and fetches the user's profile from the userinfo endpoint.
  5. Tymeslot finds the user's account, or starts a new one, by the sub (subject) claim.

OIDC-compliant providers recommended

Any OAuth 2.0 provider works, but OIDC-compliant providers are recommended because they return standard claims (sub, email, email_verified, name) from the userinfo endpoint. The sub claim is required.

1 Register Tymeslot in your identity provider

Create a new OAuth 2.0 / OIDC client application in your IdP. The steps depend on the provider, but you typically supply:

  • • Application name: Tymeslot
  • • Application type: Web application (confidential client)
  • • Redirect / callback URI: https://yourdomain.com/auth/oauth/callback
  • • Scopes / permissions: openid email profile

After creating the client, note down the Client ID and Client Secret.

2 Find your IdP's endpoint URLs

You need three endpoint URLs from your identity provider. Most OIDC providers publish them in their discovery document at: 

https://your-idp.example.com/.well-known/openid-configuration

From the discovery document (or your IdP's documentation), note:

  • • Authorisation endpoint (authorization_endpoint)
  • • Token endpoint (token_endpoint)
  • • Userinfo endpoint (userinfo_endpoint)

3 Configure environment variables

Add the following to your Tymeslot environment and restart it. 

# Enable generic OAuth / OIDC SSO
ENABLE_OAUTH_AUTH=true

# OAuth client credentials (from Step 1)
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret

# Identity provider URLs (from Step 2)
OAUTH_PROVIDER_URL=https://your-idp.example.com
OAUTH_AUTHORIZE_URL=https://your-idp.example.com/authorize
OAUTH_TOKEN_URL=https://your-idp.example.com/token
OAUTH_USERINFO_URL=https://your-idp.example.com/userinfo

# Scopes (optional — defaults to "openid email profile")
# OAUTH_SCOPE=openid email profile

HTTPS required

The OAUTH_AUTHORIZE_URL, OAUTH_TOKEN_URL, and OAUTH_USERINFO_URL must use HTTPS (or be paths relative to OAUTH_PROVIDER_URL). Tymeslot refuses to start if any of them uses plain HTTP, because they carry authorisation codes, client credentials and access tokens.

After the restart, an SSO button appears on the sign-in and sign-up pages. While the variable is unset, an admin can also turn SSO on or off later in the admin panel's Authentication tab, without a restart. On Cloudron, the OIDC addon supplies these values and SSO is on automatically unless you set ENABLE_OAUTH_AUTH=false. If the log shows "No admin can sign in" at startup, an environment variable such as that one is pinning a sign-in setting; unset or correct it and restart.

Provider-specific examples

Below are example configurations for common identity providers. Replace the placeholders with your own credentials and domain.

Keycloak

ENABLE_OAUTH_AUTH=true
OAUTH_CLIENT_ID=tymeslot
OAUTH_CLIENT_SECRET=your-keycloak-client-secret
OAUTH_PROVIDER_URL=https://keycloak.example.com
OAUTH_AUTHORIZE_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/auth
OAUTH_TOKEN_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/token
OAUTH_USERINFO_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/userinfo

Authentik

ENABLE_OAUTH_AUTH=true
OAUTH_CLIENT_ID=your-authentik-client-id
OAUTH_CLIENT_SECRET=your-authentik-client-secret
OAUTH_PROVIDER_URL=https://authentik.example.com
OAUTH_AUTHORIZE_URL=https://authentik.example.com/application/o/authorize/
OAUTH_TOKEN_URL=https://authentik.example.com/application/o/token/
OAUTH_USERINFO_URL=https://authentik.example.com/application/o/userinfo/

Lemonldap::NG

ENABLE_OAUTH_AUTH=true
OAUTH_CLIENT_ID=your-lemonldap-client-id
OAUTH_CLIENT_SECRET=your-lemonldap-client-secret
OAUTH_PROVIDER_URL=https://auth.example.com
OAUTH_AUTHORIZE_URL=https://auth.example.com/oauth2/authorize
OAUTH_TOKEN_URL=https://auth.example.com/oauth2/token
OAUTH_USERINFO_URL=https://auth.example.com/oauth2/userinfo

What users experience

When a user clicks SSO, Tymeslot sends them to your identity provider's sign-in page. Once they have signed in there, the IdP sends them back to Tymeslot, which signs them in.

On first sign-in, Tymeslot sets up a new account from the email and name in the IdP's userinfo response. Whether it trusts that email straight away depends on OAUTH_EMAIL_VERIFIED_CLAIM: by default (trust_absent) an email counts as verified unless the IdP sends email_verified: false, which suits Authentik, Entra ID and Keycloak setups that omit the claim. Set it to require to accept only email_verified: true, or ignore to trust every email your IdP returns. An email that is not trusted must be confirmed through a link Tymeslot sends.

SSO users cannot set or reset a password in Tymeslot, because the identity provider handles sign-in. Their account settings page marks the password as managed by the provider and offers no password change.

Email address conflicts

If a user's IdP email address already belongs to a Tymeslot account created another way (for example, email and password, or Google), Tymeslot rejects the SSO sign-in with an "email already taken" error and the user keeps signing in the original way. Tymeslot never links accounts across providers automatically, because that would let anyone who controls an address at one provider take over the account.

Common errors

SSO button does not appear on the login page

Confirm that ENABLE_OAUTH_AUTH=true is set and that you restarted Tymeslot, because environment variables are only read at startup. If the variable is unset, check that an admin has not switched SSO off in the admin panel's Authentication tab.

"SSO authentication failed" after clicking the button

Check the Tymeslot server logs for the specific error. The most common causes are an incorrect OAUTH_TOKEN_URL, a wrong client secret or a redirect URI mismatch. The callback URI registered in your IdP must be exactly https://yourdomain.com/auth/oauth/callback.

"invalid_user_info" error in server logs

The userinfo endpoint must return a JSON object containing a unique user identifier. Tymeslot requires the standard sub claim by default. If your IdP returns id or user_id instead, set OAUTH_ALLOW_ID_FALLBACK=true to accept those claims. Without this flag, sign-in fails if sub is missing.

Tymeslot fails to start with a configuration error

When ENABLE_OAUTH_AUTH=true, Tymeslot checks at startup that every required variable is set. If any are missing, it refuses to start and prints the missing names. Set all of the following: OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_AUTHORIZE_URL, OAUTH_TOKEN_URL, OAUTH_USERINFO_URL, and OAUTH_PROVIDER_URL when any of those endpoints is a relative path.

❓ Frequently Asked Questions

Can I use SSO alongside Google and GitHub login?

Yes. All three can be on at once, each with its own button on the sign-in page. Each Tymeslot account belongs to one sign-in method, and an email address can only belong to one account, so a user who first signed in with Google cannot later sign in with SSO using the same email.

Can SSO users reset their password?

No. SSO users have no Tymeslot password. If one requests a reset, the form answers as it does for any address, and Tymeslot emails them to explain that they sign in through SSO. Passwords are managed in your identity provider.

Can I disable email/password signup and only allow SSO?

Yes. Set REGISTRATION_ENABLED=false to hide the email sign-up form. Existing users can still sign in with SSO, but new SSO users cannot create accounts either, because the setting closes registration for every method. To keep SSO as the only sign-in method for existing accounts, also set PASSWORD_AUTH_ENABLED=false.

What claims does Tymeslot read from the userinfo endpoint?

Tymeslot reads four claims: sub (required unless OAUTH_ALLOW_ID_FALLBACK is enabled), email, email_verified, and name. If email is missing, Tymeslot asks the user for one during sign-up.

Does Tymeslot support OIDC discovery?

No. You set each endpoint URL explicitly in an environment variable, which also works with providers that publish no discovery document.

Can I switch to a different identity provider?

Yes, but Tymeslot has only one generic SSO provider. If you change the IdP (for example, from Keycloak to Authentik), existing SSO accounts no longer match because the user identifiers (sub claims) differ between providers. Before switching, remove or reassign the old SSO accounts in the database. Users then get new accounts when they first sign in through the new IdP.

Verification Checklist

Confirm each of the following after restarting Tymeslot:
  • An SSO button appears on the sign-in and sign-up pages.
  • Clicking it opens your identity provider's sign-in page.
  • After you sign in at the IdP, it sends you back to Tymeslot and you are signed in.
  • Your account settings page shows that the provider manages your password.
  • A password reset request for the SSO account sends an email explaining that the account signs in through SSO, not a reset link.

🔗 Related Articles

Read Google OAuth App Setup

Google OAuth App Setup

Set up a Google OAuth app in Google Cloud Console. One app powers Google Login, Calendar sync, and Meet rooms for Tymeslot. Covers API enabling and consent screen.

Read Microsoft Azure App Setup

Microsoft Azure App Setup

Register an Azure app for Tymeslot. Enables Outlook Calendar sync and Teams meetings. Covers API permissions and admin consent requirements.