> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.caimera.ai/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Set Up Microsoft SSO for Your Caimera Workspace

Connect your Microsoft Entra organization to Caimera so your team signs in with their work Microsoft accounts. Caimera provides the Microsoft application, so you don't need to create an app registration or manage a client secret.

## Before you start

* **Caimera:** workspace administrator access.
* **Microsoft:** an Entra admin who can grant consent for your organization (Global Administrator, Application Administrator, or Cloud Application Administrator).
* Your **Directory (tenant) ID**, from **Entra ID → Overview → Properties**. This is not the Application (client) ID.
* A Microsoft work account that matches the Caimera admin doing the setup.
* A password manager or other secure place outside Caimera for your recovery code.
* Optional: DNS access, if you want employees to find SSO from their work email.

## Step 1: Connect your Microsoft organization

1. In Caimera, open your workspace and go to **Settings → SSO**.
2. Paste your tenant ID into **Directory tenant ID** and select **Connect organization**.
3. Sign in to Microsoft as an Entra admin, review the permissions, and select **Accept**.
4. Return to Caimera in the same browser. The status shows **Connected**.

![Enter your Directory tenant ID](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/01-enter-tenant-id_gbz81h.png =600x172)

![Connected, test sign-in required](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/02-connected-test-required_16ettqm.png =600x167)

The Entra admin who approves access can be a different person from the Caimera admin.

## Step 2: Verify sign-in

1. Select **Test sign-in**.
2. Sign in with the Microsoft work account that matches your Caimera admin account.
3. Back in **Settings → SSO**, confirm you see **Sign-in verified**.

![Connected and sign-in verified](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/03-sign-in-verified_1adqion.png =600x210)

If your Caimera account uses Google, email, or a password, sign in with that method first, then complete the Microsoft sign-in in the same session to link the accounts.

## Step 3: Save a recovery code

The recovery code lets you turn off required Microsoft login if your organization ever can't sign in. You need it before you can enforce SSO.

1. Under **Workspace recovery**, select **Generate recovery code**.
2. Copy or download the code and store it outside Caimera.
3. Tick the confirmation checkbox and select **Confirm saved recovery code**.
4. Select **Open workspace recovery** and bookmark the page that opens.

![Generate a recovery code](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/04-generate-recovery-code_17psljo.png =600x204)

![Recovery code saved](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/05-recovery-code-saved_tap74t.png =600x167)

The admin who generates the code becomes the recovery administrator and must remain a workspace admin. Each code works once. If it's lost or exposed, generate a new one.

## Step 4: Choose sign-in and provisioning settings

**Require Microsoft login.** Available once sign-in is verified and a recovery code is saved. Tell your team first and have one member confirm they can sign in. When on, members must use Microsoft, and sessions using other methods are signed out. Turn it off to allow other sign-in methods again.

![Require Microsoft login](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/06-require-microsoft-login_1mn2fb1.png =600x146)

**Automatically add organization users (optional).** Eligible employees join as members on their first Microsoft sign-in, as long as seats are available. This never grants admin access. Your Entra app assignment policies still apply. When off, new users need an invitation.

![Automatically add organization users](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/07-auto-add-users_rgtfoc.png =600x112)

Hover over a greyed-out setting to see what's missing.

## Step 5: Verify your email domains (optional)

Verified domains let employees type their work email and land on your Microsoft login. This does not add anyone to the workspace on its own.

1. Under **Domain verification**, enter a domain like `example.com` (no `https://`) and select **Add domain**.
2. In your DNS provider, add a **TXT** record on that domain with the value shown in Caimera (it starts with `caimera-domain-verification=`). Use `@` as the host for a root domain. Leave existing TXT records in place.
3. Back in Caimera, select **Verify DNS record**. The domain shows **Verified** when it's ready.

![Pending domain verification with the TXT record](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/08-domain-pending-txt_16z1x7g.png =600x397)

![Verified domain](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/09-domain-verified_mgybc9.png =600x222)

Complete verification within 48 hours, or generate a new record. A domain can only be verified by one workspace. Repeat for each domain or subdomain you use.

## How your team signs in

1. On Caimera's sign-in page, select **Sign in with SSO**.
2. Enter a work email and select **Continue with SSO**.
3. Sign in with Microsoft.

![Continue with SSO on the sign-in page](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/10-continue-with-sso_1lwgwm.png =360x453)

If you haven't verified a domain, share your workspace's Microsoft sign-in page with your team instead.

## Recovering access

If your organization can't sign in while Microsoft login is required:

1. Open your bookmarked recovery page, or select **Workspace admin recovery** on the workspace login page.
2. Enter the recovery admin's email and the recovery code.
3. Select **Disable Microsoft enforcement**.

![Recover workspace access](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/11-recover-workspace-access_1cabzbs.png =600x331)

This turns off required Microsoft login but does not sign you in. Sign in with another method, fix the Microsoft issue, run **Test sign-in** again, and generate a new recovery code before re-enabling enforcement.

To disconnect Microsoft entirely, turn off **Require Microsoft login** first.

## Troubleshooting

**A setting is disabled.** Hover to see its requirements. Required login needs verified sign-in and a saved recovery code. Auto-provisioning needs verified sign-in. Only workspace admins can change these.

**Setup expired or belongs to another session.** Start **Connect organization** again from the browser where you're signed in to Caimera.

**Microsoft won't approve the organization.** Check the tenant ID and the admin account used. If your organization restricts app consent, ask your Entra admin to approve Caimera.

**"Account already uses this email."** Sign in with your original Caimera method, then complete the Microsoft sign-in from that session.

**DNS record not found.** Check the record is on the right domain and the value matches exactly. DNS changes can take time. If the request expired, generate a new record.

**A new user can't join.** Check their invitation or auto-provisioning eligibility, available seats, and their Entra app assignment.

Still stuck? Reach us via the chat bubble or at contact@caimera.ai with your workspace name and roughly when the problem happened.