Setting Up Single Sign-On for Your Team Workspace

Single sign-on (SSO) lets your team members sign in to Caffeine using the identity provider your organization already uses — such as Okta, Azure AD, or any OIDC-compatible provider. Once SSO is set up, members visit the Caffeine sign-in page and choose Sign in with SSO instead of creating a separate identity.

SSO is available to team workspace admins.

How it works

Caffeine's SSO is built on Internet Identity's support for external OIDC providers. When a member signs in with SSO, Internet Identity discovers your provider by fetching a configuration file from your organization's domain, then redirects to your provider to authenticate. No passwords are stored in Caffeine.

Setting up SSO is a two-step process: first verify that you own the domain, then connect your identity provider.

Step 1: Verify your domain

Before you can enable SSO, you need to prove to Caffeine that you control your organization's email domain.

1. Open Settings → SSO in your team workspace.
2. Enter your organization's domain (for example, example.com) and click Add domain.
3. Caffeine generates a verification token and shows you two verification options.

Option 1: DNS TXT record

Add a TXT DNS record with your DNS provider. Caffeine shows you the exact record to add — it looks like:

_caffeine-sso.example.com TXT caffeine-sso=<your-token>

After you publish the record, Caffeine checks DNS automatically every few minutes. Verification can take a short time to propagate after the record is published.

Option 2: Well-known file

If you can host a file on your domain, serve the verification token as plain text at:

https://example.com/.well-known/caffeine-sso-verification

The file must be publicly reachable over HTTPS and contain only the token string.

Once your domain shows a Verified badge in Settings, move on to Step 2.

Step 2: Connect your identity provider

After your domain is verified, you need to host a configuration file that tells Internet Identity how to find your identity provider.

Caffeine shows you the URL where this file must be served:

https://example.com/.well-known/ii-openid-configuration

Host a JSON file at that URL with the following structure:

{
  "client_id": "<your IdP client ID>",
  "openid_configuration": "https://<your-idp-host>/.well-known/openid-configuration",
  "name": "Caffeine SSO"
}

• client_id — the OAuth client ID you registered in your identity provider for Internet Identity.
• openid_configuration — your identity provider's standard OIDC discovery URL. For Okta this is https://<org>.okta.com/oauth2/default/.well-known/openid-configuration.
• name — an optional label shown in the Internet Identity interface.

Hosting requirements:

• Serve the file over HTTPS at the root of your verified domain.
• The file must be publicly reachable — Internet Identity fetches it on every sign-in.
• The openid_configuration host must match the issuer value in that document, and the authorization_endpoint must be on the same host as the issuer. Internet Identity enforces this.

Once the file is in place, SSO is live for your domain. Team members can sign in at Caffeine using Sign in with SSO on the sign-in page.

Signing in with SSO

When SSO is active, your team members see a Sign in with SSO option on the Caffeine sign-in page. Clicking it opens a dialog where they enter your organization's email domain. Caffeine resolves the domain and redirects them to your identity provider to authenticate.

Managing your SSO domain

From Settings → SSO you can:

• Regenerate token — generate a new verification token if the existing one was compromised or you need to re-verify. This does not remove existing verification status.
• Delete domain — remove your SSO domain configuration. Once deleted, Sign in with SSO will no longer resolve your domain.

Frequently asked questions

Who can configure SSO?

Only workspace admins can access the SSO settings screen and manage domain configuration.

Can my team still sign in without SSO?

Yes. SSO is not enforced — it is an additional sign-in option. Members who do not have an account under your SSO provider can still sign in using their existing Internet Identity.

What happens if DNS verification fails?

The domain will show a Failed verification badge. Double-check that the TXT record is published exactly as shown, then regenerate the token and try again. DNS propagation can take a few minutes after publishing the record.

Do I need to register Caffeine as an app in my identity provider?

Yes. You need to register Internet Identity as an OAuth client in your identity provider and note the client ID that is assigned. Refer to your identity provider's documentation for registering an OIDC application.

What identity providers are supported?

Any OIDC-compatible identity provider that supports the standard /.well-known/openid-configuration discovery URL — including Okta, Azure Active Directory, Google Workspace, Auth0, and others.