Microsoft Entra ID

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

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.

SSO & SCIM require the Enterprise plan and an organization owner or admin. See the SSO overview for prerequisites and how the URLs are derived.

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.

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.

Open the Entra admin center

Go to 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.

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.

Prefer the classic Azure portal? Go to portal.azure.com → search Microsoft Entra ID → open it → left menu Enterprise applications. Both portals reach the same app.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

If you also set up SCIM below, these same assignments determine which users and groups are in provisioning scope. For SSO without SCIM this assignment step is still 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.

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.

Add admin credentials in Entra

In the current Entra provisioning workspace, open your Enterprise App → Provisioning → Manage → Connectivity. In the classic interface, use Provisioning → Automatic → Admin Credentials instead:

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.

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.

Do not continue until Test connection succeeds. The Tenant URL must be publicly reachable by Microsoft; a stopped local server or expired temporary tunnel leaves Entra configured but unable to sync.

Assign users and start provisioning

Under Manage → Provisioning → Mappings, confirm both Provision Microsoft Entra ID Users and Provision Microsoft Entra ID Groups show Yes.
Under Manage → Attribute mapping, the default user mappings are fine (userPrincipalName → userName, mail → emails[work], givenName/surname → name.*, accountEnabled → active).
Expand Settings and set Scope to 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.

If the Overview says Initial sync paused and Last cycle completed: Never, return to Manage → Provisioning, set Provisioning Status to On, and click Save.

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.

Sync Entra groups to LLM Gateway teams

The complete path is:

Entra security group → Enterprise App assignment → SCIM group + members → exact-name mapping → LLM Gateway team policy

Three Entra settings are involved, and they do different jobs:

Entra setting	Purpose	If it is missing
Security group membership	Defines who belongs to the group.	Entra has no membership change to send.
Enterprise App → Users and groups assignment	Places the group and its immediate members in scope when provisioning is set to Sync only assigned users and groups.	The group is skipped as not assigned.
Provisioning → Manage → Provisioning → Mappings group job enabled	Sends the group object, exact `displayName`, and membership changes to LLM Gateway.	Users may be provisioned, but LLM Gateway never sees their Entra group membership.

Assigning a group to the Enterprise App is not the same as provisioning the group object. Team mapping works only when the group is assigned and the group attribute mapping is enabled.

You do not need to add a groups claim to the SAML assertion. SAML handles sign-in; SCIM sends the group object and membership used for team mapping.

Microsoft documents Enterprise App group assignment and group object provisioning separately for the same reason.

Recommended group layout

Use one unmapped access group to keep users provisioned, plus separate groups for team policy:

Entra security group	Assigned to the Enterprise App	LLM Gateway mapping	Purpose
`Gateway Access`	Yes	None	Baseline SSO/SCIM access; keeps the user in scope while their team changes.
`Gateway Platform`	Yes	`Gateway Platform → Platform`	Applies the Platform team's policy.
`Gateway Data`	Yes	`Gateway Data → Data`	Applies the Data team's policy.

Make every user an immediate member of Gateway Access and an immediate member of the appropriate policy group. Do not nest the policy groups inside the access group: Entra application assignment and provisioning do not expand nested group membership.

Without the baseline group (or a direct user assignment), leaving a mapped policy group can make the user entirely out of scope. Entra then deprovisions the organization member instead of only removing their team, which also revokes that member's API keys.

Create the Entra security groups

In the Entra admin center, go to Entra ID → Groups → All groups → New group:

Group type: Security. Entra requires assigned groups to be security-enabled.
Group name: choose a stable name such as Gateway Platform. LLM Gateway matches this display name exactly, including case and spaces.
Membership type: Assigned is simplest. Dynamic membership also works, but its own evaluation delay is added before provisioning runs.
Add the users as direct members.

Group-based Enterprise App assignment requires Microsoft Entra ID P1 or P2.

Assign every relevant group to the Enterprise App

Open Entra ID → Enterprise apps → All applications → <your LLM Gateway app> → Users and groups → Add user/group. Select the baseline access group and every group you plan to map, keep the offered application role (commonly User or Default Access), then click Assign. That role does not select an LLM Gateway team; the exact-name mapping does.

Assigning only individual users is enough to provision those users, but it does not put an unassigned group object in scope. The group itself must appear on the Enterprise App's Users and groups page.

Enable group object provisioning

On the same Enterprise App, open Provisioning → Manage → Provisioning, expand Mappings, and confirm Provision Microsoft Entra ID Groups shows Yes. Then open Manage → Attribute mapping → Groups and confirm the three default group mappings remain:

displayName → displayName
members → members
objectId → externalId

In the classic interface, these controls are together under Provisioning → Mappings → Provision Microsoft Entra ID Groups. Keep Settings → Scope set to Sync only assigned users and groups, set Provisioning Status to On, and save.

Map the exact group name in LLM Gateway

First create the destination team under Organization → Teams. Then open Organization → SSO → Group team mapping:

Enter the Entra group's exact display name, for example Gateway Platform.
Select the LLM Gateway team, for example Platform.
Click Save mapping.

The mapping can be created before or after Entra pushes the group. If the group already exists in LLM Gateway, saving applies the team immediately to its current developer members.

Run and verify the first sync

For a quick test, use Enterprise App → Provisioning → Provision on demand, search for the group, select an affected member, then click Provision. Entra's on-demand group test handles up to five selected members at a time. For the normal background cycle, use Start provisioning and check Provisioning logs for the group and its users; Entra generally runs the synchronization process about every 40 minutes.

In LLM Gateway, open Organization → Members and confirm the developer shows the expected team. Provisioning only the user tests user creation; provision the group to test group-to-team mapping.

What changes after the first sync

Change in Entra	SCIM change sent to LLM Gateway	Result
Add an assigned group/member	Create or update the user and group membership.	The developer receives the mapped team.
Move a user between mapped groups	Remove one group membership and add the other.	The developer moves to the newly resolved team.
Remove the last mapped membership	Remove the group membership.	The SCIM-assigned team is cleared; the user remains provisioned through the baseline access group.
Rename a mapped group	Update the SCIM group's `displayName`.	The old exact-name mapping stops matching; update it on the LLM Gateway SSO page.
Unassign or delete the group	Deprovision the SCIM group.	Its members lose that mapped team; users remain only if another assignment keeps them in scope.

An explicit non-null team assignment made by an admin on the Members page is never overwritten. If an admin only clears a SCIM-assigned team, the next SCIM event restores the mapped team. If several mapped groups apply, the alphabetically first exact group name wins. Owners and admins cannot belong to teams, so a privileged group → role mapping takes precedence.

Team project access is an additional ceiling: a developer can use a project only when both their personal/default project grants and their team allow it.

If the user syncs but the team does not

Check the path in order:

On the Enterprise App's Users and groups page, confirm the group is assigned—not only its individual user.
Under Provisioning → Manage → Provisioning → Mappings, confirm Provision Microsoft Entra ID Groups is Yes.
Under Manage → Attribute mapping → Groups, confirm displayName, members, and objectId are still mapped.
Use Provision on demand with the group and member, then inspect the Provisioning logs for a group operation.
In LLM Gateway, confirm the Group team mapping is character-for-character identical to the Entra display name and the member's role is developer.

If the user appears in LLM Gateway but no group operation appears in Entra's logs, the problem is on the Entra assignment or group-provisioning side. If the group operation succeeds but the team stays empty, check the exact-name mapping and member role in LLM Gateway.

Group → role mapping (optional)

The same SCIM groups can drive organization roles. On the SSO page, add mappings such as Gateway Admins → admin. Each member gets the highest mapped role among their groups (default developer). Owners are never auto-demoted. Because owners and admins cannot belong to teams, a privileged role mapping clears any team assignment.

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.

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.

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.

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.

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.

Microsoft Entra ID

On this page