> ## 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.

# Troubleshooting

This guide helps you diagnose and resolve common issues when configuring or using SAML Single Sign-On with Bruno.

## Quick Pre-Flight Checks

Before diving into technical troubleshooting, verify these basic prerequisites. Most SSO login failures are due to one of these issues:

### 1. Is SSO Enabled in Bruno?

**Check this first:**

* Go to Bruno License Portal (`https://license.usebruno.com/`)
* Navigate to **Settings** → **SSO**
* Verify the **"Enable SSO"** toggle is **ON**
* If it's OFF, toggle it ON and click **Save Configuration**

**Why this matters**: If SSO is disabled, all SSO login attempts will fail with a 500 error.

<Warning>
  **Important**: SSO must be enabled in the License Portal before users can log in via SSO. This is the first and most common cause of SSO login failures.
</Warning>

### 2. Is the User Already an Admin in Bruno License Portal?

Accessing the license portal requires admin access. Users will not need to be added as admins if they only need to activate their license via SSO.

**Check this next:**

* Go to Bruno License Portal → **Settings** → **Admins**
* Look for the user's email address in the Admins list
* If the user is NOT in the list, they must be added first before they can use SSO

**Why this matters**: Users must be configured as admins in Bruno BEFORE they can log in via SSO. SSO only authenticates users who are already admins in the system.

**If the user is not listed:**

1. Click the **"Add Admin"** button
2. Enter the user's email address
3. Click **Add**
4. The user will now be able to log in via SSO

**After the user is added as an admin, verify role mapping:**

* Go to Bruno License Portal → **Settings** → **SSO**
* Look at the **"Admin Roles"** field
* The user's role (from their IdP) must match one of the values in this field
* **Example**: If Admin Roles is set to `admin,BrunoAdmin`, the user's role must be exactly `admin` or `BrunoAdmin`

**How to verify the user's role:**

1. In your IdP, check what role value is assigned to the user
2. In Bruno License Portal → Settings → SSO, check the "Admin Roles" field
3. Ensure they match exactly (case-sensitive)

<Warning>
  **Two-Step Process**:

  1. First, add the user as an admin in Bruno License Portal (Settings → Admins)
  2. Then, ensure their IdP role matches the "Admin Roles" field in SSO settings

  Both steps are required for SSO login to work.
</Warning>

<Warning>
  **Role Matching is Case-Sensitive**: `admin` ≠ `Admin`. The role value from your IdP must match exactly what's in the Admin Roles field.
</Warning>

### 3. Is SSO Configuration Complete?

**Verify all required fields are filled:**

* Go to Bruno License Portal → **Settings** → **SSO**
* Check that these fields are NOT empty:
  * **SP Issuer ID / Entity ID**
  * **IdP Login URL**
  * **IdP Entity ID**
  * **IdP Certificate**
  * **Admin Roles** (at least one role value)

**Why this matters**: If any required field is missing, Bruno cannot generate a SAML request and will return a 500 error.

<Info>
  **Tip**: If you're not sure what values to use, refer to the [SAML SSO Overview](./overview) page for detailed explanations of each field.
</Info>

***

title: "SAML SSO Troubleshooting"
sidebarTitle: "Troubleshooting"

## Common Error Messages

### "500 Internal Server Error" When Clicking "Login with SSO"

**First, complete the pre-flight checks above** (Is SSO enabled? Is the user an admin? Is configuration complete?)

**Possible Causes:**

* SSO is not enabled in Bruno (see Pre-Flight Check #1)
* User is not a License Manager Admin (see Pre-Flight Check #2)
* SSO configuration is incomplete (see Pre-Flight Check #3)
* Entity ID mismatch between Bruno and your IdP
* Invalid or malformed certificate in Bruno configuration
* IdP Login URL is missing or incorrect

**What This Error Means:**
This error occurs when Bruno tries to generate a SAML authentication request but the SSO configuration is incomplete or invalid. The backend checks that all required fields are present before proceeding.

**Solutions:**

1. **Complete the pre-flight checks first**:
   * Verify SSO is enabled
   * Verify the user is a License Manager Admin (role matches Admin Roles)
   * Verify all required configuration fields are filled

2. **Verify Entity ID matches exactly**:
   * The "SP Issuer ID / Entity ID" in Bruno must match the "Identifier (Entity ID)" in your IdP configuration
   * Example: If Bruno has `bruno-demo`, your IdP must also have `bruno-demo`
   * The value can be anything, but it must be identical in both places

3. **Check certificate format**:
   * Open the certificate file you downloaded from your IdP
   * Copy the entire contents including `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines
   * Paste into Bruno's IdP Certificate field
   * Ensure there are no extra spaces or line breaks at the beginning or end

4. **Verify IdP Login URL is correct**:
   * The IdP Login URL should be the SAML entry point from your IdP
   * Example: `https://idp.example.com/app/123/sso/saml`
   * This is typically found in your IdP's SAML metadata

5. **Save the configuration**: Click "Save Configuration" button after making changes

6. **Check browser console**: Open Developer Tools (F12) → Console tab to see detailed error messages

7. **Try disabling and re-enabling SSO**: Toggle the "Enable SSO" switch off, save, then toggle it back on and save again

<Warning>
  **Backend Validation**: Bruno validates that SSO is enabled and all required configuration fields are present before generating the SAML request. If any field is missing or SSO is disabled, you'll see a 500 error. Check the browser console for the specific error message.
</Warning>

### IdP Test Login Shows Error or Redirects to Bruno Login Page

**Possible Causes:**

* Reply URL (ACS URL) is configured incorrectly in your IdP
* Certificate or metadata mismatch
* SSO not fully enabled in Bruno

**Solutions:**

1. **Verify Reply URL (ACS URL)**: In your IdP's SAML application configuration:
   * Should be: `https://license.usebruno.com/api/v2/auth/sso/saml/acs/<your-subscription-id>`
   * This is where your IdP sends the SAML response after authentication
   * The subscription ID is shown in the Bruno License Portal SSO settings page
   * This URL must match EXACTLY what's configured in Bruno
   * Copy this URL exactly from the Bruno SSO settings page
2. **Ensure SSO is enabled in Bruno**:
   * IdP test login will fail if SSO is not fully configured and enabled in Bruno
   * Complete the Bruno SSO configuration first, then test from your IdP
3. **Check the full error message**: The error message may be truncated. Try:
   * Opening the test in a new incognito/private browser window
   * Checking the browser console for the full error message
   * Looking at the Network tab in Developer Tools for the failed request
4. **Common error patterns**:
   * Reply URL mismatch: Check ACS URL configuration
   * Authentication method mismatch: Verify SAML 2.0 is configured
   * User not assigned: Ensure user is assigned to the Bruno application
   * Application not found: Verify application is properly configured

<Warning>
  **Microsoft Entra ID Specific**: If you see `AADSTS` error codes:

  * `AADSTS50011`: Reply URL mismatch - verify the ACS URL in Basic SAML Configuration
  * `AADSTS75011`: Authentication method mismatch - ensure SAML 2.0 is selected
  * `AADSTS50105`: User not assigned - assign user/group to the Bruno application in Enterprise Applications
  * `AADSTS700016`: Application not found - verify the application exists and is properly configured
  * `AADSTS50020`: User account from identity provider does not exist - ensure the user is assigned to the Bruno application in Entra ID
</Warning>

<Warning>
  **Okta Specific**: Common Okta-specific issues:

  * **"Invalid SAML Response"**: Check that the Okta application's SAML settings match Bruno's requirements exactly
  * **"User not assigned"**: In Okta Admin → Applications → Bruno app → Assignments, ensure users/groups are assigned
  * **"Invalid audience"**: Verify the Audience URI in Okta matches Bruno's SP Issuer ID exactly
  * **"Invalid destination"**: Ensure the Single Sign On URL in Okta matches Bruno's ACS URL
  * **Preview SAML assertion**: Use Okta's "Preview SAML assertion" feature to verify attribute values before testing
</Warning>

<Info>
  **Testing Order**: Always complete the Bruno SSO configuration first before testing from your IdP. The recommended testing flow is:

  1. Configure SSO in Bruno and save
  2. Test login by clicking "Login with SSO" from Bruno's login page (SP-initiated)
  3. Once that works, test login from your IdP portal (IdP-initiated)
</Info>

### "SAML Response Validation Failed"

**Possible Causes:**

* Certificate mismatch between IdP and Bruno configuration
* Expired or invalid SAML certificate
* Clock skew between IdP and Bruno servers

**Solutions:**

1. Verify the certificate in Bruno matches the certificate from your IdP
2. Ensure you've copied the entire certificate including `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines
3. Check that your IdP's certificate hasn't expired
4. Verify your server's system clock is synchronized (NTP)

<Warning>
  **Entra ID Specific**: Entra ID certificates auto-rotate. If you see certificate validation errors:

  * Check if Entra ID has issued a new certificate (Enterprise Applications → Bruno app → Single sign-on → SAML Certificates)
  * Download the new certificate and update it in Bruno's SSO configuration
  * Entra ID typically notifies admins 30 days before certificate expiration
</Warning>

### "Invalid ACS URL" or "Redirect URI Mismatch"

**Possible Causes:**

* Incorrect ACS URL configured in your IdP
* Missing or incorrect domain ID in the ACS URL
* ACS URL format doesn't match what Bruno expects

**Solutions:**

1. **Use the exact ACS URL shown in Bruno**: Copy the SAML ACS URL directly from the Bruno SSO settings page
   * The URL format may vary depending on your Bruno version
   * Common formats:
     * `https://license.usebruno.com/saml/acs/{your-domain-id}`
     * `https://license.usebruno.com/api/v2/auth/sso/saml/acs/{your-domain-id}`
2. Check that you've replaced `{your-domain-id}` with your actual domain ID from Bruno
3. Ensure there are no trailing slashes or extra spaces in the URL
4. **Important**: The ACS URL in your IdP must match EXACTLY what Bruno shows in the SSO settings page

<Info>
  Always copy the ACS URL directly from the Bruno SSO settings page rather than using the documentation examples, as the URL format may vary between Bruno versions.
</Info>

### "403 Forbidden" Error After Successful IdP Authentication

**Symptoms:**

* User successfully authenticates with their IdP
* User is redirected back to Bruno
* Bruno shows a 403 Forbidden error or "Access Denied" message
* Login does not complete

**What This Error Means:**
Bruno received a valid SAML response from your IdP, but the user's roles don't match any configured role in Bruno's "Admin Roles" or "User Roles" fields. This is a **role mapping issue** - the role value sent by your IdP doesn't match what's configured in Bruno.

**How Role Matching Works (Backend Logic):**

1. Bruno extracts the `roles` attribute from the SAML response
2. Bruno checks if ANY of the user's roles match the "Admin Roles" field
3. If not, Bruno checks if ANY of the user's roles match the "User Roles" field
4. If neither match, Bruno returns a 403 Forbidden error
5. **Important**: Role matching is case-sensitive and exact (`admin` ≠ `Admin`)

**Debugging Steps:**

1. **Check the SAML response** to see what role value is being sent:
   * Open browser dev tools (F12) → Network tab
   * Attempt SSO login again
   * Look for the POST request to `/api/v2/auth/sso/saml/acs/`
   * In the request payload, find the `roles` attribute value
   * Example: `<saml2:AttributeValue>admin</saml2:AttributeValue>`
   * Note: Users can have multiple roles; Bruno checks if ANY match

2. **Verify role mapping in Bruno**:
   * Go to Bruno License Portal → Settings → SSO
   * Check the "Admin Roles" and "User Roles" fields
   * Ensure the exact role value from the SAML response is listed in one of these fields
   * **Important**: Role matching is case-sensitive (`admin` ≠ `Admin`)

**Example Fix:**

* If SAML response shows: `<saml2:AttributeValue>admin</saml2:AttributeValue>`
* In Bruno Admin Roles field, add: `admin`
* Or in Bruno User Roles field, add: `admin`
* Click Save and test again

**Other Possible Causes:**

* Missing `roles` attribute in SAML response (not configured in IdP)
* User not assigned to the Bruno application in IdP
* Quotes in role values (e.g., `"admin"` vs `admin`)
* Role value is empty or whitespace

**Additional Checks:**

1. **User Assignment**: Verify the user is assigned to the Bruno application in your IdP
2. **Role Attribute Present**: Confirm the `roles` attribute is being sent in the SAML response (check Network tab)
3. **Quote Issues**: Remove quotes from role values in your IdP configuration
   * ❌ Bad: `"admin"` (with quotes)
   * ✅ Good: `admin` (no quotes)
4. **Empty Roles**: Ensure the role value is not empty or just whitespace

<Warning>
  **Okta Specific**: For 403 errors in Okta:

  * Check the **Group Assignments** tab in your Okta Bruno application - users must be assigned either directly or through groups
  * Verify **Application Visibility** settings - if "Hide application for users" is enabled, users may not be able to access it
  * Check **Sign On Policy** - ensure there are no conditional access rules blocking the user
  * Use Okta's **System Log** (Reports → System Log) to see detailed authentication attempts and failures
</Warning>

<Warning>
  **Entra ID Specific**: For 403 errors in Entra ID:

  * Check **Users and groups** assignment in Enterprise Applications → Bruno app
  * Verify **Conditional Access policies** aren't blocking the user (Azure AD → Security → Conditional Access)
  * Check **User Risk Policy** and **Sign-in Risk Policy** if Identity Protection is enabled
  * Review **Sign-in logs** (Azure AD → Monitoring → Sign-ins) for detailed error information
  * Ensure the user's account is not disabled or requires password reset
</Warning>

<Info>
  **Quick Test**: If you're unsure about role mapping, temporarily add a wildcard or common value like `user` to both Admin Roles and User Roles fields in Bruno, then check what role value your IdP is actually sending in the SAML response.
</Info>

### "User Not Found" or "Access Denied" After Role Mapping

**Symptoms:**

* User's role matches Bruno's role mapping (403 error is gone)
* But user still cannot access Bruno
* Error message indicates user not found or access denied

**What This Error Means:**
The user's role matched Bruno's configuration, but there's an issue with the user's email or account status. Bruno uses the NameID (email) from the SAML response to identify users.

**How User Identification Works (Backend Logic):**

1. Bruno extracts the NameID from the SAML response (this should be the user's email)
2. Bruno converts the email to lowercase for consistency
3. Bruno looks up the user in the database using this email
4. If the user doesn't exist, Bruno creates a new user account automatically
5. If the user exists but is inactive, Bruno reactivates them

**Debugging Steps:**

1. **Verify the NameID is an email address**:
   * Open browser dev tools (F12) → Network tab
   * Attempt SSO login again
   * Look for the POST request to `/api/v2/auth/sso/saml/acs/`
   * In the SAML response, find the NameID value
   * Example: `<saml:NameID>user@example.com</saml:NameID>`
   * Ensure it's a valid email address

2. **Check email consistency**:
   * The NameID email should match the user's email in your IdP
   * Bruno uses this email to identify and create user accounts
   * If the email changes between logins, Bruno will create a new account

3. **Verify user assignment in IdP**:
   * Ensure the user is assigned to the Bruno application
   * Check that the user's email is correctly configured in the IdP

**Solutions:**

1. Verify the user is assigned to the Bruno application in your IdP
2. Ensure the NameID in your IdP is configured to send the user's email address
3. Check that the user's email in the IdP is valid and consistent
4. Verify the email attribute is correctly mapped in your IdP (should be NameID, not a separate attribute)

### "Invalid Role" or "Insufficient Permissions"

**Possible Causes:**

* `roles` attribute not configured correctly in IdP
* `roles` attribute value doesn't match any role in Bruno's Admin Roles or User Roles fields
* `roles` attribute is missing from the SAML assertion
* Role mapping not configured in Bruno License Portal

**Solutions:**

1. Verify the `roles` attribute is configured in your IdP's SAML attribute statements
2. Ensure the attribute name is exactly `roles` (case-sensitive)
3. Check the SAML response to confirm the `roles` attribute is being sent and note its value
4. In Bruno License Portal → Settings → SSO, verify that the role value from the SAML assertion is listed in either:
   * **Admin Roles** field (for admin access), or
   * **User Roles** field (for standard access)
5. Ensure role values are case-sensitive matches (e.g., `Engineering` ≠ `engineering`)
6. For your IdP: Verify the attribute/claim name is `roles` and the value matches what you configured in Bruno's role mapping

<Info>
  **Okta Role Debugging**: Use Okta's **Preview SAML assertion** feature:

  1. Go to Okta Admin → Applications → Bruno app → General tab
  2. Click **Preview SAML assertion**
  3. Select a test user to see exactly what role values will be sent
  4. Verify the `roles` attribute appears with the expected value
  5. Copy this exact value to Bruno's Admin Roles or User Roles field
</Info>

<Info>
  **Entra ID Role Debugging**: Use the **Test single sign-on** feature:

  1. Go to Enterprise Applications → Bruno app → Single sign-on
  2. Click **Test single sign-on with Bruno**
  3. In the test results, expand **View SAML response** to see the actual claims being sent
  4. Look for the `roles` claim and note its value
  5. Ensure this exact value is configured in Bruno's role mapping fields
</Info>

### "Missing User Information" or "Name Not Displayed"

**Possible Causes:**

* `fullName` attribute not configured correctly in IdP
* `fullName` attribute is missing from the SAML assertion
* Name fields in IdP are empty
* `firstName` and `lastName` attributes are not configured as fallback

**What This Error Means:**
Bruno tries to extract the user's full name from the SAML response. If the `fullName` attribute is missing, Bruno attempts to construct it from `firstName` and `lastName` attributes. If all are missing, Bruno uses the email address as the name.

**How Name Extraction Works (Backend Logic):**

1. Bruno first looks for a `fullName` attribute in the SAML response
2. If `fullName` is not found, Bruno looks for `firstName` and `lastName` attributes
3. If found, Bruno combines them: `firstName + " " + lastName`
4. If none of these are found, Bruno uses the email address (NameID) as the name
5. The name is stored in the user's profile

**Debugging Steps:**

1. **Check what name attributes are being sent**:
   * Open browser dev tools (F12) → Network tab
   * Attempt SSO login again
   * Look for the POST request to `/api/v2/auth/sso/saml/acs/`
   * In the SAML response, look for these attributes:
     * `fullName` (preferred)
     * `firstName` and `lastName` (fallback)
   * Example: `<saml2:Attribute Name="fullName"><saml2:AttributeValue>John Doe</saml2:AttributeValue></saml2:Attribute>`

2. **Verify attribute names are case-insensitive**:
   * Bruno looks for attributes case-insensitively (e.g., `fullName`, `FullName`, `FULLNAME` all work)
   * But the attribute values are case-sensitive

3. **Check user profile after login**:
   * After a successful SSO login, check the user's profile in Bruno
   * If the name is just an email address, the name attributes weren't found

**Solutions:**

1. **Configure `fullName` attribute** (recommended):
   * Verify the `fullName` attribute is configured in your IdP's SAML attribute statements
   * Configure the attribute to combine first and last name (e.g., concatenation of first name + space + last name)
   * Check that user profiles in your IdP have first name and last name populated

2. **Or configure `firstName` and `lastName` attributes** (fallback):
   * If you can't use `fullName`, configure both `firstName` and `lastName` attributes
   * Bruno will automatically combine them with a space

3. **Verify attributes are being sent**:
   * Check the SAML response to confirm the name attributes are being sent
   * Use your IdP's preview/test feature to verify attribute values

<Info>
  **Okta fullName Configuration**: In Okta attribute statements:

  * **Name**: `fullName`
  * **Name format**: Unspecified
  * **Value**: `user.firstName+" "+user.lastName`
  * Alternative: `user.displayName` if your Okta users have display names configured
</Info>

<Info>
  **Entra ID fullName Configuration**: In Entra ID claims configuration:

  * **Claim name**: `fullName`
  * **Source**: Transformation
  * **Transformation**: `Join()`
  * **Parameter 1**: `user.givenname`
  * **Separator**: ` ` (space)
  * **Parameter 2**: `user.surname`
  * Alternative: Use `user.displayname` if available and properly formatted
</Info>

## Configuration Verification Checklist

Use this checklist to verify your SAML SSO configuration:

### Identity Provider Configuration

* [ ] SAML application created for Bruno
* [ ] ACS URL configured correctly (copy from Bruno SSO settings page)
* [ ] Entity ID configured to match Bruno's SP Issuer ID / Entity ID
* [ ] Name ID format set to EmailAddress
* [ ] **Required attribute: `roles`** configured to send user role values from your IdP (e.g., `Engineering`, `BrunoAdmin`, `IT-Team`, etc.)
* [ ] **Required attribute: `fullName`** configured (e.g., concatenation of first and last name)
* [ ] Users or groups assigned to the Bruno application
* [ ] SAML certificate is valid and not expired

### Bruno Configuration

* [ ] SAML SSO enabled in Bruno License Portal
* [ ] SP Issuer ID / Entity ID configured (must match IdP Entity ID exactly)
* [ ] IdP Login URL entered correctly
* [ ] IdP Entity ID entered correctly
* [ ] IdP Certificate pasted correctly (including BEGIN/END lines)
* [ ] **Admin Roles** configured with role values that should have admin access
* [ ] **User Roles** configured with role values that should have user access
* [ ] Role values match exactly (case-sensitive) with the values sent in the `roles` attribute from IdP
* [ ] Session timeout configured appropriately

## Testing and Debugging

### Test SSO Connection

1. In Bruno License Portal, navigate to **Settings** → **SAML SSO**
2. Click **Test SSO Connection**
3. You should be redirected to your IdP
4. Authenticate with your IdP credentials
5. You should be redirected back to Bruno
6. Verify your user information and roles are displayed correctly

### Check SAML Response

If SSO login fails, you can inspect the SAML response to diagnose issues:

1. Open your browser's developer tools (F12)
2. Go to the **Network** tab
3. Attempt to log in via SSO
4. Look for the POST request to `/saml/acs/`
5. Inspect the SAML response payload for errors

<Info>
  The SAML response contains assertions about the user's identity and attributes. Look for missing or incorrect attribute values.
</Info>

### Verify Attribute Mapping

To verify that user attributes are being sent correctly:

1. Complete a successful SSO login
2. In Bruno, check the user's profile information
3. Verify that the `fullName` attribute is populated correctly
4. If attributes are missing, check your IdP's attribute mapping configuration
5. Inspect the SAML response (see "Check SAML Response" section) to verify both `roles` and `fullName` attributes are present

### Verify Role Assignment

To verify that roles are being assigned correctly:

1. Complete a successful SSO login
2. Check if the user has the expected access level (admin vs. user)
3. If roles are incorrect:
   * Check the SAML response to see what value is being sent in the `roles` attribute
   * Verify the `roles` attribute is configured in your IdP
   * In Bruno License Portal → Settings → SSO, check the "Admin Roles" and "User Roles" fields
   * Ensure the role value from the SAML response matches one of the values in either field (case-sensitive)
   * Example: If SAML sends `roles="Engineering"`, make sure `Engineering` is listed in either Admin Roles or User Roles in Bruno

## Certificate Management

### Certificate Expiration

SAML certificates typically expire after 1-3 years. When a certificate expires:

1. Generate a new certificate in your IdP
2. Update the certificate in Bruno SAML SSO settings
3. Test the SSO connection to verify it works

<Warning>
  Set a reminder to renew your SAML certificate before it expires to avoid service disruption.
</Warning>

### Certificate Format Issues

If you encounter certificate errors:

1. Ensure the certificate is in PEM format (Base64 encoded)
2. Include the `-----BEGIN CERTIFICATE-----` header
3. Include the `-----END CERTIFICATE-----` footer
4. Remove any extra whitespace or line breaks within the certificate body
5. Do not include the private key (only the public certificate)

## Session and Timeout Issues

### Users Being Logged Out Unexpectedly

**Possible Causes:**

* Session timeout set too low
* IdP session timeout shorter than Bruno session timeout
* Browser cookie issues

**Solutions:**

1. Increase the session timeout in Bruno SAML SSO settings
2. Check your IdP's session timeout settings
3. Clear browser cookies and cache
4. Ensure cookies are enabled in the browser

<Info>
  **Okta Session Management**: Check these Okta settings:

  * **Global Session Policy** (Security → Authentication → Global Session Policy)
  * **Application Sign On Policy** (Applications → Bruno app → Sign On tab → Sign On Policy)
  * **Okta session lifetime** vs **Bruno session timeout** - the shorter one will take precedence
</Info>

<Info>
  **Entra ID Session Management**: Check these Entra ID settings:

  * **Conditional Access policies** with session controls (Azure AD → Security → Conditional Access)
  * **Token lifetime policies** (Azure AD → Security → Token lifetime policies)
  * **User sign-in frequency** settings in Conditional Access
  * **Persistent browser session** settings
</Info>

### Session Not Ending When Expected

**Possible Causes:**

* Session timeout set too high
* Browser keeping session alive

**Solutions:**

1. Decrease the session timeout in Bruno SAML SSO settings
2. Implement IdP-initiated logout if available
3. Educate users to log out manually when finished

## Attribute Configuration Troubleshooting

### SAML Attribute Configuration

**Issue**: Users not getting correct roles or missing name information

**Solutions:**

1. **Verify the `roles` attribute is configured in your IdP**:
   * Attribute/Claim name: `roles`
   * Value: Can be any value (e.g., `"admin"`, `"Engineering"`, department name, group name, etc.)
   * Ensure the attribute is included in the SAML assertion
2. **Verify the `fullName` attribute is configured in your IdP**:
   * Attribute/Claim name: `fullName`
   * Value: Combination of first and last name (e.g., "John Doe")
   * Common configurations:
     * Static concatenation: `firstName + " " + lastName`
     * Transformation/expression to join name fields
     * Direct mapping from a single name field
3. **Check attribute preview/test in your IdP** to see what values will be sent
4. **Ensure attribute names are case-sensitive and match exactly**
5. **Verify role mapping in Bruno**: In Bruno License Portal → Settings → SSO:
   * Check that the role value from your IdP is listed in either "Admin Roles" or "User Roles"
   * Example: If your IdP sends `roles="Engineering"`, ensure `Engineering` is in one of the role fields in Bruno

### Testing Roles with Hardcoded Values

**When to use this**: If you're having trouble getting role values to work correctly, you can temporarily configure a hardcoded role value in your IdP. This applies the same role to all users logging in via SSO and helps you isolate whether the issue is with role mapping or attribute configuration.

**Important**: This is for testing only. Once you verify SSO is working, configure proper role values based on your user directory.

**Steps to test with hardcoded roles:**

1. **In your IdP, configure the `roles` attribute with a static/hardcoded value**:
   * **Okta**: In the SAML app → General → SAML Attribute Statements, set:
     * Name: `roles`
     * Value: `admin` (or any test value)
     * This will send `roles="admin"` for all users

   * **Entra ID**: In Enterprise Applications → Single sign-on → Attributes & Claims, add a new claim:
     * Name: `roles`
     * Source: Attribute
     * Source attribute: Select any attribute (or use a static value if available)
     * Or use Transformation with a static value like `"admin"`

2. **In Bruno License Portal, add this test value to Admin Roles**:
   * Go to Settings → SSO
   * In the "Admin Roles" field, add the value you used (e.g., `admin`)
   * Click Save Configuration

3. **Test SSO login**:
   * Try logging in via SSO
   * If it works, the issue is with your role attribute configuration in the IdP
   * If it still fails, the issue is elsewhere (certificate, ACS URL, etc.)

4. **Once testing is complete**:
   * Remove the hardcoded value from your IdP
   * Configure proper role values based on your user directory (departments, groups, etc.)
   * Update Bruno's Admin Roles and User Roles fields with the actual role values

<Warning>
  **Important**: Hardcoded role values apply to ALL users logging in via SSO. Only use this for testing. Once you've verified SSO is working, configure role values that map to your actual user attributes or groups.
</Warning>

### Common IdP-Specific Configurations

**For Okta:**

* Attribute statements with Name format: Unspecified
* `roles` value examples: `"admin"`, `user.department`, static values
* `fullName` value: `user.firstName+" "+user.lastName`

**For Microsoft Entra ID:**

* Claims configuration with source: Attribute or Transformation
* `roles` value examples: static `admin`, `user.department`, group mappings
* `fullName` transformation: Join() with `user.givenname`, space separator, and `user.surname`

**For other SAML 2.0 providers:**

* Configure SAML attribute statements or claims
* Ensure attribute names match exactly: `roles` and `fullName`
* Use appropriate value mappings for your user directory

<Warning>
  **Okta Troubleshooting Tools**: Leverage these Okta-specific debugging features:

  * **System Log** (Reports → System Log): Search for authentication events and errors
  * **Preview SAML assertion**: Test attribute values before going live
  * **Application dashboard**: Monitor sign-in attempts and failures
  * **SAML Tracer browser extension**: Capture and analyze SAML requests/responses
  * **Okta Expression Language**: Use for complex attribute transformations
</Warning>

<Warning>
  **Entra ID Troubleshooting Tools**: Use these Entra ID-specific debugging features:

  * **Sign-in logs** (Azure AD → Monitoring → Sign-ins): Detailed authentication logs with error codes
  * **Audit logs** (Azure AD → Monitoring → Audit logs): Track configuration changes
  * **Test single sign-on**: Built-in testing tool with SAML response viewer
  * **Conditional Access insights**: See which policies are affecting sign-ins
  * **Identity Protection**: Monitor for risky sign-ins that might block SSO
  * **Enterprise Applications insights**: Application-specific usage and error analytics
</Warning>

## Troubleshooting Entra ID Group Claims

If you're using Entra ID group claims instead of App Roles, these additional troubleshooting steps apply.

### No Groups Appearing in the SAML Response

**Symptoms:** SSO redirects to Entra ID successfully, user authenticates, but Bruno shows "SSO Login failed" or "You do not have necessary permissions". Decoded SAML response has no `groups` or `roles` attribute in the `<AttributeStatement>`.

**Possible Causes and Fixes:**

1. **No group claim configured**
   * You need to explicitly add a group claim via "Add a group claim" in Attributes & Claims
   * Entra ID does not send group information by default
   * **Fix:** Follow the [Group Claims configuration guide](./configure-saml-sso-with-entra-id#option-b-using-entra-id-group-claims)

2. **"Filter groups" is checked with empty/incorrect filters**
   * Under Advanced options in the Group Claims panel, if "Filter groups" is checked but the filter fields are empty or misconfigured, all groups will be filtered out
   * **Fix:** Uncheck "Filter groups" unless you specifically need to filter

3. **Group not assigned to the Enterprise Application**
   * Even if users are members of the AD group, the group must also be assigned to the Bruno Enterprise Application under **Users and groups**
   * **Fix:** Go to Enterprise Application → Users and groups → Add the group

4. **Wrong source attribute for cloud-only groups**
   * If using `sAMAccountName` but your groups are cloud-only Entra ID groups (not synced from on-prem AD), no group names will be resolved
   * **Fix:** Switch to `Cloud-only group display names` or check "Emit group name for cloud-only groups"

5. **Selected wrong group type**
   * At the top of the Group Claims panel, ensure you selected "Groups assigned to the application" (not "None", "Security groups", or "All groups")

### How to Inspect the SAML Response

To diagnose group claim issues, inspect the actual SAML response:

1. Open Chrome DevTools → **Network** tab
2. Check **"Preserve log"** (important — the redirect will clear the log otherwise)
3. Attempt the SSO login
4. After the failure, find the POST request to `license.usebruno.com/api/v2/auth/sso/saml/acs/...`
5. In the **Payload** tab, copy the `SAMLResponse` value
6. Decode it at [samltool.io](https://samltool.io) or [samltool.com/decode.php](https://www.samltool.com/decode.php)
7. Look for the `<AttributeStatement>` section — verify a `groups` or `roles` attribute is present with the expected group names

### Group Name Doesn't Match Bruno Role Mapping

**Symptoms:** Groups appear in the SAML response but SSO still fails with "You do not have necessary permissions".

**Cause:** The group name in the SAML assertion doesn't exactly match what's configured in Bruno's Admin Roles or User Roles fields. Values are case-sensitive.

**Fix:** Compare the exact group name from the decoded SAML response with the values in Bruno License Portal → Settings → SSO → Role Mapping. They must match exactly, including casing and spacing.

### Claim Name Not Recognized by Bruno

**Symptoms:** A `groups` attribute is present in the SAML response with correct values, but Bruno still rejects the user.

**Cause:** The claim name may be a full URI (e.g., `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`) instead of a simple name. Bruno only recognizes: `role`, `roles`, `group`, `groups` (case-insensitive).

**Fix:** In the Group Claims configuration, check **"Customize the name of the group claim"** and set the Name to `groups`. Without this customization, Entra ID uses the full URI format which Bruno does not match.

<Info>
  **Quick Checklist for Group Claims:**

  * "Add a group claim" was used (not "Add new claim")
  * "Groups assigned to the application" is selected
  * "Filter groups" is unchecked under Advanced options
  * "Customize the name of the group claim" is checked and Name is set to `groups`
  * Source attribute matches your group type (cloud-only vs on-prem)
  * The group is assigned to the Enterprise Application (not just users being members)
  * Group name in Bruno role mapping matches exactly (case-sensitive)
</Info>

## Getting Additional Help

If you've tried the troubleshooting steps above and still encounter issues:

1. **Review Documentation**: Re-read the configuration guides for your specific IdP:
   * [Configure SAML SSO with Okta](./configure-saml-sso-with-okta)
   * [Configure SAML SSO with Entra ID](./configure-saml-sso-with-entra-id)
2. **Contact [Support](https://www.usebruno.com/support)**: Reach out to Bruno support with the following information:
   * Your Bruno subscription ID
   * Identity provider (Okta, Entra ID, or other SAML 2.0 provider)
   * Error messages you're seeing
   * Steps you've already tried
   * Screenshots of your configuration (redact sensitive information)

## Related Resources

* [SAML SSO Overview](./overview)
* [Configure SAML SSO with Okta](./configure-saml-sso-with-okta)
* [Configure SAML SSO with Entra ID](./configure-saml-sso-with-entra-id)
* [SCIM Provisioning](../scim-provisioning/overview)