> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SAML with Microsoft Entra ID
> Configure SAML 2.0 single sign-on between TrueFoundry and Microsoft Entra ID (formerly Azure AD).
This guide walks you through setting up SAML 2.0 single sign-on between TrueFoundry and Microsoft Entra ID (formerly Azure Active Directory). Once finished, members of your Entra tenant can sign in to TrueFoundry through a **Login with Azure AD** button.
## Prerequisites
* A TrueFoundry tenant with **Admin** access to **Settings → Security & Access → SSO**.
* A Microsoft Entra ID tenant with permission to create **Enterprise Applications** (Cloud Application Administrator or higher).
You'll bounce between the **Entra admin center** and the **TrueFoundry SSO settings**. Keep both open in adjacent tabs to copy-paste values quickly.
## Configuration overview
Save a SAML SSO configuration in TrueFoundry to surface the **Reply URL**, **Identifier (Entity ID)**, and **Relay URL**.
Register a non-gallery Enterprise Application that Truefoundry will federate with.
Paste TrueFoundry's values into Entra, then paste Entra's IdP values back into TrueFoundry.
Assign users or groups to the Entra application and sign in to verify.
## Step 1 — Create the SSO configuration in TrueFoundry
Go to **Settings → Security & Access → SSO**.
Click the **+** icon labeled **Add New SSO Config**.
* **Enabled**: turn this on.
* **Name**: a lowercase alphanumeric label — for example, `entraidsaml`.
* **SSO Provider**: choose **Azure AD**.
* **Authentication Configuration**: select **SAML v2**.
Leave **Identity Provider Endpoint** and **X.509 Certificate** blank for now — you'll fill them in once Entra surfaces those values.
Click **Save**. TrueFoundry displays the values you need for Entra on the SSO configuration card:
* **Identifier (Entity ID)** in Entra — **Audience URI (SP Entity ID)** in TrueFoundry.
* **Reply URL (Assertion Consumer Service URL)** in Entra — **Single Sign On URL** in TrueFoundry.
* **Relay State** in Entra — **Relay URL** in TrueFoundry.
## Step 2 — Create an Enterprise Application in Entra
Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/) as an administrator.
In the left navigation, expand **Identity → Applications** and select **Enterprise applications**.
Click **New application** at the top of the **Enterprise applications** page, then select **Create your own application**.
1. Give the application a name — for example, `TrueFoundry`.
2. Choose **Integrate any other application you don't find in the gallery (Non-gallery)**.
3. Click **Create**. It may take a few seconds for Entra to finish provisioning the application.
From your application's **Overview** page, click **Set single sign on**, then select the **SAML** tile.
## Step 3 — Enter TrueFoundry's details into Entra
On the **Set up Single Sign-On with SAML** page for the application you created in Step 2, edit the **Basic SAML Configuration** card using the **Reply URL**, **Identifier (Entity ID)**, and **Relay State** from Step 1.
Click the pencil icon on **Basic SAML Configuration** and enter the values from TrueFoundry:
| Entra field | Value from TrueFoundry |
| ---------------------------------------------- | ------------------------------- |
| **Identifier (Entity ID)** | **Audience URI (SP Entity ID)** |
| **Reply URL (Assertion Consumer Service URL)** | **Single Sign On URL** |
| **Relay State** | **Relay URL** |
Click **Save** at the top of the panel and close it.
From the **Attributes & Claims** card, click **Add new claim** and create two additional claims. Leave all other settings at their defaults — including the required **Unique User Identifier (Name ID)** claim and Entra's built-in schema claims.
### Add the `email` claim
1. Click **Add new claim**.
2. Set **Name** to `email`.
3. Leave **Namespace** blank and **Name format** as **Omitted (default)**.
4. Under **Source**, select **Attribute** and set **Source attribute** to `user.userprincipalname`.
5. Click **Save**.
### Add the `sub` claim
1. Click **Add new claim** again.
2. Set **Name** to `sub`.
3. Leave **Namespace** blank and **Name format** as **Omitted (default)**.
4. Under **Source**, select **Attribute** and set **Source attribute** to `user.objectid`.
5. Click **Save**.
When finished, your **Attributes & Claims** page should include `email` and `sub` alongside Entra's default claims:
| Claim name | Source attribute |
| ------------------------------------ | ------------------------ |
| **Unique User Identifier (Name ID)** | `user.userprincipalname` |
| `email` | `user.userprincipalname` |
| `sub` | `user.objectid` |
## Step 4 — Copy Entra's details back to TrueFoundry
Scroll down on Entra's **Set up Single Sign-On with SAML** page to the **SAML Certificates** and **Set up ``** cards.
Under **SAML Certificates**, click **Download** next to **Certificate (Base64)**.
Open the downloaded `.cer` file in a text editor and copy the entire contents — including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.
From the **Set up ``** card, copy the **Login URL**.
Return to **Settings → Security & Access → SSO** in TrueFoundry and edit the SSO configuration you created in Step 1. Set:
* **Identity Provider Endpoint** → the **Login URL** from Entra.
* **X.509 Certificate** → the certificate text you copied from the `.cer` file.
Click **Save**.
## Step 5 — Assign users in Entra
Entra only lets users sign in to applications they've been explicitly assigned to.
Inside your Entra application, click **Users and groups** in the left sidebar, then **Add user/group**.
Pick the individual users or security groups that should have access to TrueFoundry and click **Assign**.
Users who are not assigned to the Entra application will see a "no access" error when they click **Login Azure AD** in TrueFoundry.
## Step 6 — Test single sign-on
1. Open a private/incognito window and go to your TrueFoundry login page.
2. Click **Login with Azure AD** (or whichever button label you chose under **Show advanced fields → Button Text**).
3. Authenticate with an Entra user that you assigned to the application.
If the sign-in succeeds you'll land in the TrueFoundry dashboard. The user is created automatically if [JIT provisioning](/docs/platform/user-management#user-provisioning) is on, otherwise they must already exist in TrueFoundry or be invited.
## Optional next steps
* **Automate user lifecycle with SCIM** — see [SCIM with Microsoft Entra ID](/docs/platform/sso/entra/scim) to push users and groups from Entra into TrueFoundry automatically.
* **Use OIDC instead of SAML** — see [OIDC with Microsoft Entra ID](/docs/platform/sso/entra/oidc) for the equivalent OpenID Connect flow.
## Troubleshooting
Check the provisioning mode under **Settings → Security & Access → Provisioning**:
* **Invite-only** — the user must be invited from **Access → Users** first.
* **JIT** — the user is created on first login automatically.
* **SCIM** — the user must be synced from your IdP first. See [SCIM with Microsoft Entra ID](/docs/platform/sso/entra/scim).
The Entra user isn't assigned to your application. Go back to **Step 5** and assign them under **Users and groups**.
The certificate copied into TrueFoundry doesn't match Entra's active signing certificate. Re-download **Certificate (Base64)** from Entra and paste the full PEM (including the BEGIN/END lines) into TrueFoundry.
Confirm you added the `email` and `sub` claims under **Attributes & Claims** as described in **Step 3**. If those claims are missing or mapped incorrectly, TrueFoundry cannot read the user's email or unique ID from the SAML response.