Enterprise SSO & domains

Enterprise single sign-on lets your organization’s members sign in to Tessule through your own identity provider — Okta, Microsoft Entra, Google Workspace, or any other OIDC provider. Paired with verified email domains, it routes your people to SSO automatically, joins them to the organization on first sign-in, and can close off passwords entirely. This guide is for organization owners and admins.

If you only remember one thing: an SSO connection is how people sign in; a verified domain is who it applies to and how strictly. The connection alone just adds a button. Verifying your email domain is what unlocks routing, auto-join, and enforcement.

---

Who can do what

All of this lives in Organization Settings and is governed by organization-level permissions, held by org owners and admins (the canManage tier — org members don’t see these tabs):

• SSO connections (SSO tab) — requires org:sso:manage.
• Verified domains (Domains tab) — requires org:domains:manage.
• Security policy (Security tab, the require-MFA switch) — viewing requires org:read; changing it requires org:settings:manage.

Org roles are separate from workspace roles — see Authorization & Permissions for how the two relate.

Note

SSO is a server-level capability. If it isn’t configured on your Tessule server, the SSO tab says so and connection management is unavailable (the API answers 409 for these endpoints).

---

SSO connections

Organization Settings → SSO lists your connections (GET /organizations/{organizationId}/sso-connections). The protocol is OIDC only — there is no SAML support.

Creating a connection

Add SSO connection asks for:

Field	Notes
Name	Shown on sign-in buttons when a user has more than one SSO option.
Email domain (optional)	Login-routing hint — must be a verified domain of this organization (same DNS proof as Domain claims). Public mailboxes (gmail.com, …) are rejected. When set, only emails on that domain see this connection on the sign-in page. SSO also refuses to create or provision users whose email domain is not verified for the connection’s organization.
Issuer URL	Your IdP’s OIDC issuer, e.g. https://acme.okta.com.
Client ID / Client secret	From the app registration you create at your IdP. The secret is stored encrypted and never displayed again — the UI shows only whether one is set and the client ID’s last 4 characters. Leave both blank when editing to keep the current values.
Discovery endpoint (optional)	Defaults to {issuer}/.well-known/openid-configuration.
Scopes	Defaults to openid profile email.
Enabled	A disabled connection signs nobody in and suspends any enforcement that points at it.

On the IdP side, register a web application whose redirect URI points at Tessule’s OIDC callback: /api/auth/sso/callback/{connectionId} on your Tessule API URL, using the connectionId returned when the connection is created.

Connections are created with POST /organizations/{organizationId}/sso-connections, updated with PATCH /organizations/{organizationId}/sso-connections/{connectionId} (partial — only provided fields change; omit the secret to keep it), and deleted with DELETE /organizations/{organizationId}/sso-connections/{connectionId}.

How members sign in

The SSO sign-in sequence. Steps 5–6 run on every sign-in, so role mapping changes at the IdP flow through at the next sign-in.

Each connection has a stable sign-in URL — GET /auth/sso/{connectionId}/start — which redirects the browser to your IdP. Members reach it three ways:

1. From the sign-in page. After a user enters an email whose domain matches the connection (via the connection’s own Email domain field or a verified domain that enforces it), an SSO button appears — labelled “Single sign-on”, or “Sign in with name” when there are several. This discovery (POST /auth/methods) is computed from domain policy only, never from account existence.
2. A direct link. The SSO tab’s copy button copies the sign-in URL — put it on your intranet or in your IdP’s app dashboard. The app also serves a friendly redirect page at /sso/{connectionId} in the web app.
3. IdP-initiated bookmark — point an IdP tile at either URL above.

To test a new connection, copy its sign-in URL and open it in a private browser window: you should land at your IdP, authenticate, and arrive back in Tessule signed in. Errors bounce back to the sign-in screen with a message rather than dead-ending at the provider.

Role mapping: what an SSO user gets

Each connection carries an optional role mapping that translates the IdP’s group/role claim into organization and workspace membership. It is evaluated on every SSO sign-in and applied additively — grants and upgrades only, never demotions or removals:

• Groups claim — which claim carries group membership (default groups). IdPs differ: Okta sends group names, Entra sends group GUIDs (or app roles in a roles claim), and Google Workspace exposes no groups claim over OIDC at all — Google connections rely entirely on the defaults below. Matching is case-insensitive.
• Organization role rules — “members of crm-admins get org role admin”. When several match, the highest role wins.
• Default org role — for users matching no rule. None means users who match no rule get no membership at all: they can authenticate, but nothing is provisioned.
• Workspace rules and default workspace grants — grant workspace roles (admin / member / reader) by group, or to everyone. Grants can only target workspaces owned by this connection’s organization; a mapping that names a foreign workspace is skipped, never applied.

Tip

Because mapping runs additively on every sign-in, promoting someone in the IdP takes effect at their next sign-in — but demoting them in the IdP does not demote them in Tessule. Downgrades and removals are done in Tessule itself (Organization Settings → Members), like any other membership change.

First sign-in creates the account

SSO users are provisioned just-in-time. A first SSO sign-in creates the Tessule account with no invitation needed — and unlike self-registration it does not create a personal organization or workspace. The user’s entire access comes from the connection’s role mapping, so with Default org role: None and no matching rule they land with an account but no membership. There is no separate SCIM-style directory sync; sign-in is the sync point.

---

Verified domains

Organization Settings → Domains lets the organization claim the email domains it owns (GET /organizations/{organizationId}/domains). A verified domain is what turns SSO from opt-in to policy, and enables automatic joining.

Claiming and verifying

1. Add domain (POST /organizations/{organizationId}/domains) creates a pending claim. Public mailbox providers (gmail.com and friends) are rejected — you claim domains your organization controls.
2. The claim shows a DNS TXT record — a name like _crm-domain-verify.acme.com and an exact value. Publish it at your DNS provider.
3. Click Verify now (POST /organizations/{organizationId}/domains/{domainId}/verify), which looks up the record immediately. Status moves from pending to verified. A 409 here means another organization already holds the verified claim for that domain — a domain can only be verified by one organization at a time.

Deleting a domain (DELETE /organizations/{organizationId}/domains/{domainId}) removes the claim and its whole policy.

What a verified domain enables

Each verified domain carries a login policy, edited in place (PATCH /organizations/{organizationId}/domains/{domainId}). The switches are visible while the domain is pending but take effect only once it is verified:

Setting	Effect
Auto-join role	New users signing up with an email on this domain automatically join the organization with this org role (member / admin / owner). None disables auto-join. Only proven mailboxes auto-join: a social or SSO sign-up whose provider vouches for the email joins immediately; a password sign-up joins later, at the first sign-in after verifying their email.
Capture existing users	Users who already had accounts on this domain are attached to the organization at their next sign-in (with the auto-join role — capture requires one). Requires their email to be verified.
Enforce single sign-on	Closes the password and social paths for this domain — see below. Requires attaching one of the org’s SSO connections.

Policy changes propagate to sign-in within about a minute.

Enforcing SSO

With Enforce single sign-on on (and an enabled connection attached):

• The sign-in page shows only the SSO button for emails on this domain — no password field, no social buttons (“Your organization requires single sign-on”).
• Existing users on the domain attempting a password or social sign-in are refused with “This organization requires single sign-on”, and new password/social sign-ups on the domain are blocked outright — the SSO connection becomes the only door in.
• Fail-safe: enforcement requires a live, enabled connection. If the attached connection is disabled or deleted, enforcement is suspended rather than locking the whole domain out of sign-in.

Caution

Before enforcing, test the connection end-to-end with your own account in a private window. Enforcement applies to org owners and admins on that domain too — the fail-safe protects you from a broken connection config pointer, not from an IdP that rejects everyone.

---

Requiring MFA across the organization

Organization Settings → Security holds the organization’s one security policy: Require multi-factor authentication (GET /organizations/{organizationId}/security to view, PUT /organizations/{organizationId}/security to change).

When on, every member must satisfy MFA to use the organization’s workspaces: members without a second factor are walked through enrolment at their next sign-in, and existing access expires within 30 minutes. Two interactions worth knowing:

• SSO users are exempt. Their identity provider is responsible for MFA — enforce it there.
• Turning it on has a precondition: you and every active organization owner must already be MFA-capable (a verified second factor or a registered passkey). Otherwise the switch is refused with the list of owners who still need to enrol — the policy can never lock out the people who administer it.

The member-side experience — enrolment, passkeys counting as MFA, backup codes — is covered in Account security & sign-in.

---

FAQ

Can we use SAML? No — connections are OIDC only. Most major IdPs (including those whose internal apps are SAML-based) can publish an OIDC app for Tessule.

Does SSO deprovision users who leave? No. Role mapping only grants; removing someone from the IdP stops them signing in via SSO but does not remove their Tessule memberships or end other sign-in methods they may have. For a hard offboarding: remove them from the organization in Tessule (which detaches them from every workspace it owns), and if the domain enforces SSO their password/social paths are already closed.

Why doesn’t a user’s group change show up? Mapping is applied at sign-in. Have them sign out and back in through SSO — and remember it only ever upgrades; downgrades are manual.

We verified our domain but sign-ins aren’t routed to SSO. Routing to a specific connection comes from either the connection’s own Email domain field or the domain’s Enforce single sign-on setting with a connection attached. Verification alone proves ownership; attach the connection to get routing. Also allow up to a minute for policy changes to take effect.

Who can see the client secret? Nobody, ever again — it is stored encrypted and is write-only. Rotate it by pasting a new one into the edit dialog; leaving the field blank keeps the current secret.

Can auto-join be abused by someone typing an @our-domain email? No. A password sign-up’s email is unverified, so it gets no membership until the mailbox is proven via the verification link; social sign-ups only count when the provider has already verified the address. Org SSO is stricter still: the asserted email’s domain must be a verified domain claim of the connection’s organization (and connection Email domain routing requires the same), so a tenant cannot squat competitor addresses via their IdP.