Enterprise SSO

Single sign-on (SSO) lets users sign in to Epismo through their company's OpenID Connect (OIDC) provider. A workspace Owner or Admin registers the company domain and OIDC connection, verifies domain ownership, and completes a real login test before enabling it.

What is available now

• Epismo uses the domain of the work email entered in the normal sign-in form or passed to epismo login --email to route the user to the workspace's IdP automatically.
• Sign-in completes only when the IdP returns a verified email whose domain matches the workspace's verified domain.
• When the verified email belongs to an existing Epismo user, Epismo adds the OIDC identity to that user. Otherwise, Epismo creates a user.
• Epismo adds the user to the workspace as a Member through just-in-time (JIT) provisioning when needed.

What is not available yet

SSO is currently an additional login method. It does not require SSO whenever someone accesses the workspace. Existing members can continue to use Google, email authentication, or another method already available to them.

As a result, disabling an employee in the IdP does not necessarily invalidate an existing Epismo session or access through another login method immediately. SSO enforcement, SCIM, group sync, role mapping, multiple domains, and multiple OIDC connections are not part of the current release.

Sign-in flow

1. The user enters their company email in the normal Epismo sign-in form or runs epismo login --email <address>.
2. Epismo finds an enabled, verified SSO connection by email domain.
3. Epismo redirects the user to the company's IdP.
4. Epismo validates the OIDC response and verified email.
5. Epismo resolves the identity by issuer and subject. If the identity is new, Epismo links it to the user with the same verified email or creates a new user.
6. Epismo creates a Member membership when needed.
7. Epismo returns the user to the workspace.

The email address is used to discover the connection and confirm domain eligibility. The OIDC identity itself is identified by the issuer and subject issued by the IdP, not by email.

Configure SSO

A workspace Owner or Admin can configure SSO. A workspace currently supports one company email domain and one OIDC connection.

Create an application in your IdP

Create a web application in the IdP and register this callback URL:

https://epismo.ai/api/auth/oidc/callback

Epismo uses Authorization Code Flow, PKCE (S256), state, and nonce, and requests these scopes:

openid email profile

The ID token must contain these claims:

Assign the appropriate people to the Epismo application in your IdP. Epismo also checks the verified email domain, but that check does not replace IdP application assignment.

Save the connection in Epismo

Open the target workspace and go to Workspace settings → Single sign-on.

Client secrets are stored encrypted and are not displayed again after saving. Leaving the field empty preserves an existing secret. Use the explicit remove option to delete a stored secret.

Verify domain ownership

Before domain routing can be enabled, Epismo verifies that the workspace controls the domain. After saving the SSO configuration, add the DNS TXT record shown in settings. For example:

Name:  _epismo-challenge.acme.com
Value: epismo-domain-verification=<random-challenge>

Some DNS providers expect only _epismo-challenge in the Name field. After DNS propagation, select Verify DNS record. The domain becomes Verified when Epismo can read the exact TXT value.

Verification follows these rules:

• One email domain cannot be registered to multiple workspaces at the same time.
• Shared email domains such as gmail.com and outlook.com cannot be registered.
• Each configuration receives a random challenge.
• Changing the domain clears the old verification and issues a new challenge.
• Regenerate challenge invalidates the previous challenge and disables SSO until the new value is verified.
• Deleting and recreating the configuration requires a new challenge and verification.

Enable the connection

1. Save the connection details.
2. Add and verify the DNS TXT record.
3. Select Test SSO login and complete the IdP login as an administrator.
4. Return to settings, turn on Enable SSO, and save.

The connection cannot be enabled until both DNS verification and a real login test succeed. Changing the issuer, Client ID, Client secret, or domain invalidates the login test. Changing the domain also requires DNS verification again.

Troubleshoot DNS verification

Check that the TXT record uses the exact hostname and value shown in Epismo, DNS propagation has completed, and the same domain is not registered to another workspace. If your provider displays the value as multiple strings, joining them must produce the exact value shown in Epismo. An old record cannot verify a recreated configuration because its challenge changes.

User sign-in and JIT provisioning

When an enabled connection exists, submitting a matching work email automatically redirects the user to the company IdP. There is no separate SSO button to choose. In the CLI, epismo login --email <address> performs the same discovery; SSO continues in the browser, while addresses without SSO complete email-code login in the terminal. After authentication, the OIDC response must have a valid signature, issuer, audience, expiration, state, nonce, and PKCE exchange. The ID token must also contain email_verified: true, and its email domain must match the workspace's verified domain.

If SSO cannot complete, Epismo shows explicit options to retry SSO, send an email code, or use another email. It does not send a fallback code automatically.

Epismo resolves the identity by issuer and subject. If the identity is new, Epismo links it to the user with the same verified email or creates a user when no match exists. It then adds the user to the workspace as a Member when needed. SSO never promotes a user automatically to Owner or Admin.

An external user whose domain does not match is not JIT-provisioned, even if the IdP authenticates them. External members use the workspace's existing member-addition and regular authentication methods.

Existing accounts

The email entered before the redirect is used only to select the SSO connection. Account linking uses the verified email returned by the IdP. If that email belongs to an existing Epismo user, Epismo adds the OIDC identity to that user. A signed-in user can also link an OIDC identity explicitly. An identity already linked to another user cannot be reassigned.

SSO is not currently enforced

Disabling a user in the IdP does not guarantee immediate invalidation of an existing Epismo session. Policies that always require SSO and SCIM-based deprovisioning are outside the current scope.