> ## 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 AD FS

> Configure SAML 2.0 single sign-on between TrueFoundry and an on-premise Microsoft Active Directory Federation Services (AD FS) deployment.

This guide walks you through setting up SAML 2.0 single sign-on between TrueFoundry and **Microsoft Active Directory Federation Services (AD FS)**. Once finished, users in your AD forest can sign in to TrueFoundry through a **Login with AD FS** button.

## Prerequisites

* A TrueFoundry tenant with **Admin** access to **Settings → Security & Access → SSO**.
* An AD FS server (Windows Server 2016 or newer) with administrative access to **AD FS Management** and **Windows PowerShell** as an administrator.
* Network reachability from end-user browsers to both the AD FS sign-in endpoint (typically `https://<adfs-server>/adfs/ls/`) and your TrueFoundry control plane.

<Tip>
  You will switch between **AD FS Management** on the Windows server and **TrueFoundry → Settings → Security & Access → SSO** in your browser. Keep both open in adjacent windows to copy values across.
</Tip>

## Configuration overview

<Steps>
  <Step title="Create the SSO configuration in TrueFoundry">
    Save a SAML SSO configuration in TrueFoundry to surface the **Assertion Consumer Service URL**, **Relying Party Identifier**, and **Relay URL**.
  </Step>

  <Step title="Create a Relying Party Trust in AD FS">
    Add a claims-aware Relying Party Trust pointing at TrueFoundry.
  </Step>

  <Step title="Configure claim issuance rules">
    Map LDAP attributes to outgoing SAML claims and add a NameID transform.
  </Step>

  <Step title="Sign both the SAML response and assertion">
    Run a PowerShell command so AD FS signs both the SAML message and the assertion.
  </Step>

  <Step title="Paste AD FS values back into TrueFoundry">
    Copy the AD FS SSO endpoint and the token-signing certificate into TrueFoundry, then test.
  </Step>
</Steps>

## Step 1 — Create the SSO configuration in TrueFoundry

<Steps>
  <Step title="Open SSO settings">
    Go to **Settings → Security & Access → SSO**.

    Click the **+** icon labeled **Add New SSO Config**.

    <Frame caption="SSO page in TrueFoundry — click the + icon to add a new SSO configuration">
      <img src="https://mintcdn.com/truefoundry/OlEFjoHwZJ0edSjd/images/sso/entra/saml-truefoundry-add-sso-config.png?fit=max&auto=format&n=OlEFjoHwZJ0edSjd&q=85&s=f768205b84d9f33ce04a8b8576ab0070" alt="TrueFoundry SSO settings page with the Add New SSO Config plus button highlighted" width="1024" height="263" data-path="images/sso/entra/saml-truefoundry-add-sso-config.png" />
    </Frame>
  </Step>

  <Step title="Fill in the basic fields">
    * **Enabled**: turn this on.
    * **Name**: a lowercase alphanumeric label — for example, `adfssaml`.
    * **SSO Provider**: choose **Custom**.
    * **Authentication Configuration**: select **SAML v2**.

    Leave **Identity Provider Endpoint** and **X.509 Certificate** blank for now — you'll fill them in once AD FS surfaces those values.
  </Step>

  <Step title="Save to reveal the Single sign-on URL, Audience URI (SP Entity ID), and Relay URL">
    Click **Save**. TrueFoundry displays the values you need for AD FS on the SSO configuration card:

    | AD FS field                              | Value from TrueFoundry          |
    | ---------------------------------------- | ------------------------------- |
    | **Assertion Consumer Service (ACS) URL** | **Single Sign On URL**          |
    | **Relying Party Trust Identifier**       | **Audience URI (SP Entity ID)** |
    | **Relay State** *(if used)*              | **Relay URL**                   |

    <Frame caption="TrueFoundry SSO configuration card showing the SAML values to copy into AD FS">
      <img src="https://mintcdn.com/truefoundry/OlEFjoHwZJ0edSjd/images/sso/entra/saml-truefoundry-sp-metadata.png?fit=max&auto=format&n=OlEFjoHwZJ0edSjd&q=85&s=e061fae840c0fa4e8af3c4efe9961a2b" alt="TrueFoundry SSO configuration card displaying Audience URI, Single Sign On URL, Metadata URL, and Relay URL for SAML setup" width="1024" height="391" data-path="images/sso/entra/saml-truefoundry-sp-metadata.png" />
    </Frame>
  </Step>
</Steps>

## Step 2 — Create a Relying Party Trust in AD FS

<Steps>
  <Step title="Open AD FS Management">
    On your AD FS server, open **Server Manager → Tools → AD FS Management**.

    In the left navigation, select **Relying Party Trusts**, then under **Actions**, click **Add Relying Party Trust…**.
  </Step>

  <Step title="Choose Claims aware">
    On the **Welcome** page of the wizard, select **Claims aware** and click **Start**.
  </Step>

  <Step title="Select the data source">
    On **Select Data Source**, pick one of the following based on how your TrueFoundry control plane is reachable:

    <Tabs>
      <Tab title="Public / reachable URL">
        Choose **Import data about the relying party published online or on a local network** and enter the metadata URL of your TrueFoundry control plane. This is the recommended option when AD FS can reach the control plane.
      </Tab>

      <Tab title="Internal / manual entry">
        Choose **Enter data about the relying party manually** and supply the values manually on the following screens:

        * **Display name** — any descriptive label (used in PowerShell later).
        * **Configure URL** — enable **SAML 2.0** and paste the TrueFoundry **Single Sign On URL** as the Assertion Consumer Service URL.
        * **Configure Identifiers** — add the TrueFoundry **Audience URI (SP Entity ID)** as the Relying Party Trust Identifier.
      </Tab>
    </Tabs>

    Click **Next**.
  </Step>

  <Step title="Specify a display name">
    On **Specify Display Name**, enter a **Display name** such as `TrueFoundry`. Optionally add notes, then click **Next**.

    <Note>
      Remember this exact display name — you will pass it to PowerShell in [Step 4](#step-4-sign-both-the-saml-response-and-assertion).
    </Note>
  </Step>

  <Step title="Choose an access control policy">
    On **Choose Access Control Policy**, select **Permit everyone** for a typical deployment, or pick a more restrictive policy (such as **Permit specific group**) if you want only specific AD groups to use TrueFoundry. Click **Next**.
  </Step>

  <Step title="Finalize the trust">
    Review the configuration on **Ready to Add Trust** and click **Next**. On **Finish**, leave **Configure claims issuance policy for this application** checked and click **Close**. The **Edit Claim Issuance Policy** dialog opens automatically.
  </Step>
</Steps>

## Step 3 — Configure claim issuance rules

In the **Edit Claim Issuance Policy** dialog, add two rules: one to send LDAP attributes as claims, and one to transform the email claim into a properly formatted NameID.

<Steps>
  <Step title="Add a 'Send LDAP Attributes as Claims' rule">
    Click **Add Rule…**, choose **Send LDAP Attributes as Claims**, and click **Next**.

    Enter a **Claim rule name** such as `LDAP attributes`, select **Active Directory** as the **Attribute store**, and add the following mappings:

    | LDAP Attribute        | Outgoing Claim Type |
    | --------------------- | ------------------- |
    | `E-Mail-Addresses`    | `E-Mail Address`    |
    | `E-Mail-Addresses`    | `email`             |
    | `Object-Guid`         | `sub`               |
    | `Given-Name`          | `Given Name`        |
    | `Surname`             | `Surname`           |
    | `User-Principal-Name` | `Name ID`           |

    Click **Finish**.
  </Step>

  <Step title="Add a NameID transform rule">
    Click **Add Rule…** again, choose **Transform an Incoming Claim**, and click **Next**.

    Configure the rule as follows:

    * **Claim rule name**: `Email to NameID`
    * **Incoming claim type**: **E-Mail Address**
    * **Outgoing claim type**: **Name ID**
    * **Outgoing name ID format**: **Email**
    * Select **Pass through all claim values**.

    Click **Finish**.

    <Tip>
      If you prefer to write the rule in the Claim Rule Language directly (for example to script the deployment), the equivalent rule is:

      ```text theme={"dark"}
      c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
       => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
                Issuer = c.Issuer,
                OriginalIssuer = c.OriginalIssuer,
                Value = c.Value,
                ValueType = c.ValueType,
                Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"]
                  = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
      ```
    </Tip>

    Click **OK** to close the **Edit Claim Issuance Policy** dialog.
  </Step>
</Steps>

<Warning>
  Without the NameID transform rule, AD FS sends `NameID` with `Format="Unspecified"`. TrueFoundry will reject the assertion with an **InvalidNameIDPolicy** error.
</Warning>

## Step 4 — Sign both the SAML response and assertion

By default AD FS only signs the SAML assertion, but TrueFoundry requires both the response message and the assertion to be signed.

Open **Windows PowerShell** as an administrator on the AD FS server and run:

```powershell theme={"dark"}
Set-ADFSRelyingPartyTrust -TargetName "<display-name>" -SamlResponseSignature "MessageAndAssertion"
```

Replace `<display-name>` with the exact **Display name** you set in Step 2.

## Step 5 — Paste AD FS values back into TrueFoundry

<Steps>
  <Step title="Locate the AD FS SAML sign-in URL">
    AD FS exposes its SAML endpoint at:

    ```
    https://<adfs-server>/adfs/ls/
    ```

    You can confirm this value by browsing to **AD FS Management → Service → Endpoints** and locating the row of type `SAML 2.0/WS-Federation` with URL path `/adfs/ls/`.
  </Step>

  <Step title="Export the token-signing certificate">
    In **AD FS Management**, expand **Service → Certificates**. Right-click the **Token-signing** certificate and choose **View Certificate…**.

    1. Open the **Details** tab and click **Copy to File…**.
    2. Choose **Base-64 encoded X.509 (.CER)** and save the certificate to disk.
    3. Open the saved `.cer` file in a text editor and copy the entire contents — including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.
  </Step>

  <Step title="Paste the values into TrueFoundry">
    Return to **Settings → Security & Access → SSO** in TrueFoundry and edit the SSO configuration you created in Step 1. Set:

    * **Identity Provider Endpoint** → `https://<adfs-server>/adfs/ls/`
    * **X.509 Certificate** → the PEM-encoded certificate text you just copied.

    Click **Save**.
  </Step>

  <Step title="(Optional) Customise the login button">
    Expand **Show advanced fields** in the SSO form to set:

    * **Button Text** — for example, `Login with AD FS`.
    * **Button Image URL** — a public URL to your AD FS / corporate logo.

    Leave **Email Claim** and **Unique ID Claim** at their defaults; the claim rules you added in Step 3 already emit the standard claim types TrueFoundry expects.
  </Step>
</Steps>

## Step 6 — Test single sign-on

1. Open a private/incognito window and go to your TrueFoundry login page.
2. Click **Login with AD FS** (or the button label you chose).
3. Authenticate with an Active Directory user that is permitted by your access control policy.

If sign-in succeeds you will land in the TrueFoundry dashboard. The user is created automatically when [JIT provisioning](/docs/platform/user-management#user-provisioning) is enabled; otherwise they must already exist in TrueFoundry or be invited first.

## Troubleshooting

<AccordionGroup>
  <Accordion title="'InvalidNameIDPolicy' or 'NameID policy not satisfied' on sign-in">
    AD FS is sending `NameID` with `Format="Unspecified"`. Re-open **Edit Claim Issuance Policy** on the Relying Party Trust and confirm the **Email to NameID** transform rule from [Step 3](#step-3-configure-claim-issuance-rules) is present and ordered after the LDAP attribute rule.
  </Accordion>

  <Accordion title="'Invalid Signature' or 'SAML response was not signed'">
    AD FS only signed the assertion, not the response. Re-run the PowerShell command from [Step 4](#step-4-sign-both-the-saml-response-and-assertion):

    ```powershell theme={"dark"}
    Set-ADFSRelyingPartyTrust -TargetName "<display-name>" -SamlResponseSignature "MessageAndAssertion"
    ```
  </Accordion>

  <Accordion title="'Could not validate SAML response' / certificate mismatch">
    The token-signing certificate copied into TrueFoundry no longer matches the active certificate on AD FS — usually after an AD FS certificate rollover. Re-export the current **Token-signing** certificate from **AD FS Management → Service → Certificates** and paste the full PEM (including the BEGIN/END lines) back into TrueFoundry.
  </Accordion>

  <Accordion title="Users sign in but email or unique ID is empty">
    Confirm the **Send LDAP Attributes as Claims** rule emits `email` and `sub` as described in **Step 3**, and that the user has populated `mail` / `userPrincipalName` and `objectGUID` values in Active Directory. If your AD schema uses different attribute names, expand **Show advanced fields** in TrueFoundry and set **Email Claim** and **Unique ID Claim** to match the outgoing claim types you configured.
  </Accordion>

  <Accordion title="AD FS shows 'access denied' before the user reaches TrueFoundry">
    Your **Access Control Policy** on the Relying Party Trust is rejecting the user. Switch the policy to **Permit everyone**, or add the user's AD group to the existing policy under **Edit Access Control Policy…**.
  </Accordion>
</AccordionGroup>