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

# Single Sign-On

> Let your team sign in to Studio through Okta, Microsoft Entra ID or Google Workspace

Single sign-on (SSO) lets your team sign in to Studio with their company account instead of a password. You verify the email domains you own, connect your identity provider, and can then require SSO for everyone at those domains.

SSO is available on the **Enterprise plan**. On any other plan the page opens with the message "Single sign-on is available on the Enterprise plan."

You manage it on the **Security & SSO** page, at **Manage → Security & SSO**. It has a card on the **Manage** hub. It isn't in your sidebar until you add it, but you can add it with **Customize sidebar** or open it by pressing **Cmd/Ctrl+K**, typing "SSO" and pressing Enter. See [Navigating Studio](https://docs.squawkvoice.ai/navigating-studio.md).

The page has three sections, in the order you use them: **Verified domains**, **SSO provider** and **Sign-in rules**. **Sign-in rules** appears once a provider is connected.

## Verified Domains

SSO works only for email addresses at a domain you've proved you own. Use the domain of the email address your identity provider sends, such as `acme.com` rather than `acme.onmicrosoft.com`.

1. Under **Verified domains**, enter one or more domains in **Add a domain**. Separate several with commas or spaces, then select **Add**.
2. Each domain appears with a **Host** and a **TXT value**. Add that TXT record at your DNS provider. DNS changes can take a few hours to show up.
3. Select **Verify** on the domain.

A domain shows one of these statuses:

| Status | What it means |
| - | - |
| **Waiting for DNS** | The domain is added, and its TXT record hasn't been found yet. |
| **Record not found** | The last check couldn't find the TXT record. Check it at your DNS provider, then select **Verify** again. |
| **Verified** | The record was found. Select **Re-check** to check it again straight away. |

A verified domain is checked again every day. If its record can't be found, the domain shows a warning with the date SSO from that domain stops, 7 days after the first missed check. Restore the record and select **Re-check** before then.

A domain can be verified by only one account at a time. To take a domain off SSO, select the bin icon on its row and confirm **Remove domain**. SSO stops for that domain, and existing users keep their access.

> [!NOTE]
>
> Anyone your identity provider lets in, at one of your verified domains, joins your account the first time they sign in with SSO. Control who can sign in by choosing who is assigned to the app in your identity provider.

## Connect Your Identity Provider

Under **SSO provider**, you connect one provider. Verify a domain first: until you do, the section says "Verify a domain above before adding a provider."

> [!TIP]
>
> Step-by-step guides cover each provider: [Okta SSO](https://docs.squawkvoice.ai/manage/okta-sso.md) (the SquawkVoice app from the Okta Integration Network), [Microsoft Entra ID SSO](https://docs.squawkvoice.ai/manage/entra-sso.md) and [Google Workspace SSO](https://docs.squawkvoice.ai/manage/google-workspace-sso.md).

1. Under **Choose your identity provider**, select **Okta**, **Microsoft Entra ID** or **Google Workspace**.
2. Choose the protocol. **SAML** is recommended, because it connects from one metadata URL. Use **OIDC** if your IT team prefers it. Google Workspace connects with SAML only.
3. Under **Add Squawk Studio in** your provider, follow the setup instructions shown for it, and copy the values Studio gives you into a new app in your identity provider. For SAML these are the **SP Entity Id** and the **Redirect URL**, labelled the way your provider names them. For OIDC it is the redirect URL. Assign the people who need access to that app.
4. Bring the connection details back to Studio.
   * **SAML**: paste your provider's metadata URL and select **Connect**. Google Workspace has no metadata URL, so paste the contents of the `GoogleIDPMetadata.xml` file you download from the Google Admin console. To type the details instead, select **Enter values manually instead** and fill in **IdP Entity Id (Issuer)**, **IdP Sign-In URL** and **X.509 certificate**.
   * **OIDC**: enter the **Client Id** and **Client secret** from your provider, and the **Issuer URL**. For Microsoft Entra ID, enter the **Directory (tenant) ID**, **Application (client) ID** and **Client secret**, using the secret's Value. Then select **Save provider**.
5. You see "SSO provider saved", or "Connected. SSO provider saved." after **Connect**, and the section shows **Connected**.

To change the details later, select **Change provider details**. You tick "I acknowledge this change will log out users currently using SSO" before saving. For OIDC, leave **Client secret** blank to keep the saved secret (the field says "Saved. Leave blank to keep it."), or enter a new one to replace it. If you change the identity provider or the protocol, enter the secret again. To disconnect the provider, select **Remove** and confirm **Remove provider**. Users can then no longer sign in with SSO, and anyone signed in with SSO is signed out.

## Require SSO

Until you require it, SSO is an extra way to sign in: password and Google sign-in keep working. Under **Sign-in rules**, turn on **Require SSO** to make SSO the only way in.

1. Switch on **Require SSO**. The **Require SSO?** window says "This account's users at its verified domains will only be able to sign in with SSO. Password and Google sign-in stop working for them, and anyone signed in that way is signed out."
2. Select **Require SSO** to confirm. You see "SSO is now required".

**Applies to** lists the domains it covers. It affects only your account's users with an email at those verified domains. Switching it off, with the same switch, lets them use a password or Google again, and you see "SSO is no longer required".

A change to this setting can take up to about a minute to apply everywhere.

> [!WARNING]
>
> Sign in with SSO yourself, as a user at a verified domain, before you turn on **Require SSO**. Once it's on, users at those domains can't sign in with a password or Google.

## Signing In With SSO

On the Studio sign-in page, select **Sign in with SSO** below the sign-in form. If you've already typed your email address, it's carried over.

1. On **Continue with SSO**, enter your **Work email** and select **Continue**. If the domain isn't set up for SSO, you see "Single sign-on is not set up for this email domain. Check the address, or sign in another way." Select **Go back** to return to the usual sign-in.
2. Select **Sign in with your company account**. Your identity provider opens in a window. Sign in there, and you're taken into Studio. If the window is blocked, allow pop-ups for the site and try again.

You can also open Studio from your identity provider's app portal. Under **Open Studio from your app portal**, the **Dashboard tile URL** is the link to add there as a tile or bookmark, and the text beneath it says where to put it in your provider. Google Workspace's app launcher tile can't sign you in, so share the link as a bookmark instead (see [Google Workspace SSO](https://docs.squawkvoice.ai/manage/google-workspace-sso.md#the-google-app-launcher)).

A user's name comes from your identity provider when they sign in, if they don't have a name yet. For SAML, your provider must send a display name, or a first and last name; if it sends neither, the name stays empty and the user can set it in **Profile Settings**. A name that is already set isn't overwritten.

An SSO sign-in lasts up to 12 hours. After that you go back to your identity provider, and Studio shows "Your single sign-on session has ended. Sign in with SSO again."

A user at a domain that requires SSO who tries a password or **Continue with Google** sees "Your organization signs in with SSO. Use "Sign in with SSO"."

People you invite whose email address is at one of your verified domains, while your SSO provider is connected, don't set a password. Their invitation link opens **Sign in with SSO to accept your invite**, and **Continue with SSO** signs them in. See [User Invitation Process](https://docs.squawkvoice.ai/manage/users.md#user-invitation-process).

## Troubleshooting

> [accordion] I see 'Single sign-on is available on the Enterprise plan.'
>
> * SSO is part of the Enterprise plan. Contact [support@squawkvoice.ai](mailto:support@squawkvoice.ai) to ask about it

> [accordion] A domain stays on Waiting for DNS or Record not found
>
> * Check that the **Host** and **TXT value** at your DNS provider match what Studio shows, with nothing added or cut off
> * DNS changes can take a few hours to show up. Select **Verify** again later

> [accordion] A domain won't verify and the record is correct
>
> * A domain can be verified by only one account at a time. If another account has already verified it, contact [support@squawkvoice.ai](mailto:support@squawkvoice.ai)

> [accordion] Someone can't sign in with SSO
>
> * Check that they're assigned to the app in your identity provider
> * Check that their email address is at one of your verified domains and that the domain shows **Verified**
> * If the provider's secret or certificate has expired, enter the new one under **Change provider details**

## Next Steps

> [card] [Users](https://docs.squawkvoice.ai/manage/users.md)
>
> Invite teammates, and how people sign in.

> [card] [Okta SSO](https://docs.squawkvoice.ai/manage/okta-sso.md)
>
> Set up SSO with the SquawkVoice app in the Okta Integration Network.

> [card] [Microsoft Entra ID SSO](https://docs.squawkvoice.ai/manage/entra-sso.md)
>
> Set up SSO with Microsoft Entra ID.

> [card] [Google Workspace SSO](https://docs.squawkvoice.ai/manage/google-workspace-sso.md)
>
> Set up SSO with a custom SAML app in Google Admin.

> [card] [Security](https://docs.squawkvoice.ai/security.md)
>
> How SquawkVoice protects your data.


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