> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terminus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Single sign-on (SAML)

> Connect your SAML identity provider so your team signs in to Terminus Hub through it, then optionally enforce SSO for members.

<Info>
  Single sign-on lets your team sign in to Terminus Hub through your company identity provider (IdP) instead of a Terminus password. Terminus Hub supports **SAML 2.0**, which covers providers such as Okta, Microsoft Entra ID, and Google Workspace. Setup is available to **account owners and admins** on the **Enterprise plan**.
</Info>

## How it works

You create a **connection** for your IdP and scope it to one or more **email domains**. Once the connection is active, anyone who enters an email on that domain at the sign-in screen is sent to your IdP instead of being asked for a password. The sign-in screen asks for the email first, which is how it knows where to route each person.

A connection moves through stages, shown as a badge in the connection list:

1. **Needs IdP details**: you created it with just a name and domains.
2. **Draft**: IdP details are filled in; it can be tested but is not live.
3. **Active (optional)**: live. People on the domain can use SSO, and passwords still work.
4. **Enforced**: live, and members on the domain must use SSO.

## Prerequisites

* You are an owner or admin of the account. Creating, testing, and activating connections also requires the Enterprise plan.
* You can create apps in your identity provider and copy its SAML details.
* The email domains you plan to use are your company's own. Public email domains such as gmail.com are rejected.

## Set up a connection

<Steps>
  <Step title="Create a draft connection">
    Open **Settings**, then **Single Sign-On**, and click to add a connection. Give it a **Name** and the **Email domains** it covers (comma-separated). Saving generates the connection's service provider details.
  </Step>

  <Step title="Copy the SP details into your IdP">
    The connection page shows two values to paste into a new SAML app at your IdP:

    * **SP Entity ID** (sometimes called Audience or Identifier)
    * **ACS URL** (sometimes called Reply URL or Single sign-on URL)

    Both are unique to this connection, so if you ever set up a second connection it registers as a distinct app at the IdP. There is no override for the Entity ID.
  </Step>

  <Step title="Paste the IdP details back into Terminus">
    From your IdP's SAML app, copy three values into the connection:

    * **IdP Entity ID**
    * **IdP SSO URL**
    * **IdP X.509 Certificate**: the public signing certificate, pasted as PEM text.

    Optionally set a **Unique ID attribute** (see below). With all three IdP fields present the connection is configured and can be tested.
  </Step>

  <Step title="Test with a real login">
    Click **Copy test link**. The link is valid for **15 minutes** and drives a genuine end-to-end login against the draft connection without it being live for anyone else. Open it in a fresh browser session and sign in at your IdP. A successful round trip is recorded on the connection.
  </Step>

  <Step title="Activate">
    Click **Activate**. Activation is only allowed after at least one successful login has been recorded; if you skipped the test, the activation is rejected. Once active, sign-ins on the connection's domains route through your IdP.
  </Step>
</Steps>

## The two toggles

**Enforce SSO** appears once a connection is active. With it on, members on the connection's domains must sign in through SSO; even a correct password is intercepted and redirected to the IdP. **Owners and admins always keep password access**, enforced or not. That carve-out is deliberate: it means an IdP outage or misconfiguration can never lock the people who can fix it out of the account.

**Auto-provision members** is on by default. With it on, the first SSO login from a new person on the domain creates their user and an active membership automatically. New members created this way count against your seat limit, and a login that would exceed the seats fails rather than silently going over. With it off, SSO only signs in people who already hold an active membership; new people must be [invited](/account/team-members) first.

## What your team sees

The sign-in screen asks for an email address first. On an SSO-enabled domain, submitting the email redirects straight to your IdP and back into Terminus Hub; there is no separate "sign in with SSO" button to find. On a non-enforced domain a person can still choose to use their password instead. If a login fails at the SSO stage, the person lands on a generic failure page; the specific reason is logged for security rather than shown, so check the troubleshooting list below.

## Keeping identities stable

By default, Terminus Hub keys each SSO identity on the email your IdP asserts. If your company changes email addresses (rebrands, marriages, domain migrations), set the **Unique ID attribute** to a stable, immutable attribute your IdP sends, such as Entra ID's object ID or Okta's user ID. The identity is then keyed on that value, and a person's email can change at the IdP without breaking their link to Terminus. On each login the person's email and name are synced from the IdP's assertion.

## Migrating to a new IdP

Create a second connection for the same domain, configure and test it, then activate it. Activation automatically deactivates the other connection on that domain, so a domain always has at most one live connection and the cutover is atomic. The old connection stays in your list, deactivated, until you delete it.

## Troubleshooting

* **"Cannot activate" or an activation error.** No successful login has been recorded yet. Use **Copy test link** and complete a real sign-in first.
* **Test login fails.** The usual causes are a certificate mismatch (re-paste the current cert from the IdP), an Entity ID or Audience mismatch at the IdP, or an expired certificate. The connection shows the stored certificate's fingerprint and expiry date, so compare those against the IdP.
* **The certificate box is empty when I edit the connection.** The certificate is write-only: it is stored but never displayed back. An empty box on a configured connection means "keep the stored certificate." Only paste into it when you mean to replace the cert.
* **"Domain already configured for SSO."** A domain can be active in only one Terminus account at a time. If another account already claims it, that account's admin must deactivate first.
* **A new person's first SSO login fails.** If auto-provision is on, check your seat limit: a first login that would exceed the seats is refused. If auto-provision is off, the person needs an invitation before SSO will sign them in.
* **Public email domains are rejected.** Connections can only cover company-owned domains, not gmail.com, outlook.com, and similar.

## Not included

Terminus Hub's SSO is SAML 2.0 only. OAuth/OIDC sign-in, SCIM provisioning and deprovisioning, and configurable attribute mapping are not available. Removing someone's access is done by suspending or removing their membership in [Members](/account/team-members); disabling them at the IdP stops future SSO logins but does not end an existing session or remove their membership.

## Related

* [Team members and roles](/account/team-members): seats, invitations, and what each role can do.
* [Billing and plans](/account/billing): SSO is an Enterprise plan feature.
* [Authentication](/authentication): passwords, sessions, and signing in.