> ## Documentation Index
> Fetch the complete documentation index at: https://docs.antsfield.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure AD SAML SSO

> Configure SAML single sign-on between Microsoft Entra ID (Azure AD) and Retrac.

This guide walks workspace **owners** through connecting **Microsoft Entra ID** (formerly Azure AD) as a SAML identity provider for Retrac. SAML SSO is available on **Enterprise** plans.

<Note>
  Test in a staging Entra enterprise app before enforcing SSO on production users. Keep at least one break-glass owner account with a non-SSO recovery path.
</Note>

## Prerequisites

* Microsoft Entra ID admin access
* Retrac workspace owner role
* Enterprise plan with SAML enabled

## Set up Azure AD SAML

<Steps>
  <Step title="Open Retrac Security settings">
    In Retrac, go to **Settings → Security** and click to configure **SAML Single Sign-On**. Select **Microsoft Entra ID (Azure AD)** as your identity provider.
  </Step>

  <Step title="Create an enterprise app in Entra ID">
    In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity → Applications → Enterprise applications → New application**.

    Choose **Create your own application**, name it **Retrac**, and select **Integrate any other application you don't find in the gallery (Non-gallery)**.
  </Step>

  <Step title="Configure SAML">
    Open the Retrac enterprise app → **Single sign-on** → **SAML**.

    From the Retrac SAML setup modal, copy the **ACS URL** and **Entity ID**. Enter them in Entra:

    * **Identifier (Entity ID)** — Retrac Entity ID
    * **Reply URL (ACS URL)** — Retrac ACS URL
    * **Sign-on URL** — leave blank for IdP-initiated, or set per your flow
  </Step>

  <Step title="Copy the metadata URL">
    ## Step 4: Copy the metadata URL

    In the Entra SAML configuration, Microsoft provides **App Federation Metadata Url**.

    1. On the **SAML-based Sign-on** page, find **App Federation Metadata Url**.
    2. Copy the metadata URL.
    3. In Retrac **Settings → Security**, paste the metadata URL into the SAML configuration form.
    4. Save the configuration in Retrac.

    Retrac uses this metadata to trust Entra ID's signing certificate and SSO endpoint.
  </Step>

  <Step title="Configure claims">
    Under **Attributes & Claims**, ensure the token includes:

    | Claim                         | Retrac expects        |
    | ----------------------------- | --------------------- |
    | `emailaddress` or `user.mail` | Email address         |
    | `givenname`                   | First name (optional) |
    | `surname`                     | Last name (optional)  |

    Use **Unique User Identifier (Name ID)** mapped to the user's email or UPN, consistent with your Retrac email matching policy.
  </Step>

  <Step title="Assign users and test">
    Go to **Users and groups** and assign the Retrac app to users or groups.

    1. Sign out of Retrac.
    2. On the login page, click **Sign in with SAML**, or launch from the Microsoft My Apps portal.
    3. Confirm you land in the correct workspace.

    <Tip>
      Download the **Federation Metadata XML** from Entra if your security team prefers file-based exchange instead of a metadata URL.
    </Tip>
  </Step>
</Steps>

## Remove SAML

Owners can disconnect SAML from **Settings → Security**. Coordinate with your IT team before removing production SSO.

See [Security documentation](/dashboard/security/introduction) and [Azure AD SCIM](/help/article/azure-scim) for user provisioning.