> ## 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.

# Google Workspace SSO

> Let your team sign in to SquawkVoice with their Google Workspace accounts, using SAML

You connect Google Workspace to your SquawkVoice account with a **custom SAML app** in the Google Admin console. Once it is set up, your team signs in to SquawkVoice with their Google Workspace account, and you decide in Google Admin who can get in.

## Supported Features

* **SP-initiated SSO:** people start on the SquawkVoice sign-in page, click **Sign in with SSO** and enter their work email, or open the **Dashboard tile URL** from a bookmark.
* **Just-in-time (JIT) provisioning:** the first time someone you turned the app on for signs in, SquawkVoice creates their user in your account.

Not supported: signing in from the Google app launcher (see [The Google App Launcher](#the-google-app-launcher)), SCIM provisioning (users aren't created, updated or deactivated from Google ahead of sign-in), IdP-initiated SAML and Single Logout. Google Workspace connects with SAML only.

## Requirements

* A SquawkVoice Enterprise plan.
* Access to **Manage → Security & SSO** in SquawkVoice. If it isn't in your sidebar, search for **SSO**, or add it with **Customize sidebar**.
* A Google Workspace **super administrator**: only a super administrator can add a custom SAML app.
* A company email domain your team signs in with, where you can add a DNS TXT record. Free email domains such as gmail.com can't be used.

## Your Account and Region

SquawkVoice gives every account its own SAML values. You don't type your Account ID or region anywhere: you copy the values that **Manage → Security & SSO** shows for your account into Google Admin, and they already carry both.

| Google Admin field | Value | What it carries |
| - | - | - |
| **ACS URL** | `https://auth.squawkvoice.ai/__/auth/handler` in the US, `https://eu.auth.squawkvoice.ai/__/auth/handler` in the EU | your region |
| **Entity ID** | `squawk-studio-acct-` followed by your Account ID | your account |

Always copy them from your own **Security & SSO** page rather than from this table, so the account and region are right.

## Configuration Steps

**1. Verify your email domain in SquawkVoice**

In SquawkVoice, open **Manage → Security & SSO**. Under **Verified domains**, enter your company's email domain and add it.

SquawkVoice shows a **Host** and a **TXT value**. Add them as a TXT record in your domain's DNS, then click **Verify**. DNS changes can take a while to be visible; if the record isn't found yet, try again later.

Only people whose email is at a verified domain can sign in with SSO.

**2. Add a custom SAML app in Google Admin**

1. In SquawkVoice, on **Manage → Security & SSO**, under **SSO provider**, choose **Google Workspace**. Keep this page open: it shows the values to copy.
2. In the [Google Admin console](https://admin.google.com), go to **Apps → Web and mobile apps**, click **Add app** and choose **Add custom SAML app**.
3. Name the app `SquawkVoice` and click **Continue**.

**3. Download Google's metadata**

On **Google Identity Provider details**, click **Download metadata** and save the file (`GoogleIDPMetadata.xml`). Then click **Continue**.

Google has no metadata URL, so you paste this file's contents into SquawkVoice in step 6.

**4. Enter the SquawkVoice values**

On **Service provider details**, enter:

* **ACS URL:** the **ACS URL** from SquawkVoice.
* **Entity ID:** the **Entity ID** from SquawkVoice.
* Leave **Start URL** empty and **Signed response** unticked.
* **Name ID format:** `EMAIL`.
* **Name ID:** **Basic Information → Primary email**.

Click **Continue**.

**5. Map the name attributes**

On **Attribute mapping**, add two mappings so SquawkVoice gets each person's name:

| Google Directory attributes | App attributes |
| - | - |
| **Basic Information → First name** | `firstName` |
| **Basic Information → Last name** | `lastName` |

Click **Finish**. Without these mappings, sign-in still works, but new users are created without a name.

**6. Connect SquawkVoice**

1. Open the downloaded `GoogleIDPMetadata.xml` in a text editor and copy all of it.
2. Back on **Manage → Security & SSO**, paste it into **Metadata XML** and click **Connect**.

**7. Turn the app on for your people**

In Google Admin, open the **SquawkVoice** app, click **User access**, and turn it **ON** for the people who should be able to sign in:

* **Everyone:** select your top-level organizational unit and choose **ON for everyone**.
* **An organizational unit** (such as a department): select it on the left and choose **ON**.
* **A group:** select it under **Groups** and choose **ON**. Use this for people spread across organizational units.

Click **Save**. Google says changes can take up to 24 hours, though they usually apply sooner.

**8. Share the sign-in link**

On **Manage → Security & SSO**, under **Open Studio from your app portal**, copy the **Dashboard tile URL** and share it with your team as a bookmark. Opening it starts the SSO sign-in straight away.

**9. Optionally, require SSO**

Under **Sign-in rules**, turn on **Require SSO** to make SSO the only way your users at your verified domains can sign in. Password and Google sign-in stop working for them, and anyone signed in that way is signed out.

Test an SSO sign-in before you turn this on.

## Signing In

**From SquawkVoice (SP-initiated):**

1. Go to `app.squawkvoice.ai`, or `eu.app.squawkvoice.ai` in the EU.
2. Click **Sign in with SSO**.
3. Enter your work email and continue. You're sent to Google to sign in, then back to SquawkVoice.

**From a bookmark:** open the **Dashboard tile URL** your administrator shared.

## The Google App Launcher

Once the app is on, Google also shows a **SquawkVoice** tile in your users' Google app launcher. That tile starts the sign-in from Google's side, which SquawkVoice doesn't accept, and Google offers no setting to make the tile open SquawkVoice first. Ask your team to use **Sign in with SSO** or the bookmark instead.

## How Users Work

* **New users:** someone the app is on for who has no SquawkVoice user yet gets one in your account the first time they sign in, with standard account access.
* **Existing users:** people who already have a SquawkVoice user in your account keep it and can now sign in with Google Workspace. A user who belongs to a different SquawkVoice account can't sign in to yours with SSO.
* **Removing access:** turning the app off for someone stops their next SSO sign-in, but doesn't delete their SquawkVoice user. An SSO session lasts at most 12 hours before SquawkVoice asks the person to sign in again.

## When Google's Signing Certificate Changes

SquawkVoice reads Google's signing certificate from the metadata you paste. Google's certificate lasts five years. Super administrators manage certificates under **Security → Authentication → SSO with SAML applications**.

When you assign a new certificate to the SquawkVoice app, sign-in stops working until SquawkVoice reads it:

1. In Google Admin, open the **SquawkVoice** app and download the metadata again (it now holds the new certificate).
2. On **Manage → Security & SSO**, click **Change provider details**.
3. Paste the new file's contents into **Metadata XML** and click **Connect**.

Do this right after you assign the new certificate in Google.

## Troubleshooting

| What you see | What to check |
| - | - |
| "Single sign-on is not set up for this email domain." | The email's domain is verified on **Security & SSO** and the provider is saved. |
| Google shows `403 app_not_enabled_for_user` | Turn the app on for the person, their organizational unit or a group they're in (step 7). Changes can take a while to apply. |
| Google shows `403 app_not_configured_for_user` | The **Entity ID** in the app's **Service provider details** is exactly the one on **Security & SSO**. |
| "Your organization has not enabled sign-in with SSO for this account." after signing in to Google | The **Name ID** is **Primary email**, and the person's primary email is at a domain verified on **Security & SSO** of this account (step 4). |
| Sign-in fails after Google with an `invalid-credential` error | Google's signing certificate changed, or the metadata pasted is from another app. Download the metadata again and connect it ([see above](#when-googles-signing-certificate-changes)). |
| The Google app launcher tile shows an error | Expected: use **Sign in with SSO** or the bookmark ([see above](#the-google-app-launcher)). |
| "Your user belongs to a different account." | The person already has a SquawkVoice user in another account. Sign in the way you usually do, or contact support. |

For help, contact [support@squawkvoice.ai](mailto:support@squawkvoice.ai).


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