> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cassidyai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Set up SSO
> Enable SAML-based Single Sign-On so your team can log in to Cassidy with your identity provider.
Single Sign-On (SSO) lets your team sign in to Cassidy using your existing identity provider (IdP) — like Okta or Microsoft Entra ID (formerly Azure AD). Once enabled, users authenticate through your IdP instead of managing a separate Cassidy password.
SSO is available on **Enterprise** plans only. [Contact us](mailto:support@cassidyai.com) to learn more or upgrade.
## Verify your domain
Before you can enable SSO, you need to verify that you own the email domain your team uses to sign in.
Click your account name at the bottom of the sidebar, then click the **gear icon** next to your organization name.
In the left sidebar, click **Single Sign-On**. You'll see the SSO configuration panel.
Click **Add Verified Domain** and enter the email domain you want to enable for SSO (e.g., `yourcompany.com`).
Cassidy will provide a **TXT record** to add to your domain's DNS settings. Copy the record value and add it to your DNS provider.
DNS changes can take up to 48 hours to propagate, but most providers update within a few minutes.
Once you've added the TXT record to your DNS provider, return to Cassidy and click **Verify Domain**.
Once the TXT record is detected, your domain is verified.
Your domain is verified. You can now enable Single Sign-On.
## Enable SSO
Once you have at least one verified domain, you can enable SSO.
On the **Single Sign-On** settings page, click **Enable Single Sign-On**. This opens the SSO configuration modal.
The modal has two sections:
* **Identity provider details** — Enter your IdP's Entity ID, SSO URL, and public certificate. You can fill these in manually, or **upload your IdP's metadata XML** to auto-fill all three fields at once.
* **Service provider details** — Copy Cassidy's Entity ID and Sign-In URL into your IdP's configuration. Some IdPs also support importing an SP metadata file — click **download our SP metadata** to get the file.
## Configure your identity provider
Cassidy works with any SAML 2.0 identity provider. Below are step-by-step guides for Okta and Microsoft Entra ID — if you use a different provider, the general flow is the same: create a SAML application in your IdP, enter Cassidy's SP values, configure attribute mappings, and copy your IdP's values back into Cassidy.
In your Okta admin dashboard, go to **Applications** → **Create App Integration**. Select **SAML 2.0** as the sign-in method.
Enter the following values from Cassidy's SSO configuration modal:
| Okta field | Value |
| ------------------------------- | ------------------------------ |
| **Single sign-on URL** | Copy from Cassidy SSO settings |
| **Audience URI (SP Entity ID)** | Copy from Cassidy SSO settings |
Map the following user attributes so Cassidy can identify users:
| Name | Value |
| ----------- | ---------------- |
| `email` | `user.email` |
| `firstName` | `user.firstName` |
| `lastName` | `user.lastName` |
In Okta, go to the **Assignments** tab of your new app and assign it to the users or groups who should have access to Cassidy.
After saving the Okta app, go to the **Sign On** tab and copy the following values into Cassidy's SSO configuration modal:
* **Sign on URL** (also called SSO URL or Login URL)
* **Issuer** (also called Entity ID)
* **Signing Certificate** (download the X.509 certificate)
Instead of copying values individually, you can upload Okta's metadata XML into the Cassidy modal to auto-fill all fields. You can also upload the certificate file directly instead of pasting its contents.
In the [Azure portal](https://portal.azure.com), go to **Microsoft Entra ID** → **Enterprise Applications** → **New Application** → **Create your own application**. Name it "Cassidy" and select **Integrate any other application you don't find in the gallery (Non-gallery)**.
Go to **Single sign-on** → **SAML**.
In the **Basic SAML Configuration** section, enter the values from Cassidy's SSO configuration modal:
| Entra ID field | Value |
| -------------------------- | ------------------------------ |
| **Identifier (Entity ID)** | Copy from Cassidy SSO settings |
| **Reply URL (ACS URL)** | Copy from Cassidy SSO settings |
Instead of entering these values manually, you can **download Cassidy's SP metadata** from the SSO configuration modal and import it into Entra ID's SAML configuration.
Under **Attributes & Claims**, map the following:
| Claim name | Source attribute |
| ----------- | ---------------- |
| `email` | `user.mail` |
| `firstName` | `user.givenname` |
| `lastName` | `user.surname` |
From the SAML configuration page in Entra ID, copy the following into Cassidy's SSO configuration modal:
* **Login URL**
* **Azure AD Identifier** (Entity ID)
* **Certificate (Base64)** — download and paste the contents
Instead of copying values individually, you can upload Entra ID's metadata XML into the Cassidy modal to auto-fill all fields. You can also upload the certificate file directly instead of pasting its contents.
## Verify and enable
After entering your IdP settings into the Cassidy configuration modal, click **Verify and Enable**. You'll be redirected through the SAML sign-in process to verify your settings are correct.
SSO sign-in respects your organization's join settings. If your organization requires invitations or admin approval for new members, those rules still apply when users sign in through SSO for the first time. See [Invite team members](/settings/invite-team-members) for details.
SSO is now enabled. Team members with email addresses on your verified domain will be redirected to your identity provider when signing in.
## Set up SAML group mappings
SAML group mappings let you map attributes in your identity provider's SAML response to Cassidy [groups](/settings/roles-and-groups). Use group mappings to automatically place people into the teams that control resource visibility.
When a user signs in through your IdP, Cassidy checks the user's SAML assertion and adds the user to Cassidy groups based on the mappings you've configured.
Groups control which shared resources a user can see. To automatically grant privileges for what a user can do, use [SAML role mappings](#set-up-saml-role-mappings).
### Important behavior
* **Case-sensitive** — Attribute keys and values must match exactly.
* **Additive only** — Cassidy adds users to groups when a mapping matches, but does not remove users from groups if the attribute is later removed in your IdP. Users also keep any groups they were already in.
* **Visibility only** — Group mappings update group membership. They do not grant privileges like creating Agents or managing settings.
* **Multi-value attributes supported** — If an attribute contains multiple values (e.g., a `groups` attribute with a list of group IDs), the mapping matches if any of the values exactly equals the mapping's configured value.
### Prerequisites
Before turning on mappings, make sure you understand exactly what attributes your IdP is sending in the SAML assertion — mappings only work if the attribute key and value are correct.
* Many IdPs require you to explicitly configure which attributes (including group membership) are included in the SAML assertion. If group membership isn't being sent, Cassidy won't have anything to map.
* **Microsoft Entra ID** often sends group Object IDs rather than group names. If you map by group, you typically need to use the ID values Entra ID sends.
* It's recommended to inspect and validate a SAML response to confirm the exact attribute key and value your IdP is sending (e.g., using [samltool.com](https://www.samltool.com/validate_response.php)) before creating mappings.
* SSO must be [enabled](#enable-sso) for your organization before you can configure group mappings.
### Configure mappings
In **Organization Settings** → **Single Sign-On**, click the **Group Mappings** tab.
Click **Add Group Mapping** to create a new mapping rule. Enter:
* **SAML Attribute Key** — The attribute name your IdP sends (e.g., `groups`, `memberOf`, or a custom attribute).
* **SAML Attribute Value** — The specific value to match (e.g., a group name or group Object ID, depending on your IdP).
* **Cassidy Group** — The Cassidy [group](/settings/roles-and-groups) to assign users to when the match is found.
Your IdP must include group membership in the SAML assertion under the same attribute key you configured in the mapping. If group membership isn't being sent, Cassidy won't have anything to map.
In Okta, configure a **group attribute statement** in your SAML application's settings. This tells Okta to include the user's group memberships in the SAML assertion.
In Entra ID, add a **Group Claim** in the **Attributes & Claims** section of your SAML application and set a custom claim name (e.g., `groups`). Entra ID typically sends group Object IDs rather than names, so use the ID values as your SAML Attribute Value.
Back in Cassidy, repeat step 2 for each group you want to map. The key should match the attribute name your IdP sends, and the value should match the exact value sent by your IdP for each group.
To learn more about creating and managing groups in Cassidy, see [Assign roles and groups](/settings/roles-and-groups).
Click **Save**. Mappings are applied the next time users sign in via SSO. Have a team member sign in to verify they are automatically assigned to the correct Cassidy groups based on their SAML group membership.
Group mappings are active. Users will be automatically assigned to Cassidy groups on their next SSO login.
## Set up SAML role mappings
SAML role mappings let you map attributes in your identity provider's SAML response to Cassidy [roles](/settings/roles-and-groups). When a user signs in through your IdP, Cassidy checks the user's SAML assertion and grants them any role whose mapping matches.
A mapping can target either a built-in **managed role** (Admin, Member, Viewer) or any **custom role** you've created.
Use role mappings for privileges like creating Agents, editing Workflows, inviting team members, managing groups, or configuring organization settings.
### Important behavior
* **Case-insensitive match** — Attribute keys are case-sensitive, but attribute values are compared case-insensitively.
* **Additive only** — Cassidy assigns matching roles when a user signs in but does not remove existing role assignments if the attribute is later removed in your IdP.
* **Multi-value attributes supported** — If an attribute contains multiple values, the mapping matches if any value equals the mapping's configured value.
* **Multiple mappings stack** — A user can match multiple role mappings on a single login, in which case they receive every matching role.
### Prerequisites
* SSO must be [enabled](#enable-sso) for your organization before you can configure role mappings.
* Custom-role targets require the destination role to already exist. Create roles in **Organization Settings** → **Roles & Groups** first.
* As with group mappings, validate the exact attribute key and value your IdP sends (for example using [samltool.com](https://www.samltool.com/validate_response.php)) before creating mappings.
### Configure mappings
In **Organization Settings** → **Single Sign-On**, click the **Role Mappings** tab.
Click **Add Role Mapping** to create a new mapping rule. Enter:
* **SAML Attribute Key** — The attribute name your IdP sends (e.g., `groups`, `memberOf`, or a custom attribute).
* **SAML Attribute Value** — The specific value to match (e.g., a group name or Object ID, depending on your IdP).
* **Cassidy Role** — The managed or custom role to grant when the match is found.
Repeat step 2 for each role you want SSO to grant. A user matching multiple mappings receives all the matching roles, and their effective privileges are the union of those roles.
Mappings are applied the next time users sign in via SSO. Have a team member sign in to verify they are automatically granted the correct roles.
Role mappings are active. Users will be automatically granted matching roles on their next SSO login.
## Next steps
Create and configure the roles and groups that SSO maps to.
Manually invite users who aren't covered by SSO.