---
title: Microsoft Entra ID
description: Set up SAML single sign-on and SCIM provisioning for your organization with Microsoft Entra ID (formerly Azure AD).
icon: Microsoft
---

import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";

# Microsoft Entra ID

This guide walks an organization admin through connecting **Microsoft Entra ID** (formerly Azure Active Directory) to LLM Gateway for SAML single sign-on and SCIM provisioning.

<Callout type="info">
	SSO & SCIM require the **Enterprise** plan and an organization **owner** or
	**admin**. See the [SSO overview](/features/sso) for prerequisites and how the
	URLs are derived.
</Callout>

## Finding "Enterprise applications" in Entra

An **Enterprise application** is a registered instance of an app that your tenant trusts for sign-in. You'll create one to represent LLM Gateway; its **Single sign-on (SAML)** page is where you exchange URLs and download the certificate.

<Callout type="warn">
	This is **not** the same as **App registrations** (that section is for apps
	you are developing). Use **Enterprise applications**. They are siblings under
	**Applications** and easy to confuse.
</Callout>

<Steps>
<Step>
### Open the Entra admin center

Go to [entra.microsoft.com](https://entra.microsoft.com) and sign in with an account that has at least the **Cloud Application Administrator** or **Application Administrator** role (Global Administrator also works). A regular member account won't see these options.

</Step>

<Step>
### Navigate to Enterprise applications

In the left-hand navigation, click **Entra ID** (older tenants label this group **Identity**), then expand **Applications** and click **Enterprise applications** (older label: **Enterprise apps**).

You're now on the **All applications** list.

<Callout type="info">
	Prefer the classic Azure portal? Go to
	[portal.azure.com](https://portal.azure.com) → search **Microsoft Entra ID** →
	open it → left menu **Enterprise applications**. Both portals reach the same
	app.
</Callout>
</Step>

<Step>
### Create the application

Click **+ New application** → **+ Create your own application**. Name it (e.g. `LLM Gateway`), choose **"Integrate any other application you don't find in the gallery (Non-gallery)"**, then **Create**. Wait a few seconds for it to provision.

<Callout type="warn">
	Don't search the Entra **gallery** for "LLM Gateway" — there is no gallery
	listing, so always use **Create your own application → Non-gallery**. You
	configure SAML and SCIM manually with the URLs from your **SSO** page; the
	steps below cover everything.
</Callout>

</Step>

<Step>
### Open the SAML SSO page

On the app's **Overview**, use the app's own left menu → **Single sign-on**. On the **Select a single sign-on method** screen, choose **SAML**.

This opens the 5-section **Set up Single Sign-On with SAML** page referenced throughout the rest of this guide.

</Step>
</Steps>

## Configure SAML SSO

Because Entra needs LLM Gateway's URLs and LLM Gateway needs Entra's Login URL and certificate, the two systems exchange values. Follow this order.

<Steps>
<Step>
### Choose a connection slug

In LLM Gateway (**Organization → SSO → Add a connection**), set **Identity provider** to **Microsoft Entra ID**, then pick a **connection slug** (lowercase letters, numbers, hyphens; `^[a-z0-9-]+$`, up to 64 chars). We recommend the format `<your-org-slug>-<provider>`, e.g. `acme-entra` — the form pre-fills this from your organization name and the selected provider, so you can accept it or edit it. It must be unique across all LLM Gateway organizations, and each organization has exactly one SSO connection. Keep it stable: your SP URLs are built from it.

As soon as the slug is set, the form shows your two SP URLs (with the hosted default `https://internal.llmgateway.io`) — copy them from there:

- **Identifier (Entity ID):** `https://internal.llmgateway.io/auth/sso/saml2/sp/metadata?providerId=acme-entra`
- **Reply URL (ACS):** `https://internal.llmgateway.io/auth/sso/saml2/sp/acs/acme-entra`

You'll paste these into Entra next — no need to create the connection yet.

</Step>

<Step>
### Set Basic SAML Configuration in Entra

On the Entra **Single sign-on (SAML)** page, **Section 1 – Basic SAML Configuration** → **Edit**:

- Under **Identifier (Entity ID)**, click **Add identifier** and paste your metadata URL from the previous step.
- Under **Reply URL (Assertion Consumer Service URL)**, click **Add reply URL** and paste your ACS URL.
- Leave **Sign on URL**, **Relay State**, and **Logout Url** blank.

Click **Save** (the button enables once both required fields are filled), then close the panel.

<Callout type="warn">
	The Reply URL row has a small numeric **Index** column next to the URL field.
	Paste the ACS URL into the **Enter a reply URL** box only — if it lands in the
	Index box you'll see _"The value must be a valid number."_ Leave Index blank.
</Callout>

</Step>

<Step>
### Confirm the claims

**Section 2 – Attributes & Claims**: the Entra defaults are fine. In **Microsoft Entra ID** mode, LLM Gateway reads email/name from the standard claim URIs Entra sends by default (`.../emailaddress`, `.../givenname`, `.../surname`, `.../name`), so you don't need to force the Name ID to be the email — just make sure users have a real `mail`/UPN.

</Step>

<Step>
### Grab the certificate and Login URL

- **Section 3 – SAML Certificates** → next to **Certificate (Base64)**, click **Download**. The `.cer` file's contents are a PEM block (`-----BEGIN CERTIFICATE----- … -----END CERTIFICATE-----`). Use **Certificate (Base64)**, not Raw or the Federation Metadata XML.
- **Section 4 – Set up \<app name\>** → copy the **Login URL** (looks like `https://login.microsoftonline.com/<tenant-id>/saml2`).

Keep both values handy for the next step.

<Callout type="info">
	The certificate **Download** links stay greyed out until Section 1's required
	fields are filled and saved — so complete the previous step first. The
	auto-generated signing certificate is valid for three years; its thumbprint
	and expiry are shown in Section 3.
</Callout>

</Step>

<Step>
### Create the connection in LLM Gateway

Back on the **SSO → Add a connection** form:

- **Identity provider:** **Microsoft Entra ID** — important, this switches on the Entra claim mapping and relaxes the NameID format
- **Connection slug:** `acme-entra` (must match the slug whose URLs you pasted into Entra)
- **Email domains:** your corporate domain(s), e.g. `acme.com` (comma-separate for several)
- **Identity Provider Single Sign-On URL:** the Entra **Login URL**
- **X.509 signing certificate:** paste the PEM block

Save. The connection card then shows the exact SP metadata + ACS URLs — confirm they match what you entered in Entra **Section 1**. You can edit the email domain list on the connection card later without re-creating the connection.

<Callout type="warn">
	The domain list must include **every domain Entra may send as a user's
	email**. LLM Gateway signs a user in from the `emailaddress` claim, which
	Entra fills from the **`mail`** attribute — and that domain can differ from
	the sign-in (userPrincipalName) domain, e.g. UPN `jane@acme.local` with mail
	`jane@acme.com`. If they differ, list **both** (`acme.local, acme.com`);
	otherwise sign-in bounces back to the login page with an `account_not_linked`
	error even though Entra authenticated the user.
</Callout>

</Step>
</Steps>

## Assign users to the app

Configuring SAML isn't enough on its own — Entra only issues a SAML assertion for users who are **assigned** to the application. On the Enterprise App → **Users and groups → + Add user/group**, add the people (or groups) who should be able to sign in, then **Assign**.

<Callout type="warn">
	If you skip this, sign-in fails at Entra with _"…is not assigned to a role for
	the application"_ (error `AADSTS50105`) — even though the SAML config is
	correct. Assign at least your own account before testing.
</Callout>

If you also set up SCIM below, assigning users there covers this same requirement; but for SSO **without** SCIM this assignment step is mandatory.

## Configure SCIM provisioning

SSO only signs people in. SCIM is what actually adds members to the organization. Set it up on the **same** Enterprise App.

<Steps>
<Step>
### Generate a SCIM token

In LLM Gateway, on **Organization → SSO → Directory sync (SCIM)**, click **Generate SCIM token** and copy it (shown once). The SCIM base URL is shown in the same card — it's `https://internal.llmgateway.io/scim/v2` on the hosted default.

</Step>

<Step>
### Add admin credentials in Entra

In Entra, on your Enterprise App → **Provisioning → Automatic → Admin Credentials**:

- **Authentication method:** choose the token option — labelled **"Long-lived bearer token"** (or **"Secret token"**). **Do not** pick "OAuth 2.0 code grant flow": LLM Gateway's SCIM endpoint authenticates a plain static bearer token (`Authorization: Bearer <token>`), not an OAuth code exchange. The presence of a **Tenant URL + Secret token** pair on the form confirms you're on the right method.
- **Tenant URL:** the SCIM base URL, e.g. `https://internal.llmgateway.io/scim/v2`
- **Secret Token:** the token from the previous step
- Click **Test Connection** (Entra calls `/ServiceProviderConfig` with the bearer token), then **Save**.

A green check confirms the credentials are valid.

<Callout type="info">
	Entra rolled out a redesigned provisioning UX that adds the **"Select
	authentication method"** dropdown shown above. The classic UX has no dropdown
	and just shows Tenant URL + Secret token (which is the bearer method). Either
	is fine — pick the bearer/secret-token option and the steps are identical.
</Callout>

</Step>

<Step>
### Assign users and start provisioning

- **Mappings:** the Entra SCIM defaults are fine (`userPrincipalName → userName`, `mail → emails[work]`, `givenName/surname → name.*`, `accountEnabled → active`, group provisioning on).
- **Settings → Scope:** "Sync only assigned users and groups".
- Under **Users and groups**, assign the people/groups who should get access.
- Set **Provisioning Status = On** and Save. Use **Provision on demand** to test a single user instantly.

Entra then begins syncing assigned users on its provisioning cycle.

</Step>
</Steps>

Assigned users are created in LLM Gateway and added to the organization (default role **developer**). Deactivating or unassigning a user in Entra removes their membership.

## Group → role mapping (optional)

On the **SSO** page, add mappings such as `Acme Admins → admin`. When Entra pushes group membership over SCIM, each member gets the **highest** mapped role among their groups (default `developer`). Owners are never auto-demoted, so you can't accidentally lock yourself out of the owner role.

## Default project access (optional)

Provisioned members join as **developers**, who only see the projects they're granted (owners/admins always see every project). Use the **Default project access** card on the **SSO** page to choose which projects newly provisioned SSO/SCIM developers get by default. If you leave it unconfigured, new members get your organization's first (default) project so they can see something out of the box; select an empty set to instead grant nothing and manage project access manually per member.

<Callout type="info">
	Default project access applies only to members provisioned **after** you set
	it — it doesn't retroactively change existing members' project grants. Adjust
	an existing member's projects from the **Team** page.
</Callout>

## Test the login

Log out → login page → **Sign in with SSO** → enter a work email (`someone@acme.com`). LLM Gateway resolves the connection by email domain, redirects to Entra, and on return the (SCIM-provisioned) user is signed in and lands in the enterprise organization.

## Enforce SSO (optional, do this last)

Flip **Require SSO** on the connection to require SSO for that email domain — password, social, and passkey sign-in are then rejected for it.

<Callout type="warn">
	Only enable **Require SSO** after the test above passes, and remember it also
	applies to the admin setting it up if their email is on that domain — verify
	your own SSO login works first.
</Callout>

## Troubleshooting: login bounces back to the login page

If the Entra sign-in itself succeeds but the user lands back on the LLM Gateway login page (with a 401 in the browser console), the SAML response was received but LLM Gateway refused to attach it to the provisioned user — almost always an `account_not_linked` domain mismatch:

- **The asserted email's domain isn't in the connection's Email domains list.** Entra sends the user's `mail` attribute as the email; if its domain differs from the one you registered (e.g. you registered the UPN domain), edit the connection's **Email domains** on the SSO page to include both.
- **Wrong Identity provider type.** If the connection was created as **Other (SAML 2.0)** instead of **Microsoft Entra ID**, the Entra claim mapping isn't applied and the email falls back to the NameID (usually the UPN), which may again be off-list — and creates duplicate users instead of matching the SCIM-provisioned ones.

## Troubleshooting: can't find "Enterprise applications"

- **Insufficient role** — you need Application Administrator, Cloud Application Administrator, or Global Administrator. Ask whoever administers your Microsoft 365 / Entra tenant.
- **Wrong menu** — you're in **App registrations** (for developers) instead of **Enterprise applications**.
- **Wrong tenant** — if you belong to multiple tenants, use **Settings (gear) → Directories + subscriptions** (top-right) to switch to the tenant you administer.
