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

# Microsoft Entra ID SSO

> Let your team sign in to SquawkVoice with Microsoft Entra ID (formerly Azure AD), using SAML

The SquawkVoice app for Microsoft Entra ID connects your Entra tenant to your SquawkVoice account with **SAML 2.0**. Once it is set up, your team signs in to SquawkVoice with their Microsoft work account, and you decide in Entra 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.
* **My Apps tile:** people click the SquawkVoice tile in Microsoft My Apps and land in SquawkVoice. The tile opens SquawkVoice, which then signs the person in through Entra, with no extra prompt if they're already signed in to Microsoft. SquawkVoice doesn't accept a SAML sign-in that starts in Entra without going through SquawkVoice first, which is why the tile needs the **Sign on URL** (step 3).
* **Just-in-time (JIT) provisioning:** the first time someone you assigned in Entra signs in, SquawkVoice creates their user in your account. Their name comes from the **given name** and **surname** claims Entra sends.

Not supported: SCIM provisioning (users aren't created, updated or deactivated from Entra ahead of sign-in), IdP-initiated SAML and Single Logout.

## 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 Microsoft Entra administrator who can add and configure Enterprise applications (for example, the **Cloud Application Administrator** role).
* 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, and neither can `onmicrosoft.com` addresses, since you can't add DNS records to that domain.

## 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 Entra, and they already carry both.

| Entra field | Value | What it carries |
| - | - | - |
| **Identifier (Entity ID)** | `squawk-studio-acct-` followed by your Account ID | your account |
| **Reply URL (Assertion Consumer Service URL)** | `https://auth.squawkvoice.ai/__/auth/handler` in the US, `https://eu.auth.squawkvoice.ai/__/auth/handler` in the EU | your region |
| **Sign on URL** | the **Dashboard tile URL**, such as `https://app.squawkvoice.ai/auth/sso?provider=saml.acct-…` (`eu.app.squawkvoice.ai` in the EU) | both |

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 the SquawkVoice app in Entra**

In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Enterprise applications** and click **New application**. Search for **SquawkVoice**, select it and click **Create**.

> [!NOTE]
>
> If SquawkVoice isn't listed in the gallery yet, click **Create your own application**, name it `SquawkVoice`, choose **Integrate any other application you don't find in the gallery (Non-gallery)** and click **Create**. Everything below is the same.

**3. Enter the SAML values**

1. In SquawkVoice, on **Manage → Security & SSO**, under **SSO provider**, choose **Microsoft Entra ID** and **SAML**. Keep this page open: step 2 on it shows the values to copy.
2. In Entra, open the app's **Single sign-on** page and choose **SAML**.
3. Under **Basic SAML Configuration**, click **Edit** and enter:
   * **Identifier (Entity ID):** the **Identifier (Entity ID)** from SquawkVoice. Remove any other identifier and leave **Default** ticked for this one.
   * **Reply URL (Assertion Consumer Service URL):** the **Reply URL** from SquawkVoice.
   * Leave **Relay State** and **Logout Url** empty. You add the **Sign on URL** in step 5.
4. Click **Save**.

**4. Check the claims and connect**

1. Under **Attributes & Claims**, check that **Unique User Identifier (Name ID)** is the person's email at your verified domain. The default, `user.userprincipalname`, works when your users sign in to Microsoft with their email address. If their user principal name is at another domain (such as `onmicrosoft.com`), change it to `user.mail`.
2. Keep the default **givenname** and **surname** claims: SquawkVoice uses them for the person's name.
3. Under **SAML Certificates**, copy the **App Federation Metadata Url**.
4. Back on **Manage → Security & SSO**, paste it into **Metadata URL** and click **Connect**.

**5. Add the Sign on URL for the My Apps tile**

1. On **Manage → Security & SSO**, under **Open Studio from your app portal**, copy the **Dashboard tile URL**.
2. In Entra, edit **Basic SAML Configuration** again, paste it as the **Sign on URL**, and click **Save**.

With a Sign on URL, the SquawkVoice tile in My Apps opens SquawkVoice, which signs the person in through Entra. Without one, the tile tries to sign in from Entra directly, which SquawkVoice refuses.

**6. Assign people**

In the app's **Users and groups** page, click **Add user/group** and assign the people or groups who should be able to sign in to SquawkVoice. Only assigned people can sign in while the app's **Assignment required?** property is **Yes**, the default.

**7. 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 Microsoft to sign in, then back to SquawkVoice.

**From My Apps:** click the **SquawkVoice** tile at [myapps.microsoft.com](https://myapps.microsoft.com).

## How Users Work

* **New users:** someone you've assigned in Entra 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 Entra. A user who belongs to a different SquawkVoice account can't sign in to yours with SSO.
* **Removing access:** removing someone's assignment in Entra 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 Entra's Signing Certificate Changes

SquawkVoice reads Entra's signing certificate when you click **Connect**. Entra's certificate lasts three years, and Entra emails the notification address under **SAML Certificates** before it expires.

When you create or activate a new certificate in Entra, sign-in stops working until SquawkVoice reads it:

1. On **Manage → Security & SSO**, click **Change provider details**.
2. Paste the same **App Federation Metadata Url** (it doesn't change) and click **Connect**.

Do this right after you make the new certificate active in Entra.

## 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. |
| Microsoft shows `AADSTS50105` (the user isn't assigned to the application) | Assign the person, or a group they're in, on the app's **Users and groups** page. |
| Microsoft shows `AADSTS700016` or `AADSTS650056` | The **Identifier (Entity ID)** in Basic SAML Configuration is exactly the one on **Security & SSO**. |
| Microsoft shows `AADSTS50011` (reply URL mismatch) | The **Reply URL** is exactly the one on **Security & SSO**, for your region. |
| "Your organization has not enabled sign-in with SSO for this account." after signing in to Microsoft | The **Unique User Identifier (Name ID)** is the person's email at a domain verified on **Security & SSO** of this account (step 4). |
| Sign-in fails after Microsoft with an `invalid-credential` error | Entra's signing certificate changed. Connect the metadata URL again ([see above](#when-entras-signing-certificate-changes)). |
| The My Apps tile shows an error | The **Sign on URL** in Basic SAML Configuration is the **Dashboard tile URL** from **Security & SSO** (step 5). |
| "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.