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

# Set up SSO with Microsoft Entra ID

> Register Variable as an app in Microsoft Entra ID (Azure AD) and send us the credentials to switch on single sign-on

Microsoft renamed Azure Active Directory (Azure AD) to Microsoft Entra ID. The steps below use the current names; the older Azure AD portal labels map one to one.

You register Variable as an **app registration** in your tenant — think of it as issuing Variable a badge that lets it ask Microsoft "who is this person?". A tenant is your organization's own directory in Microsoft's cloud.

You need the **Application Administrator** or **Cloud Application Administrator** role in Entra ID, or **Global Administrator**. Read the [single sign-on overview](/docs/sso/overview) first if you have not verified your domain in Variable.

## Register the app

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
2. Go to **Identity** → **Applications** → **App registrations** and select **New registration**.
3. Set **Name** to `Variable`, or anything your team will recognize.
4. Under **Supported account types**, choose **Accounts in this organizational directory only (Single tenant)**. This pins sign-in to your directory, so accounts from other Microsoft tenants and personal Microsoft accounts are rejected.
5. Under **Redirect URI**, choose the **Web** platform and enter:

   ```text theme={"system"}
   https://app.variable.global/api/auth/microsoft/callback
   ```

   It must match exactly, including `https` and no trailing slash.
6. Select **Register**.

On the app's **Overview** page, copy two values:

* **Application (client) ID**
* **Directory (tenant) ID** — the ID itself, in the form `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, not your domain name

## Check the permissions

Variable asks Microsoft for your users' name and email address, and nothing else.

1. Open **API permissions**.
2. Confirm **Microsoft Graph** → **User.Read** (Delegated) is listed. It is added by default.
3. Select **Grant admin consent for** your organization. Without it, each person is asked to approve access on their first sign-in, and if your tenant blocks user consent they cannot sign in at all.

Variable matches each person to their Variable user by email address, so invite people with the address they use to sign in to Microsoft.

## Create a client secret

1. Open **Certificates & secrets** → **Client secrets** → **New client secret**.
2. Give it a description such as `Variable SSO` and choose an expiry. Microsoft allows at most 24 months.
3. Select **Add**, then copy the secret **Value** straight away. Microsoft shows it once; the **Secret ID** column is not the secret.

Write the expiry date in your calendar. When the secret expires, SSO stops working for everyone until you send us a new one.

## Send us the credentials

Send us the following through an agreed-upon secure channel:

* Provider: Microsoft
* Application (client) ID
* Directory (tenant) ID
* Client secret **Value**
* The email domains to cover, each verified in Variable
* A contact who can test the sign-in

We confirm once it is switched on.

## Test it

1. Open a private browser window and go to `https://app.variable.global`.
2. Enter your work email and continue. You are sent to Microsoft.
3. Sign in. You land back in Variable.

## Troubleshooting

| Microsoft or Variable says | Cause | Fix |
| :- | :- | :- |
| `AADSTS50011: The redirect URI ... does not match` | The redirect URI in the app registration differs from the one above | Correct it under **Authentication** → **Web** |
| `AADSTS65001: The user or administrator has not consented` | Admin consent was not granted | Grant it under **API permissions** |
| `AADSTS50020` or `AADSTS700016` | The person is signing in from another tenant, or the client ID is wrong | Confirm the tenant ID and client ID you sent |
| Back on the sign-in page with no message | The client secret is wrong or expired, or the **Secret ID** was sent instead of the **Value**. Microsoft reports this to Variable, not to the person signing in | Ask us whether we see a secret error, then create a new secret and send the **Value** |
| Back on the sign-in page with no message | The tenant ID or client ID sent to us is wrong, the account signed in to Microsoft is not the address typed, or the sign-in did not start on Variable's sign-in page in the same browser | Recopy both IDs from **Overview**, and start from Variable's sign-in page with the account whose address you typed |
| **No access** screen | None of the account's addresses is on a domain verified in Variable and linked to the connection | Check the domain still shows **Verified** under **Settings** → **Company**, then contact us |
| A setup screen asking for a company name | Signed in, but not invited to Variable | See [invite people first](/docs/sso/overview#invite-people-first) |

## Restrict who can sign in (optional)

By default anyone in your tenant can start a sign-in. To limit it to specific people, open the app under **Enterprise applications**, then **Properties**, set **Assignment required?** to **Yes**, and add users or groups under **Users and groups**. People who are not assigned are stopped by Microsoft before they reach Variable.


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