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

# Single sign-on (SSO)

> Connect a SAML 2.0 or OpenID Connect identity provider such as Okta or Entra ID, verify your domain, and optionally require SSO for every member.

> [!NOTE]
>
> **Plans:** Growth and Enterprise · **In the app:** Settings → Security → Single sign-on

With single sign-on, people whose email is in your company's domain sign in to Quotable through your identity provider (IdP). Quotable supports **SAML 2.0** and **OpenID Connect (OIDC)**, works with Okta, Microsoft Entra ID, Google Workspace and any standards-compliant IdP, and pairs with [SCIM provisioning](https://docs.usequotable.com/workspace/scim.md).

> [!NOTE]
>
> Only workspace **owners** can manage single sign-on, and every change asks for [recent re-authentication](https://docs.usequotable.com/workspace/security.md#recent-re-authentication).

## How it works

1. You add a **connection**: one IdP for one or more email domains.
2. You **verify** that you control the domain with a DNS TXT record.
3. From then on, anyone signing in with an address in that domain can use SSO. New people join your workspace automatically as **viewers**.
4. Optionally, you **require** SSO, so a password or Google sign-in is refused for those addresses.

## Service provider details

Give these values to your IdP administrator. `{connection-id}` is shown on each connection in **Settings → Security → Single sign-on** once it is registered.

| Setting | Value |
| - | - |
| SP entity ID / audience | `https://app.usequotable.com` |
| SAML ACS URL | `https://app.usequotable.com/api/auth/sso/saml2/sp/acs/{connection-id}` |
| SAML SP metadata | `https://app.usequotable.com/api/auth/sso/saml2/sp/metadata?providerId={connection-id}` |
| OIDC redirect URI | `https://app.usequotable.com/api/auth/sso/callback/{connection-id}` |

> [!TIP]
>
> Some IdPs ask for the ACS URL before they give you metadata. Create the IdP app with a placeholder URL, register the connection in Quotable, then paste the ACS URL it shows back into your IdP.

## Set up SAML 2.0

**1. Create a SAML app in your IdP**

Create a new SAML 2.0 application. Set the **SP entity ID / Audience URI** to `https://app.usequotable.com` and the **ACS / Reply URL** to the ACS URL above.

Configure it to:

* send the user's email address as the **NameID** (email format),
* include attributes named `email` and `name`,
* **sign the assertion**. Quotable rejects unsigned assertions.

**2. Add the connection in Quotable**

Go to **Settings → Security → Single sign-on → Add an identity provider** and choose **SAML 2.0**. Enter your **email domains**, comma-separated (for example `acme.com, acme.co.uk`), and paste the IdP's **metadata XML**.

No metadata? Expand **Enter the details by hand** and give the **SSO URL**, the **IdP entity ID** and the **signing certificate** (PEM).

**3. Copy the ACS and metadata URLs back**

The connection now shows its **ACS URL** and **SP metadata** URL. Make sure your IdP app uses exactly these values.

**4. Verify your domain**

See [Verify your domain](#verify-your-domain) below.

**5. Assign people and test**

Assign users to the app in your IdP. Then sign out of Quotable, enter an address in your domain on the login page and choose **Use single sign-on (SAML / OIDC)**.

### Provider notes

> [accordion] Okta
>
> Create an app integration with **SAML 2.0** as the sign-in method. **Single sign-on URL** is the ACS URL and **Audience URI (SP Entity ID)** is `https://app.usequotable.com`. Set **Name ID format** to `EmailAddress` and **Application username** to `Email`. Add attribute statements `email` → `user.email` and `name` → `user.displayName`. Copy the **Metadata URL** contents (the XML) into Quotable.

> [accordion] Microsoft Entra ID
>
> In **Enterprise applications**, create a non-gallery application and choose **SAML** single sign-on. Set **Identifier (Entity ID)** to `https://app.usequotable.com` and **Reply URL (Assertion Consumer Service URL)** to the ACS URL. Under **Attributes & Claims**, make the unique user identifier the user's email and add claims named `email` and `name`. Download **Federation Metadata XML** and paste it into Quotable.

> [accordion] Google Workspace
>
> In the Admin console, add a custom SAML app. Set **ACS URL** to the ACS URL and **Entity ID** to `https://app.usequotable.com`, with **Name ID format** `EMAIL` and **Name ID** `Basic Information > Primary email`. Add attribute mappings for `email` and `name`. Download the IdP metadata and paste it into Quotable.

## Set up OpenID Connect

**1. Create an OIDC app in your IdP**

Create a web application using the authorization code flow. You add the redirect URI after the next step.

**2. Add the connection in Quotable**

Go to **Settings → Security → Single sign-on → Add an identity provider** and choose **OpenID Connect**. Enter your **email domains**, the **Issuer URL** (must be `https://`), the **Client ID** and the **Client secret**.

Quotable reads the endpoints from the issuer's `/.well-known/openid-configuration`, requests the `openid`, `email` and `profile` scopes and uses PKCE. The client secret is stored securely and never shown again.

**3. Add the redirect URI to your IdP**

Copy the connection's **Redirect URI** into your IdP app's allowed redirect URIs.

**4. Verify your domain and test**

Follow [Verify your domain](#verify-your-domain), then test as described for SAML.

## Verify your domain

Sign-in through a connection is refused until you prove you control its domain. This stops anyone from registering another company's domain and capturing its sign-ins.

**1. Get the record**

On the connection, choose **Verify domain**. Quotable shows a TXT record **Name** and **Value**.

**2. Publish it**

Add the TXT record to the DNS of every domain on the connection, exactly as shown. The record name starts with `_quotable-`.

**3. Check it**

Back in Quotable, choose **Check DNS record**. DNS changes can take a few minutes to propagate. Once verified, the connection is live.

## Who gets in

* **New people.** The first time someone signs in through a verified connection, they join the workspace that owns the connection as a **viewer** with **no brands**. An owner grants brands and raises their role in **Settings → Members**, or you can map roles from IdP groups with [SCIM](https://docs.usequotable.com/workspace/scim.md).
* **Existing members** keep their role and brand access. SSO only adds another way to sign in.
* **Deactivated members** are not let back in by signing in through SSO. Their access is restored by your IdP or an owner.
* A connection only admits addresses in its own verified domains and only adds people to its own workspace.
* If you have 2FA on your Quotable account, you are still asked for your code after SSO.

## Require single sign-on

Once a connection is verified, an owner can turn on **Require single sign-on** in **Settings → Security → Single sign-on**.

When it is on, members whose email is in a verified domain **must** sign in through your IdP. A password or Google sign-in for those addresses is refused, and their existing sessions from those methods are sent back to sign in with SSO. Members with addresses outside your verified domains, such as contractors, are not affected.

The login page also steers people: entering an address in a domain that requires SSO starts SSO directly.

To turn it on, you need:

* at least one **verified** connection, and
* **two-factor authentication on your own account**, because it is the break-glass below.

Turning it off takes effect immediately.

### Break-glass access for owners

If your IdP is down or misconfigured, owners can still get in: sign in with a password or Google, choose **Sign in with a password instead** if the login page steers you to SSO, and complete the 2FA challenge. Owners are admitted this way **only with 2FA**, so a stolen owner password alone is still refused. From there you can fix the connection or turn off the requirement.

## Rotate a signing certificate

A SAML connection trusts a list of IdP signing certificates, so you can rotate without downtime:

1. Before your IdP switches keys, open the connection, choose **Rotate certificate** and paste the new certificate. Both certificates are trusted.
2. Switch your IdP to the new key.
3. Remove the old certificate from the connection.

Expired and duplicate certificates are refused, and a connection's last certificate cannot be removed.

## Remove a connection

Removing a connection stops sign-in through it. Members keep their membership, role and any other sign-in method they have.

## Limitations

* **Sign-in starts at Quotable.** IdP-initiated sign-in (clicking a tile in your IdP's dashboard) is not supported.
* **No single logout.** Signing out of Quotable ends the Quotable session only. Your IdP session is left as it is, so signing in again through SSO may be instant.
* **One connection per domain list.** Each connection covers the domains you entered when you created it.
* **Clock skew.** If your IdP's clock is off, assertions are rejected as expired and the login page shows that single sign-on did not complete.
* **Email changes.** Members cannot change their sign-in email while their domain is under required SSO.

## Audit trail

Every change is recorded in the [audit log](https://docs.usequotable.com/workspace/audit-log.md): connections registered and removed, domains verified, certificates added and removed, and the requirement turned on or off.

## Next steps

> [card] [SCIM provisioning](https://docs.usequotable.com/workspace/scim.md)
>
> Create, update and deactivate members from your IdP.

> [card] [Team and roles](https://docs.usequotable.com/workspace/team-and-roles.md)
>
> What viewers, editors and admins can do.

> [card] [Account security](https://docs.usequotable.com/workspace/security.md)
>
> Two-factor authentication and sessions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.