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.

Required SSO and current limits

SSO can be enabled as an additional sign-in method or marked Required after domain verification and a successful login test. When required, workspace access needs current verified SSO evidence, including Web, CLI, and MCP credentials. Evidence expires at an absolute 12-hour deadline; refreshing or deriving credentials does not extend it. Web redirects to SSO, while CLI/MCP requests without evidence are denied and require sign-in again. Required SSO applies to owners too; email codes do not bypass it.

Disabling someone in the IdP does not immediately invalidate an existing Epismo session or SSO evidence. Remove the member in Epismo to revoke workspace-home access. SCIM, group sync, role mapping, multiple domains, and multiple OIDC connections remain unavailable. Explicit personal sharing has independent access semantics.

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.

External users are not JIT-provisioned through a nonmatching IdP domain. Adding membership separately does not bypass required SSO.

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.

Access when SSO is required

Signing in with Google or an email code can still identify the user, but does not satisfy required workspace SSO. Complete SSO before accessing that workspace, including as an owner. CLI/MCP credentials without current evidence are rejected, and refreshing them does not reset the evidence deadline.

To turn on Required SSO, complete a successful SSO test in the same browser within the previous 10 minutes.