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

# Single Sign-On with Azure AD

> Configure Azure AD (Microsoft Entra ID) as a SAML identity provider for the Gr4vy dashboard.

The following is a generic guide for setting up SSO through Azure AD (Microsoft Entra ID) as a SAML
app. The exact setup may differ depending on your version of Azure AD and your desired setup.

## SAML app setup

Various configurations for Azure AD are supported. The following is an example of an Azure setup.

<Steps>
  <Step title="Create the enterprise app">
    1. Open [portal.azure.com](https://portal.azure.com).
    2. Go to **Microsoft Entra ID → Add → Enterprise Application**.
    3. Select the option to create your own app and choose the **non-gallery** type.
    4. Enter a name for the app. A descriptive name is recommended so it can be easily identified later, for example `Gr4vy Dashboard Sandbox/Production`.
    5. Click **Create**.

    <Note>
      Sandbox and production are configured separately. Create a separate enterprise
      app for each environment, each with its own values as shown below.
    </Note>
  </Step>

  <Step title="Configure SAML single sign-on">
    Select **Single sign-on** in the left menu, then choose **SAML** as the method. Edit the
    **Basic SAML Configuration** for the environment you are setting up:

    <Tabs>
      <Tab title="Sandbox">
        * **Identifier (Entity ID):** `urn:auth0:gr4vy:{instance_id}-sandbox-saml`
        * **Reply URL:** `https://auth.gr4vy.com/login/callback?connection={instance_id}-sandbox-saml&organization={instance_id}`
      </Tab>

      <Tab title="Production">
        * **Identifier (Entity ID):** `urn:auth0:gr4vy:{instance_id}-production-saml`
        * **Reply URL:** `https://auth.gr4vy.com/login/callback?connection={instance_id}-production-saml&organization={instance_id}`
      </Tab>
    </Tabs>

    Click **Save**.
  </Step>

  <Step title="Retrieve the connection details">
    1. Download the **Base64 Certificate** from the **SAML Signing Certificate** section.
    2. Copy the **Login URL**.
    3. Provide both to the support team so they can enable the connection.
  </Step>
</Steps>

## Users access

Once the app is set up, make sure the right users have access to it. Assign users or groups
to the enterprise app under **Users and groups**. Whichever approach you use, apply the
roles and environments below to the intended users.

## Roles and environments

By default, users are restricted to the `analyst` role in the `sandbox` environment. To assign
roles and environments, the `gr4vy_roles` and `gr4vy_environments` attributes must be included in
the SAML assertion. In Azure AD these are most commonly driven by group membership.

### Mapping Azure AD groups to Gr4vy roles

1. Create an Azure AD group for each Gr4vy role you need (up to nine). Only create the roles you
   actually use. If you want different roles across sandbox and production, create separate groups
   for each environment.
2. In the enterprise app, go to **Single sign-on → Attributes & Claims** and add a **group
   claim**.
3. Enable **Customize the name of the group claim** and set the name to `gr4vy_roles`.
4. Use the group claim's regular expression transformation to convert each Azure group name into the matching
   Gr4vy role name. For example: `Azure-ABS12123123-Tst_P_Administrator-AAD-Apps` → `Administrator`.
5. Role names are matched case-insensitively, as long as the transformed value matches a Gr4vy role
   name.

<Note>
  This approach relies on group names containing the Gr4vy role in a consistent, predictable format.
  Environments can be delivered in the same way, using a `gr4vy_environments` claim.
</Note>

### Roles

The `gr4vy_roles` property controls the roles a user has. This needs to be an array with one or more
of the following values. If not set, it defaults to `analyst`.

* `analyst`
* `administrator`
* `customer-support`
* `pii-viewer`
* `system-manager`
* `system-support`
* `user-manager`
* `report-manager`
* `report-viewer`

### Environments

The `gr4vy_environments` property controls which environments a user can access. This needs to be an
array with one or more of the following values. If not set, it defaults to `sandbox`.

* `production`
* `sandbox`