Back to Overview

Generic SSO (OAuth / OIDC)

Connect Tymeslot to any OAuth 2.0 / OpenID Connect identity provider for single sign-on. Works with Keycloak, Authentik, Lemonldap::NG, Okta, Azure AD, and others.

Luka Breitig — Technical Product Builder & AI Developer
Luka Breitig

Technical Product Builder & AI Developer

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 will be able to sign in to Tymeslot using your organization's identity provider. This replaces or supplements email/password authentication with centralized SSO.

How it works

Tymeslot implements a standard OAuth 2.0 Authorization Code flow. When a user clicks the SSO button:

  1. Tymeslot redirects the user to your IdP's authorization endpoint.
  2. The user authenticates with the IdP (password, MFA, etc.).
  3. The IdP redirects back to Tymeslot with an authorization code.
  4. Tymeslot exchanges the code for an access token and fetches the user's profile from the userinfo endpoint.
  5. A Tymeslot account is created or linked based on the sub (subject) claim.

OIDC-compliant providers recommended

While any OAuth 2.0 provider works, OIDC-compliant providers are recommended because they return standardized 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 exact steps depend on the provider, but you will typically need to 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 these in their discovery document at: 

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

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

  • — Authorization endpoint (authorization_endpoint)
  • — Token endpoint (token_endpoint)
  • — Userinfo endpoint (userinfo_endpoint)

3 Configure environment variables

Add the following to your Tymeslot environment configuration and restart the server. 

# 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. Tymeslot will refuse to start if any of these URLs use plain HTTP, because they carry security-sensitive material (authorization codes, client credentials, access tokens).

After restarting, an SSO button appears on the login and registration pages.

Provider-specific examples

Below are example configurations for popular identity providers. Replace placeholder values with your actual 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, they are redirected to your identity provider's login page. After authenticating, they are redirected back to Tymeslot and signed in automatically.

On first login, Tymeslot creates a new account using the email and name from the IdP's userinfo response. If the IdP returns email_verified: true, the email is marked as verified immediately. Otherwise, a verification email is sent.

SSO users cannot set or reset a password in Tymeslot — authentication is fully managed by the identity provider. The account settings page shows that the account is managed by SSO and the password change option is disabled.

Email address conflicts

If a user's IdP email address already exists in Tymeslot from a different sign-in method (e.g., email/password or Google), the SSO login will be rejected with an "email already taken" error. Users must sign in with their original method. Automatic cross-provider account linking is not supported to prevent account takeover.

Common errors

SSO button does not appear on the login page

Confirm that ENABLE_OAUTH_AUTH=true is set and that you have restarted Tymeslot. Environment variables are read at startup only.

"SSO authentication failed" after clicking the button

Check the Tymeslot server logs for the specific error. The most common causes are: incorrect OAUTH_TOKEN_URL, 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 alternative claims. Without this flag, authentication will fail if sub is missing.

Tymeslot fails to start with a configuration error

When ENABLE_OAUTH_AUTH=true, Tymeslot validates that all required environment variables are set at startup. If any are missing, the application will refuse to start and print the list of missing variables. Ensure all of the following are set: OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_PROVIDER_URL, OAUTH_AUTHORIZE_URL, OAUTH_TOKEN_URL, OAUTH_USERINFO_URL.

❓ Frequently Asked Questions

Can I use SSO alongside Google and GitHub login?

Yes. All three can be enabled simultaneously. Each appears as a separate button on the login page. Users must continue using their original sign-in method — Tymeslot identifies accounts by email, so the same email address cannot be used across multiple providers. A user who initially signed in via Google cannot later sign in via SSO if they use the same email.

Can SSO users reset their password?

No. SSO users do not have a local password. If they visit the password reset page, they see a message explaining that their account is managed by an external authentication provider. Password management should happen in your identity provider.

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

Yes. Set REGISTRATION_ENABLED=false to hide the email signup form and block email-based registration. SSO login will still work for existing users. Note that new SSO users will also be blocked from creating accounts when registration is disabled — this is a global gate that applies to all registration methods.

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, the user will be prompted to provide one during account creation.

Does Tymeslot support OIDC discovery?

Not automatically. You must provide each endpoint URL explicitly via environment variables. This gives you full control over which endpoints are used and works with providers that do not publish a discovery document.

Can I switch to a different identity provider?

Tymeslot stores a single generic SSO provider slot. If you change the IdP (e.g., from Keycloak to Authentik), existing SSO accounts will no longer match because the user identifiers (sub claims) differ between providers. Before switching, remove or reassign the old SSO accounts in the database. New users will be created automatically when they sign in through the new IdP.

Verification Checklist

Confirm each of the following after restarting Tymeslot:
  • An SSO button appears on the login and registration pages.
  • Clicking it redirects to your identity provider's login page.
  • After authenticating with the IdP, you are redirected back to Tymeslot and signed in.
  • Your account settings page shows that authentication is managed by SSO.
  • The password reset page rejects attempts for the SSO account with a clear message.

🔗 Related Articles

Read Google OAuth App Setup

Google OAuth App Setup

Create a Google OAuth app to enable Google Login, Google Calendar sync, and Google Meet room creation.

Read Microsoft Azure App Setup

Microsoft Azure App Setup

Register a Microsoft Azure app to enable Microsoft Login, Outlook Calendar sync, and Teams room creation.

Read GitHub Login Setup

GitHub Login Setup

Let users sign in with their GitHub account. A two-minute setup with no special API scopes required.