> For the complete documentation index, see [llms.txt](https://docs.fullsession.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fullsession.io/18.-single-sign-on-sso.md).
# 18. Single Sign-On (SSO)
`Enterprise` SSO lets your team sign in to FullSession through your own identity provider (IdP) using **SAML 2.0**, so you control authentication centrally — no separate FullSession passwords. This chapter covers setting up SSO, verifying your domain, enabling and enforcing it, the sign-in experience, and its limits.
SSO is configured under **Settings → SSO** and is governed by the `sso:view`, `sso:create`, `sso:edit`, and `sso:delete` permissions (\[Chapter 16 — Team & Account Management]). It's an Enterprise-tier feature.
***
### 18.1 SSO Overview
FullSession's SSO is a **SAML 2.0** integration in which FullSession acts as the **Service Provider (SP)** and your IdP (Okta, Azure AD, Google Workspace, OneLogin, or any SAML-capable IdP) acts as the **Identity Provider**. FullSession brokers the SAML exchange behind the scenes, so you configure it once and your users sign in with their existing corporate credentials.
#### Key characteristics
| Aspect | What to know |
| -------------- | ------------------------------------------------------------------------------ |
| **Protocol** | SAML 2.0 only (no OIDC/OAuth or IdP-specific templates) |
| **Connection** | **One SSO connection per account**, bound to **one email domain** |
| **Flow** | SP-initiated (users start from FullSession's login page) |
| **Users** | SSO **authenticates existing FullSession users** — it does **not** create them |
> **Important — no automatic user provisioning.** FullSession does **not** auto-create accounts on first SSO login (no JIT provisioning, no SCIM). A user must already be a member of your account (\[Chapter 16, section 16.2]) before they can sign in via SSO. The recommended order is: **invite your users first, then enable SSO.**
***
### 18.2 Setting Up SSO
Setting up SSO is a two-way exchange of metadata: you give your IdP FullSession's **Service Provider** details, and you give FullSession your **IdP's** details. The setup wizard walks you through both.
#### Step 1 — Configure your IdP with FullSession's details
Click **Create SSO Connection**. FullSession shows its **Service Provider Configuration** — the values to enter into your IdP:
| Field | Use it for |
| ------------------------------------------------------- | ------------------------------------------------- |
| **Issuer / Metadata URL** | Import into your IdP for automatic configuration |
| **Assertion Consumer Service (ACS) URL / Callback URL** | The destination your IdP sends SAML assertions to |
| **Service Provider Certificate** | FullSession's public X.509 certificate |
Follow the on-screen **Next Steps**: configure your IdP with these details, then obtain your IdP's **SSO URL, Issuer, and Certificate**, and click **Continue to IdP Configuration**.
#### Step 2 — Enter your IdP's details into FullSession
On the **Create SAML SSO Connection** form, provide:
| Field | What to enter |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Domain** | The email domain your users sign in from — **must exactly match** their email domain (e.g. `example.com`) |
| **Identity Provider Single Sign-On URL** | Your IdP's SSO endpoint (e.g. `https://idp.example.com/sso/saml`) |
| **Entity ID** | Your IdP's Entity ID / issuer |
| **Certificate** | Your IdP's X.509 signing certificate |
Click **Create Connection**. The connection is created, but **SSO can't be turned on until you verify your domain** (next section).
***
### 18.3 Verifying Your Domain
Before SSO can be enabled, FullSession verifies that you own the email domain you entered — this prevents anyone from hijacking sign-in for a domain they don't control.
#### Add the DNS record
FullSession generates a unique verification key and shows you a DNS **TXT record** to add:
| Field | Value |
| --------- | -------------------------------- |
| **Type** | `TXT` |
| **Name** | `_fus_domain_verification` |
| **Value** | (the generated verification key) |
Add this record to your domain's DNS, wait for it to propagate, then click **Verify Domain**.
The status badge moves through **Pending → Verifying… → Verified** (or **Failed** if the record isn't found). If verification fails, double-check the record name and value and that DNS has propagated, then try again — *"Domain verification failed. Please ensure the DNS record is correct and has propagated."*
> **Why the exact domain matters** — SSO routes users by their **email domain**, and the domain must match exactly. A user with `name@example.com` is matched to the `example.com` connection.
***
### 18.4 Enabling & Enforcing SSO
Once your domain is verified, you control two switches.
#### Enable or disable
* **Enable SSO** — makes SSO available for users on your domain. (Only available once the domain is verified.)
* **Disable SSO** — turns it off again.
When enabled, the page shows **"SSO is enabled and active."**
#### Optional or enforced
* **Force SSO Login** — requires everyone on your domain to authenticate through SSO (password login is no longer offered for them). Shown as **"SSO Login is Forced."**
* **Allow Normal Logins** — reverts to optional, letting users choose SSO or password.
Force SSO can only be turned on when SSO is already enabled and the domain is verified.
> **Tip** — leave SSO **enabled but not forced** at first. Confirm a few users can sign in via SSO successfully, then **Force SSO Login** to make it mandatory.
***
### 18.5 Signing In with SSO
From your team's perspective, SSO adds an option to the login screen.
#### The sign-in flow
1. On the FullSession login page, choose the **Sign in with SSO** tab.
2. Enter your work **email** and click **Sign In with SSO**.
3. FullSession checks whether your email's domain has SSO configured. If it does, you're redirected to your IdP to authenticate (or signed straight through if you already have an IdP session).
4. After your IdP confirms your identity, you land in FullSession.
#### Fallbacks
* If a user's domain **has no SSO**, they simply use password sign-in as normal.
* If SSO is **enabled but not forced**, users can choose either method.
* If SSO is **forced** for the domain, those users sign in through SSO.
> **Remember** — the user must already exist in your account. If someone authenticates via your IdP but has no FullSession account, sign-in fails. Invite them first (\[Chapter 16, section 16.2]).
***
### 18.6 Managing the Connection, Limits & Troubleshooting
#### Viewing and editing the connection
Once configured, the SSO page shows the connection's **type, domain, entry point, issuer**, and a **View Certificate** option (opens the certificate in a modal). You can **edit** the IdP details or domain (requires `sso:edit`) and **Delete SSO Connection** from the Danger Zone (requires `sso:delete`) — deleting it means *"Users will no longer be able to sign in using SSO."*
#### Permissions
| Permission | Allows |
| ------------ | ----------------------------------------- |
| `sso:view` | See the SSO settings |
| `sso:create` | Create the SSO connection |
| `sso:edit` | Edit details, enable/disable, force/allow |
| `sso:delete` | Delete the connection |
#### Limitations
To set expectations clearly, these **don't exist**:
* **No automatic provisioning** — no JIT user creation and **no SCIM**. Users are invited manually.
* **No default-role assignment via SSO** — roles are managed in **Users** ([Chapter 16](/16.-team-and-account-management.md)).
* **One connection, one domain per account** — there's no multi-connection or multi-domain SSO.
* **SP-initiated only** — there's no IdP-initiated (tile/portal) launch.
* **No attribute-mapping UI** — FullSession reads standard name/email claims automatically; there's nothing to configure.
* **SAML only** — no OIDC/OAuth IdP connections, and no IdP-specific setup templates.
#### Troubleshooting
| Symptom | Check |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Can't click **Enable SSO** | The **domain isn't verified yet** — complete the DNS TXT step (section 18.3) |
| Domain verification **fails** | Confirm the TXT record name (`_fus_domain_verification`) and value are exact, and that DNS has propagated |
| A user's SSO login **fails** | Confirm they have a **FullSession account** (invite first) and that their email domain **exactly matches** the configured domain |
| Users still see password login when you expected SSO | SSO may be **enabled but not forced** — use **Force SSO Login** to require it |
| SAML assertion rejected | Re-check the **IdP SSO URL, Entity ID, and certificate** you entered, and that your IdP is using the **ACS URL** from Step 1 |
> **The big picture** — FullSession SSO is a **SAML 2.0** integration: exchange metadata (FullSession's SP details ↔ your IdP's details), **verify your domain** via a DNS TXT record, then **enable** (and optionally **force**) SSO. Users sign in from the **"Sign in with SSO"** tab by email. It's **one connection per domain**, **SP-initiated**, and authenticates **existing** users only — so **invite your team first**, with **no JIT/SCIM provisioning** and no attribute-mapping to configure.
***
> **Next up:** \[Chapter 19 — Integrations] covers the third-party connections referenced throughout this manual — Zapier, Slack, Intercom, Optimizely, HubSpot, and Shopify — and how they extend FullSession.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.fullsession.io/18.-single-sign-on-sso.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.