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

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.

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, 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.

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

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.

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.

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.

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