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

# Microsoft Entra ID

> Configure Microsoft Entra ID (formerly Azure AD) as a SAML or OIDC single sign-on provider for Bronto, and map Entra ID groups to Bronto roles.

## Overview

Microsoft Entra ID can be configured as an identity provider for Bronto using either **SAML** or **OIDC**. Both options let your users sign in to Bronto with their existing Microsoft credentials, and both support [role mapping](/Account-Management/SSO/SSO-Role-Mapping) so Bronto permissions are provisioned automatically from your Entra ID group membership.

Choose the option that matches your organization's preference:

* **SAML** — Configure Bronto as a SAML application in Entra ID. Best if your organization standardizes on SAML for enterprise apps.
* **OIDC** — Register Bronto as an app registration and authenticate through OpenID Connect.

Before you begin you need a Microsoft Entra ID tenant and an account with the **Global Administrator**, **Cloud Application Administrator**, or **Application Administrator** role.

For Microsoft's own reference, see [Microsoft Entra ID documentation](https://learn.microsoft.com/en-us/entra/identity/).

<Note>
  If you intend to use role mapping, first create an attribute mapping to **custom:member\_of** when configuring the IdP in Bronto. See [SSO Role Mapping](/Account-Management/SSO/SSO-Role-Mapping).
</Note>

## Manage SSO providers in Bronto

You configure and manage identity providers from **Settings** > **Authentication** > **Login Methods**. The **SSO** section lists your existing SAML and OIDC providers and lets you add new ones.

Each provider row shows its type (SAML or OIDC), associated email domains, user count, and last login, with controls to enable/disable, view details, edit, or delete it. Click **Add Provider** to launch the setup wizard. On the first step you set **Choose protocol** to **SAML** or **OIDC**; the wizard then has four steps — **Name**, **Upload** (SAML) or **Provide** (OIDC), **Email**, and **Map**.

## SAML authentication

### Step 1: Create the Enterprise Application in Entra ID

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
2. Navigate to **Identity** > **Applications** > **Enterprise applications**.
3. Click **New application**, then **Create your own application**.
4. Enter a name (e.g. "Bronto"), select **Integrate any other application you don't find in the gallery (Non-gallery)**, and click **Create**.

See Microsoft's [Add an enterprise application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal) and [Configure SAML-based single sign-on](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso) for full details.

### Step 2: Configure SAML in Entra ID

1. In the new application, open **Single sign-on** and select **SAML**.
2. Edit the **Basic SAML Configuration** and enter the following values from Bronto. They appear in the **Paste these into your IdP** panel on the **Upload** step of the Bronto wizard (see Step 4), and again whenever you open the provider from the **SSO** list:
   * **Identifier (Entity ID)** — Use the **Entity ID** from Bronto.
   * **Reply URL (Assertion Consumer Service URL)** — Use the **ACS URL** from Bronto.
   * **Relay State** — Use the **Default Relay State** from Bronto.
3. Click **Save**.

### Step 3: Configure attributes and claims

Bronto requires **First name**, **Last name**, and **Email** attributes. In **Attributes & Claims**, map the Entra ID source attributes to the attribute names you configured when creating the IdP in Bronto. Entra ID's defaults are:

| Bronto attribute | Entra ID source attribute |
| ---------------- | ------------------------- |
| First name       | `user.givenname`          |
| Last name        | `user.surname`            |
| Email            | `user.mail`               |

To use role mapping, add a **group claim** that emits group membership and map it to the attribute mapped to **custom:member\_of** in Bronto:

1. In **Attributes & Claims**, click **Add a group claim**.
2. Select which groups to emit (e.g. **Groups assigned to the application**).
3. Under **Source attribute**, choose **Group ID**. Bronto matches role mappings on the group's **Object ID** (a GUID in the form `00000000-0000-0000-0000-000000000000`), so the claim must emit group IDs rather than display names.
4. Set the claim name to match the source attribute you mapped to **custom:member\_of** in Bronto.

For details, see Microsoft's [Configure group claims for applications](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims). Then see [Map Entra ID groups to Bronto roles](#map-entra-id-groups-to-bronto-roles) below.

### Step 4: Configure the IdP in Bronto

1. In Entra ID, download the **Federation Metadata XML** from the **SAML Certificates** section.
2. In Bronto, go to **Settings** > **Authentication** > **Login Methods** and click **Add Provider** in the **SSO** section.
3. Work through the wizard:
   * **Name** — Give the provider a unique name and set **Choose protocol** to **SAML**.
   * **Upload** — Upload the Federation Metadata XML. The **Paste these into your IdP** panel shows the **ACS URL**, **Entity ID**, and **Default Relay State** to configure on the Entra ID side (Step 2).
   * **Email** — Add the email domains to route to this provider.
   * **Map** — Map your IdP attributes to Bronto's required **First Name**, **Last Name**, and **Email**. To use role mapping, click **+ Add role mapping** and map your group claim to **custom:member\_of**.
4. Click **Save** to create and enable the IdP.

### Step 5: Assign users or groups

1. In the Enterprise Application, go to **Users and groups**.
2. Click **Add user/group** and select the users or security groups who should have access to Bronto.
3. Click **Assign**.

<Tip>
  Assigning a security group is recommended over individual users for easier ongoing access management.
</Tip>

## OIDC authentication

### Step 1: Register the application in Entra ID

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
2. Navigate to **Identity** > **Applications** > **App registrations** and click **New registration**.
3. Enter a name (e.g. "Bronto").
4. Under **Redirect URI**, select **Web** and enter the URI for your Bronto region:
   * **EU:** `https://auth.eu.bronto.io/oauth2/idpresponse`
   * **US:** `https://auth.us.bronto.io/oauth2/idpresponse`
5. Click **Register**.
6. From the app **Overview**, note the **Application (client) ID** and your **Directory (tenant) ID**.
7. Go to **Certificates & secrets**, create a **New client secret**, and note its value.

See Microsoft's [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) for full details.

### Step 2: Configure SSO in Bronto

In Bronto, go to **Settings** > **Authentication** > **Login Methods**, click **Add Provider** in the **SSO** section, and work through the four steps of the wizard.

#### Name

Enter a unique **Provider name** for this IdP within your organisation (e.g. "EntraIDtest") and select **OIDC** as the **Identity Provider type**.

#### Provide

The **Paste these into your IdP** panel on the right shows the values Bronto generates for your account and region. Use these in your Entra ID app registration first:

* **Redirect URI** — e.g. `https://auth.eu.bronto.io/oauth2/idpresponse` (or `auth.us.bronto.io` for US). This matches the Redirect URI you set in Step 1.
* **Start URL** — used for IdP-initiated sign-in.

Then paste your Entra ID values into the fields on the left:

* **Client ID** (from Step 1)
* **Client Secret** (from Step 1)
* **Issuer URL:** `https://login.microsoftonline.com/<tenant-id>/v2.0`, where `<tenant-id>` is your **Directory (tenant) ID** from Step 1.

#### Email

Add the email domains that should route to this provider (e.g. `contoso.com`, `contoso.onmicrosoft.com`). Type each domain and press **Enter**.

#### Map

Tell Bronto where to find each user attribute in the OIDC payload. Entra ID's defaults are:

| IdP attribute | Bronto attribute                        |
| ------------- | --------------------------------------- |
| `email`       | Email *(required)*                      |
| `family_name` | Last Name *(required)*                  |
| `given_name`  | First Name *(required)*                 |
| `groups`      | `custom:member_of` *(for role mapping)* |
| `sub`         | —                                       |

To use role mapping, add a row mapping the **`groups`** IdP attribute to **`custom:member_of`**. Click **Save** to create and enable the IdP.

### Step 3: Configure the Homepage URL for IDP-initiated login (optional)

To launch Bronto directly from the Microsoft My Apps portal, set the application's Homepage URL to the IDP-initiated login URL:

1. In the [Microsoft Entra admin center](https://entra.microsoft.com), open the linked **Enterprise Application** for your app registration (from the app **Overview**, click the link next to **Managed application in local directory**).
2. Go to **Properties** and paste the Start URL from Bronto (or an equivalent constructed login URL) into the **Homepage URL** field.
3. Set **Enabled for users to sign-in?** and **Visible to users?** to **Yes**, then click **Save**.

<Note>
  My Apps can take up to 10 minutes to reflect changes after setup. If the tile does not appear immediately, wait a few minutes and hard-refresh the page.
</Note>

## Map Entra ID groups to Bronto roles

Role mapping uses the **custom:member\_of** attribute. When you emit Entra ID group membership into that attribute (a group claim for SAML, or the groups claim for OIDC), Bronto matches each group value to a Bronto role.

Bronto matches on the Entra ID group's **Object ID** — the GUID assigned to the group in Entra ID, not its display name. You can find a group's Object ID in the [Microsoft Entra admin center](https://entra.microsoft.com) under **Identity** > **Groups** > select the group > **Overview**.

1. Ensure the **custom:member\_of** attribute mapping is configured for your Entra ID IdP, and that Entra ID emits group **Object IDs** into it (see Step 3 of SAML, or Step 2 of OIDC above).
2. In Bronto, go to **Settings** > **Authentication** > **SAML Role Mappings**.
3. Click **+ New Mapping** and create a mapping for each group, selecting the Bronto **Role** and entering the group's Object ID as the **Provider Value** (the **Provider Key** is `custom:member_of`).

For example, to grant the Administrator role to a group, set the **Provider Value** to that group's Object ID (a GUID in the form `00000000-0000-0000-0000-000000000000`) and select **Administrator Role**.

For full details on creating and editing mappings, see [SSO Role Mapping](/Account-Management/SSO/SSO-Role-Mapping).

<Warning>
  If a user doesn't match any role mapping, they will be given the **Standard** role by default.
</Warning>

## Troubleshooting

* **Authentication fails:** Verify the Client ID and Client Secret (OIDC) or the Entity ID, ACS URL, and certificate (SAML) are correct.
* **Redirect errors:** Ensure the redirect URI exactly matches the region-specific value configured in Entra ID.
* **User cannot access the application:** Check user and group assignments in the Enterprise Application.
* **Missing user information:** Verify attribute mapping in both Entra ID and Bronto.
* **Roles not applied:** Confirm the group claim emits group **Object IDs** and is mapped to **custom:member\_of**, and that matching Object IDs exist as the **Provider Value** in **SAML Role Mappings**.
* **"Need admin approval":** An administrator must grant consent for the app in **Enterprise Application** > **Permissions** > **Grant admin consent**.

For questions about your Bronto SSO parameters or configuration, contact [support@bronto.io](mailto:support@bronto.io).