> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebruno.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure SAML SSO with Microsoft Entra ID
This guide walks you through configuring SAML Single Sign-On for Bruno using Microsoft Entra ID (formerly Azure Active Directory) as your identity provider.
Before you begin, make sure you have completed the [prerequisites](./overview#prerequisites) and have admin access to both Microsoft Entra ID and the Bruno License Portal.
## Configure SSO in Bruno
Before configuring a SAML application in Microsoft Entra ID, first configure SSO in Bruno.
1. Log in to the [Bruno License Portal](https://license.usebruno.com/)
2. Navigate to **Settings** → **SSO** in the left sidebar
3. Toggle the **Enable SSO** switch on
4. Note the following values (you'll need these when configuring Entra ID):
* **SAML ACS URL**: Copy this URL exactly as shown in Bruno
* **SP Issuer ID / Entity ID**: Set your own unique identifier (e.g., `bruno-sso`, `bruno-entra`, `your-company-bruno`, etc.)
Keep this page open in a separate tab - you'll return here after configuring Entra ID to complete the Bruno SSO setup.
## Configure SSO with Microsoft Entra ID
### Step 1: Create a New Enterprise Application
1. Log in to the [Microsoft Entra admin center](https://entra.microsoft.com/)
2. On the left sidebar, navigate to **Enterprise apps** → **+ New application**
3. Click **Create your own application**
4. Enter the application name: Set your own unique identifier (e.g., `Bruno`, `Bruno-SAML-App`, etc.)
5. Select **Integrate any other application you don't find in the gallery (Non-gallery)**
6. Click **Create**
### Step 2: Select SAML as Single Sign-On Method
1. In the created Enterprise Application, navigate to **Manage** → **Single sign-on** in the left sidebar
2. Select **SAML** as the single sign-on method
### Step 3: Configure Basic SAML Configuration
1. Under **Single sign-on** section in the **Basic SAML Configuration** section, click **Edit**
2. Copy the values from the Bruno SSO settings page and paste them into your SAML configuration in Microsoft Entra ID:
* **Identifier (Entity ID)**: Paste the **SP Issuer ID / Entity ID** value from the Bruno License Portal
* **Reply URL (Assertion Consumer Service URL)**: Copy and paste the **SAML ACS URL** from the Bruno License Portal
3. Click **Save**
**Critical**: The Entity ID in Entra ID must match EXACTLY what you configured in Bruno's **SP Issuer ID / Entity ID** field. A mismatch will cause authentication failures.
### Step 4: Configure Attributes & Claims
Bruno requires three specific SAML attributes to be configured in Entra ID:
* `Unique User Identifier (Name ID)`, `roles`, and `fullName`
These attributes map user information from Entra ID to your Bruno subscription, ensuring users get the correct access levels.
**How Attribute Mapping Works:**
* **User Identification**: Bruno uses the email address (NameID) to match the SSO user with existing Bruno users in your subscription
* **Role Assignment**: The `roles` attribute determines whether the user gets admin or standard access in Bruno
* **Profile Information**: The `fullName` attribute populates the user's display name in Bruno
#### Required Claims
In the **Attributes & Claims** section:
1. Click **Edit**
2. Delete any existing claims that are not on this list
3. You will now update the claims to match the following:
| Claim Name | Source Attribute | Notes |
| ------------------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Unique User Identifier (Name ID)** | `user.mail` | Required for user identification. |
| **roles** or **groups** | `user.assignedroles`, `user.groups`, or other attribute | Use `roles` with App Roles (`user.assignedroles`), OR use `groups` via "Add a group claim" for AD/Entra groups. See details below. |
| **fullName** | Transformation: `user.givenname + " " + user.surname` or equivalent attribute | Represents the combined user's first and last name. |
#### Configuring the `Unique User Identifier (Name ID)` claim
This claim is required for user identification. It will be mapped to the user's email address in Entra ID.
2. Click the `Unique User Identifier` claim
3. Select the **Source Attribute** option
4. Choose `user.mail` as the attribute
5. Click **Save**
#### Configuring Role or Group Claims
Bruno needs to know what role a user should have (admin or standard user). You can send this information using **either** of two approaches — choose the one that fits your organization:
* **Option A: Use App Roles or User Attributes** — Create a `roles` claim mapped to App Roles, user attributes like `user.department`, or static values
* **Option B: Use Entra ID Group Claims** — Send existing AD/Entra ID group memberships directly in the SAML assertion
Both approaches are equally valid. Choose based on how your organization already manages access.
#### Option A: Using App Roles or User Attributes
The `roles` claim will represent the user's roles in Bruno. This role value will be mapped to Bruno access levels for the License Portal and for License Activation. These roles could be hardcoded, mapped to existing user attributes, originate from [App Roles](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-use-app-roles-customers#app-roles), etc.
On the **Attributes & Claims** page:
1. Click **Add new claim**
2. Enter `roles` as the name
3. Configure the claim as follows:
* **Map to existing user attribute**:
* Under **Source**, select **Attribute**
* Choose an existing user attribute like `user.assignedroles`, `user.department`, `user.jobtitle`, or custom attributes
4. Click **Save**
**Important**: The role value sent by Entra ID will be mapped to Bruno access levels in the License Portal's SSO Settings. You'll configure which role values correspond to admin or user access in Bruno (see Step 2 in the Bruno configuration section below).
#### Option B: Using Entra ID Group Claims
If your organization already has Active Directory or Entra ID groups set up for managing access (e.g., `Bruno-Admins`, `Bruno-Users`), you can use **Group Claims** to send group membership directly in the SAML assertion.
Bruno's backend recognizes SAML attributes named `role`, `roles`, `group`, or `groups` (case-insensitive) for role mapping.
**On the Attributes & Claims page:**
1. Click **"Add a group claim"** (not "Add new claim")
2. Under "Which groups associated with the user should be returned in the claim?", select **"Groups assigned to the application"**
* Do **not** select "All groups" or "Security groups" — this can include unrelated groups and may hit Entra ID's 150-group limit for SAML tokens
3. Configure the **Source attribute** based on your group type:
* **Cloud-only Entra ID groups**: Select `Cloud-only group display names`
* **On-premises AD groups** (synced via Entra Connect): Select `sAMAccountName`
* If unsure, try `Cloud-only group display names` first
4. Expand **Advanced options** and ensure:
* **"Filter groups" is unchecked** — if checked with empty or incorrect filter fields, no groups will be included in the SAML response
* **"Customize the name of the group claim"** is checked
* Set the **Name** to `groups` (Bruno recognizes `groups`, `group`, `roles`, and `role` as valid claim names)
5. Click **Save**
**Important:** The group must be **assigned to the Enterprise Application** in Entra ID. Go to your Bruno Enterprise Application → **Users and groups** → click **Add user/group** and add the relevant groups. Simply being a member of the AD group is not enough — the group must be explicitly assigned to the application.
After saving, your finalized Attributes & Claims should look like the following. Note that the `roles` and `groups` claims can be used **alone or together** — Bruno will accept either or both for role mapping:
| Claim Name | Type | Value | Required |
| ------------------------------------ | ---- | ------------------------------------------ | ------------------------------------------ |
| **Unique User Identifier (Name ID)** | SAML | `user.mail` | Yes |
| **fullName** | SAML | `Join (user.givenname, " ", user.surname)` | Yes |
| **groups** | SAML | `user.groups` | Optional — use alone or alongside `roles` |
| **roles** | SAML | `user.assignedroles` | Optional — use alone or alongside `groups` |
Then in the Bruno License Portal under **Settings → SSO → Role Mapping**, enter the **exact group display names** as they appear in Entra ID:
* **Admin Roles**: e.g., `Bruno-Admins` or `Your-Company_Bruno_Admin`
* **User Roles**: e.g., `Bruno-Users` or `Your-Company_Bruno_Users`
Role values are case-sensitive and must match exactly with the group names in Entra ID.
**Example Scenarios:**
* If you set a static value of `Engineering`, you'll add the value `Engineering` in the Bruno License Portal to the corresponding Admin or User role field
* If you map to `user.department` and a user's department is `IT`, you'll add `IT` to the appropriate role field in the Bruno License Portal
#### Configuring the `fullName` claim
The `fullName` claim represents the user's full name. This may already be available in your Entra ID user profile as a single field (e.g., `user.displayname`). If so, you can map the `fullName` attribute directly to that field.
If a full name field is not available, you can concatenate the first and last name fields using a transformation as follows:
On the **Attributes & Claims** page:
1. Click **Add new claim**
2. Enter `fullName` as the name
3. Under **Source**, select **Transformation**
4. In **Manage Transformation**, configure the transformation:
* **Transformation**: `Join()`
* **Parameter 1**: `user.givenname`
* **Separator**: ` ` (space)
* **Parameter 2**: `user.surname`
5. Click **Save**
#### Finalized Attributes & Claims Configuration
Return to the **Attributes & Claims** page and verify the following:
1. Any other claims that are not shown below have been deleted
2. The `Unique User Identifier (Name ID)` and `fullName` claims are configured
3. Either `roles` (Option A), `groups` (Option B), or both are configured based on your chosen approach
**Important**: A role or group claim (`roles` or `groups`) and the `fullName` attribute are required for Bruno SAML SSO to function correctly. The attribute names are case-sensitive and must match the appropriate values configured in Entra ID.
## Finish SSO Configuration in Bruno
### Step 1: Add SSO URL to Bruno License Portal
**IdP Login URL / SSO URL**
1. Return to the Enterprise Application page and navigate to **Manage** → **Single sign-on** in the left sidebar
2. In the **Set up 'AppName'** section 4, copy the following value:
* **Login URL**: Copy this URL
3. Return to the [Bruno License Portal](https://license.usebruno.com/) tab you opened [from the earlier configuration](#configure-sso-in-bruno)
4. Navigate to **Settings** → **SSO** (if not already there)
5. Under **SAML Configuration** paste the **Login URL** from Entra ID into the **IdP Login URL / SSO URL** field
### Step 2: Add IdP Certificate to Bruno License Portal
**Entra ID IdP Certificate**
1. In the **SAML Certificates** section 3:
* **Certificate (Base64)**: Download the certificate
2. Open the downloaded certificate file and copy the contents (include the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines)
3. Return to the Bruno License Portal tab
4. Under **SAML Configuration** paste the certificate contents into the **IdP Certificate** field
### Step 3: Map the role values from Entra ID to Bruno access levels
1. Under the Bruno License Portal in the SSO Configuration page, scroll down to the **Role Mapping** section
2. **Admin Roles**: Enter the role values (comma-separated) that will have admin access to the Bruno License Portal
* Example: `admin,BrunoAdmin,IT-Administrators`
* These values must match what you configured in the `roles` attribute in Entra ID
* Users with these roles can access the admin panel and manage licenses
3. **User Roles**: Enter the role values (comma-separated) that should have user access to Bruno
* Example: `user,Engineering,Developers,QA`
* These values must match what you configured in the `roles` attribute in Entra ID
* Users with these roles will be able to activate their Bruno licenses with SSO. **They will not have access to the admin panel.**
**How Role Mapping Works:**
The role value you configured in Entra ID's `roles` claim will be sent in the SAML assertion. Bruno will check if this value matches any role in the "Admin Roles" or "User Roles" fields.
**Example:**
* In Entra ID, you set the `roles` claim to map to `user.department`
* A user's department is `Engineering`
* In Bruno Admin Roles, you enter: `admin,IT`
* In Bruno User Roles, you enter: `user,Engineering,QA`
* Result: Users from the Engineering department get standard access (matches "Engineering" in User Roles)
**Important**: Role values are case-sensitive. Ensure the values in Entra ID's `roles` claim match exactly with the values you enter in Bruno's Admin Roles or User Roles fields.
### Step 4: Configure Session Settings
1. Scroll down to the **Session Timeout** section:
* Set the session timeout in seconds (default: 3600 = 1 hour)
2. Click **Save Configuration** to apply your SAML SSO configuration
## Test Your SAML Configuration
### Assign Users or Groups
1. In your Entra ID Enterprise Application, navigate to **Manage** → **Users and groups** in the left sidebar
2. Click **Add user/group**
3. Select the users or groups that should have access to Bruno, if using [App Roles](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-use-app-roles-customers#app-roles) they can be assigned here
4. Click **Assign**
### Test SSO Login
1. Navigate to the Bruno License Portal ([https://license.usebruno.com/](https://license.usebruno.com/))
2. Enter the email address of a user assigned to the Bruno app in Entra ID
3. Click **Login with SSO**
4. You should be redirected to Entra ID to authenticate
5. If your user is an admin in Bruno and contains the correct role mapping, you should be redirected back to the Bruno License Portal
## Next Steps
After setting up SSO with Microsoft Entra ID, you can:
* [Configure SCIM Provisioning](../scim-provisioning/overview) to automate user provisioning and deprovisioning
* [Manage your Bruno licenses](../license-portal) in the License Portal
## Related Resources
For more information about configuring SAML SSO and managing roles in Microsoft Entra ID, refer to these Microsoft documentation resources:
* [SAML authentication with Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/architecture/auth-saml) - Overview of SAML protocol and authentication flow
* [Enable SAML single sign-on for an enterprise application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso) - Step-by-step guide for SAML SSO setup
* [Customize SAML token claims](https://learn.microsoft.com/en-us/entra/identity-platform/saml-claims-customization) - Configure custom attributes and claims for SAML applications
* [Using App Roles for role-based access control](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-use-app-roles-customers) - Configure and use App Roles for fine-grained access control
* [Manage federation certificates for federated single sign-on](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/tutorial-manage-certificates-for-federated-single-sign-on) - Manage and renew SAML certificates
* [Plan a single sign-on deployment](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/plan-sso-deployment) - Best practices and planning guide for SSO deployment