SAML SSO 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.

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)

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.

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

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

“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)

”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

”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

”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

”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

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

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

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

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

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

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 Entra ID
2. Contact 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
• Configure SAML SSO with Okta
• Configure SAML SSO with Entra ID
• SCIM Provisioning