# Single sign-on (SAML)

> Let your team sign in to intoCHAT with your identity provider over SAML 2.0: setup for Okta, Microsoft Entra ID and Google Workspace, domain verification, automatic team membership, requiring SSO, two-factor and troubleshooting. Enterprise plan.

Single sign-on (SSO) lets people from your company sign in to intoCHAT with your identity provider (IdP), such as Okta, Microsoft Entra ID (formerly Azure AD) or Google Workspace, instead of a separate intoCHAT password. intoCHAT works with any IdP that supports SAML 2.0.

> Single sign-on is part of the **Enterprise** plan. On other plans, **Settings**, **Single sign-on** explains this and nothing can be set up. See [Plans and limits](/en/docs/plans-and-limits).

## How it works

- You, the account owner, connect your IdP under **Settings**, **Single sign-on** and verify the email domains your company uses, such as `acme.com`.
- On the sign-in page, people click **Sign in with SSO**, enter their work email and are sent to your IdP. After they sign in there, they're back in intoCHAT, in your account.
- Someone who signs in with SSO for the first time joins your [team](/en/docs/team) automatically, with the role you choose, if a seat is free. Nobody needs an invitation.
- You can [require SSO](#require-sso) for everyone on your domains, so they can't sign in with a password or Google instead.

Only the account owner can set up and change single sign-on. Admins can open the page and see how it's set up; editors and viewers don't see it. A super admin viewing your account for support can't change it either.

## Set up single sign-on

1. Go to **Settings**, **Single sign-on** and click **Set up single sign-on**. Nothing changes for anyone until you switch it on.
2. Under **Details for your identity provider**, copy the **ACS URL**, the **Entity ID** and the **Metadata URL**. Create a SAML app in your IdP with them: see [Okta](#okta), [Microsoft Entra ID](#microsoft-entra-id) or [Google Workspace](#google-workspace).
3. Under **Identity provider**, paste your IdP's metadata XML, or choose **Enter manually** and enter its entity ID, sign-in URL (SSO URL) and signing certificate. Click **Save identity provider**.
4. Under **Domains**, add your email domains and [verify them](#verify-your-domains).
5. Choose the **Role for new members**: Viewer, Editor or Admin.
6. Click **Test sign-in** to check that your IdP and intoCHAT understand each other. See [Test sign-in](#test-sign-in).
7. Switch on **Enabled**.

**Enabled** can only be switched on once the IdP's entity ID, sign-in URL and a current certificate are saved and at least one domain is verified. Until then, the **Status** card lists what's missing.

### What your IdP needs to send

- **The person's email address** as the NameID (format "EmailAddress" or "Unspecified"), or in an attribute named `email`. intoCHAT uses it to find or add the person.
- **A signed assertion.** intoCHAT refuses a response whose assertion isn't signed with the certificate you saved, even if the response around it is signed.
- **The person's name** (optional) in an attribute named `displayName`, or `firstName` and `lastName`. It's used when someone joins for the first time.

intoCHAT doesn't sign its requests and doesn't need encrypted assertions, so you don't need to upload an intoCHAT certificate to your IdP. The certificate you paste is your IdP's public signing certificate. Never paste a private key; intoCHAT refuses one.

## Okta

1. In the Okta Admin Console, go to **Applications**, **Applications**, click **Create App Integration**, choose **SAML 2.0** and click **Next**.
2. Name the app, for example intoCHAT, and click **Next**.
3. Set **Single sign-on URL** to the **ACS URL** from intoCHAT, and leave **Use this for Recipient URL and Destination URL** ticked.
4. Set **Audience URI (SP Entity ID)** to the **Entity ID** from intoCHAT.
5. Set **Name ID format** to **EmailAddress** and **Application username** to **Email**.
6. Optional: under **Attribute Statements**, add `email` with the value `user.email`, and `displayName` with `user.displayName`.
7. Click **Next**, then **Finish**.
8. On the app's **Sign On** tab, copy the **Metadata URL** and open it, or click **View SAML setup instructions**. Paste the metadata XML into intoCHAT under **Identity provider**.
9. On the **Assignments** tab, assign the people or groups who should use intoCHAT.

Okta signs the assertion by default. Leave **Assertion Signature** set to **Signed**.

## Microsoft Entra ID

1. In the Microsoft Entra admin center, go to **Enterprise applications**, click **New application**, then **Create your own application**. Name it, choose **Integrate any other application you don't find in the gallery (Non-gallery)** and click **Create**.
2. Open **Single sign-on** and choose **SAML**.
3. Under **Basic SAML Configuration**, click **Edit**. Set **Identifier (Entity ID)** to the **Entity ID** from intoCHAT and **Reply URL (Assertion Consumer Service URL)** to the **ACS URL**. Leave **Sign on URL** and **Relay State** empty. Save.
4. Under **Attributes & Claims**, check that **Unique User Identifier (Name ID)** is `user.mail` (or `user.userprincipalname` if that is each person's email address). Entra also sends the email in its `emailaddress` claim, which intoCHAT reads.
5. Under **SAML Certificates**, download **Federation Metadata XML** and paste its contents into intoCHAT under **Identity provider**.
6. Under **Users and groups**, add the people or groups who should use intoCHAT.

Entra signs the assertion by default (**Signing Option**: "Sign SAML assertion"). If you change it, choose "Sign SAML response and assertion", not "Sign SAML response" alone.

## Google Workspace

1. In the Google Admin console, go to **Apps**, **Web and mobile apps**, click **Add app** and choose **Add custom SAML app**.
2. Name the app, for example intoCHAT, and click **Continue**.
3. Click **Download Metadata** to save the IdP metadata, then click **Continue**. Paste the file's contents into intoCHAT under **Identity provider**.
4. Set **ACS URL** to the **ACS URL** from intoCHAT and **Entity ID** to the **Entity ID**. Leave **Signed response** unticked or ticked: the assertion is signed either way.
5. Set **Name ID format** to **EMAIL** and **Name ID** to **Basic Information**, **Primary email**. Click **Continue**.
6. Optional: under **Attribute mapping**, map **Primary email** to `email`. Click **Finish**.
7. Open the app's **User access** and turn it **ON for everyone**, or for the organizational units that should use intoCHAT.

## Verify your domains

Single sign-on only works for email addresses on domains you've verified. This proves your company owns the domain, so nobody else can sign people from it into their account.

1. Under **Domains**, enter a domain, such as `acme.com`, and click **Add domain**. Enter the domain only: no `https://`, no `@`. Subdomains such as `mail.acme.com` are separate domains.
2. Add the TXT record shown, `intochat-verification=…`, at your DNS provider, on the domain itself (host `@` at most providers).
3. Click **Verify**. The domain shows **Verified** once intoCHAT finds the record.

DNS changes can take a few minutes, sometimes up to 48 hours, to be seen everywhere. If the record isn't found yet, wait and click **Verify** again. Checks are limited to 20 every 10 minutes per account.

- A domain can be verified for one intoCHAT account only. If another account has already verified it, adding it is refused.
- A domain that's only added (pending) does nothing. Another account can have the same domain pending; whoever verifies it first keeps it.
- Once verified, a domain stays verified. You can remove the TXT record afterwards, but keeping it does no harm.
- To remove a domain, click the bin icon next to it. Removing your last verified domain switches single sign-on off.

## Signing in with SSO

1. On the sign-in page, click **Sign in with SSO**.
2. Enter your work email and click **Continue**.
3. Sign in at your IdP, if you aren't already.
4. You're back in intoCHAT, working in your company's account.

Sign-in always starts at intoCHAT. Starting from the intoCHAT tile in your IdP's app dashboard (IdP-initiated sign-in) isn't supported and shows "Single sign-on didn't work". It can't be tied to a sign-in someone started in their own browser, which is what keeps a response from being reused or slipped into someone else's browser. In Okta and Google Workspace you can hide the tile from users.

### Who gets in

When your IdP says who signed in, intoCHAT checks the email address:

- **Its domain must be verified** for your account, for everyone, you and existing members included. An address on any other domain is refused with a message saying the domain isn't verified.
- **You, the owner**, sign in to your account.
- **A member of your team** signs in with their current role.
- **Someone with a pending invitation** joins with the role in the invitation, which is accepted.
- **Anyone else** joins your team with the **Role for new members**. If they don't have an intoCHAT login yet, one is made for them, without a password. If they already have one (with their own account), they keep it and become a member of yours too.

Upper and lower case in the email address don't matter. Super admins (intoCHAT staff) can't sign in through SSO.

### Seats

Someone who joins through SSO takes a seat, like an invited member. Enterprise includes unlimited seats. If your account has no seat left, for example after a plan change, people who aren't on your team yet are refused with "Your organization's intoCHAT account has no seats left for new members"; current members still sign in.

### Roles and removing people

The **Role for new members** applies only to people joining for the first time. Change anyone's role later in **Settings**, **Team**; the next SSO sign-in doesn't change it back. Removing someone from the team ends their access to your account, but if they can still sign in at your IdP, their next SSO sign-in adds them again with the default role. To keep someone out, remove their access to the intoCHAT app in your IdP as well.

## Require SSO

Switch on **Require SSO for members with these domains** to make single sign-on the only way in for addresses on your verified domains:

- Signing in with an email and password is refused with "Your organization requires single sign-on for this email address", whatever password is entered.
- Signing in with Google is refused the same way.
- **You, the account owner, are never refused**, so you can always get in to fix things if your IdP has a problem.
- People who are already signed in stay signed in until they sign out or their session ends.
- It applies only while single sign-on is switched on and working (on Enterprise, with a current certificate).

Requiring SSO affects everyone with an address on your verified domains, also people who use intoCHAT for their own account rather than yours.

## Two-factor authentication

Signing in with SSO doesn't ask for an intoCHAT [two-factor](/en/docs/two-factor) code, even if the person turned it on. Your IdP is responsible for multi-factor authentication: require it there, for example with an Okta sign-on policy, Entra Conditional Access or Google 2-Step Verification. Two-factor authentication still applies when the same person signs in with their email and password.

## Test sign-in

**Test sign-in**, on the **Status** card, opens your IdP in a new tab and checks its response exactly as a real sign-in would: signature, audience, times, your domains. It works before you switch single sign-on on. A test never signs anyone in and never adds anyone to your team. When it works, the page says "Test sign-in worked" with the address your IdP sent (partly hidden).

Test with an account at your IdP whose email is on a verified domain.

## Delete single sign-on

Under **Delete single sign-on**, click **Delete single sign-on** and confirm. Sign in with SSO stops working straight away and your domains are released. People who joined through SSO stay on your team. Those without a password can sign in with Google, or set a password with **Forgot password?** on the sign-in page.

If your account leaves the Enterprise plan, the connection stays but stops working until you upgrade again, and **Require SSO** no longer applies.

## Troubleshooting

- **"Single sign-on isn't set up for this email address."** The domain of the address isn't verified for an account with single sign-on switched on, or the account is no longer on Enterprise, or its IdP certificate has expired. Check **Settings**, **Single sign-on**.
- **"Single sign-on didn't work."** intoCHAT refused your IdP's response. Common causes:
  - the ACS URL or Entity ID in your IdP doesn't exactly match the ones on the intoCHAT page (copy them again);
  - the assertion isn't signed, or is signed with a different certificate than the one saved (after your IdP rotates its certificate, paste the new one);
  - sign-in was started from the IdP's app dashboard instead of intoCHAT;
  - sign-in took longer than 10 minutes, was started in another browser, or the page was reloaded after signing in;
  - the clocks of your IdP and intoCHAT differ by more than 2 minutes.
- **"Your identity provider signed you in with an email address on a domain that isn't verified."** The address your IdP sent isn't on a verified domain. Check which address it sends (NameID or `email` attribute) and verify that domain.
- **"Your organization's intoCHAT account has no seats left for new members."** See [Seats](#seats).
- **"That sign-in link expired or was already used."** The last step of signing in must happen within a minute. Start again from **Sign in with SSO**.
- **"Too many sign-in attempts from your network."** SSO sign-ins are limited per network address. Wait 15 minutes.
- **The certificate shows "expired".** Download the current signing certificate from your IdP and save it under **Identity provider**. An expired certificate stops single sign-on.

## Limits

- SAML 2.0 only, with sign-in started at intoCHAT. No OpenID Connect, no IdP-initiated sign-in.
- One identity provider per account.
- No single logout: signing out of intoCHAT doesn't sign you out of your IdP, and the other way round.
- No SCIM. People are added when they first sign in; removing someone at your IdP doesn't remove them from your intoCHAT team.
- Encrypted assertions and signed requests aren't supported.
- Roles come from the **Role for new members** setting, not from IdP groups.