License AdministratorsSAML Single Sign-On (SSO)Overview

SAML Single Sign-On (SSO) Overview
PremiumBruno Logo

SAML SSO is available for Ultimate Edition customers behind a feature flag. Please contact your Bruno Account Manager to enable this feature.

What is SAML SSO?

SAML (Security Assertion Markup Language) Single Sign-On allows your organization to use your existing identity provider (IdP) to authenticate users accessing Bruno. With SAML SSO, users can sign in to Bruno using their corporate credentials without needing a separate Bruno password.

Benefits of SAML SSO with Bruno

Centralized Authentication

  • Single set of credentials: Admins and users access Bruno with the same credentials they use for other corporate applications
  • Streamlined access: One-click access to Bruno through your identity provider’s portal

Enhanced Security

  • Centralized access control: Manage Bruno access through your existing identity management system
  • Multi-factor authentication: Leverage your IdP’s MFA capabilities for Bruno access
  • Audit trail: Track all authentication activities in your identity provider
  • Automatic session management: Control session timeouts and security policies centrally

Operational Efficiency

  • Simplified onboarding: New employees automatically receive Bruno Ultimate access as part of their standard onboarding
  • Simplified offboarding: Departing employees automatically lose Bruno Ultimate access when removed from your IdP
  • Reduced administrative overhead: IT teams spend less time on manual user management

Supported Identity Providers

Bruno supports SAML 2.0 SSO with the following identity providers:

Prerequisites

Before configuring SAML SSO, ensure you have:

  • Ultimate Edition subscription with SAML SSO feature enabled
  • Admin access to the Bruno License Portal (https://license.usebruno.com/)
  • Admin access to your identity provider (Okta, Entra ID, etc.)

General Setup Flow

Setting up SAML SSO involves configuration in both your identity provider and Bruno:

1. Configure Your Identity Provider

In your identity provider (Okta, Entra ID, etc.):

  • Create a new SAML application for Bruno
  • Configure the SAML settings using Bruno’s ACS URL and Entity ID
  • Set up attribute mappings for user information
  • Configure role mappings for admin and user access
  • Assign users or groups to the Bruno application

2. Configure Bruno

In the Bruno License Portal:

  • Navigate to Settings → SSO
  • Toggle Enable SSO to on
  • Enter your IdP’s SAML metadata (Entity IDLogin URL, Certificate)
  • Configure Role Mapping to match your IdP’s role attributes
  • Set session timeout preferences
  • Save Configuration

3. Test and Verify

  • Test SSO login with a test user account
  • Verify user attributes are correctly mapped
  • Confirm role assignments work as expected
  • Test session timeout behavior

SAML Configuration Values

When configuring your identity provider, you’ll need these Bruno-specific values:

FieldValueNotes
ACS URLSpecific to your Bruno subscriptionCopy the exact SAML ACS URL from your Bruno SSO settings page. Format: https://license.usebruno.com/api/v2/auth/sso/saml/acs/{subscription-id}
SP Issuer ID / Entity IDEnter a unique valueCan be any unique identifier (e.g., bruno, bruno-demo). Must match exactly between Bruno and your IdP

Important: Always copy the ACS URL and SP Issuer ID / Entity ID directly from your Bruno SSO settings page. The Entity ID can be any unique value you choose, but it must match exactly between Bruno and your identity provider.

Required SAML Attributes

Bruno requires the following SAML attributes to be configured in your identity provider. These attributes are sent in the SAML assertion and used to provision and manage user access:

User Attributes

Attribute NameDescriptionExample Value
NameIDUser’s email address (unique identifier)user.mail or user.email - Must be in email format
rolesUser role(s) for access controlAny role value from your IdP (e.g., BrunoAdmin, Engineering, admin, user)
fullNameUser’s full nameuser.firstName+" "+user.lastName or equivalent

Attribute Configuration Details:

  • NameID: Bruno uses the NameID as the unique user identifier and email address. Configure your IdP to send the user’s email address as the NameID with format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. This is critical for user identification and license activation.

  • roles: This attribute contains the role value(s) from your identity provider. The value can be:

    • Any existing role or group attribute from your IdP (e.g., Engineering, BrunoAdmin, IT-Team)
    • A hardcoded value for testing purposes (e.g., admin, user)
    • Mapped from existing user attributes or group memberships in your IdP

    Important: The role values sent in the SAML assertion must be mapped to either “Admin Roles” or “User Roles” in the Bruno License Portal’s SSO Settings (see Role Mapping section below).

  • fullName: This attribute should contain the user’s complete name. It can be mapped to:

    • A single field if your IdP has a combined name field
    • A concatenation of first and last name fields (e.g., user.firstName+" "+user.lastName)
    • Any existing user property in your IdP that contains the full name

Example SAML Assertion

Here’s an example of how these attributes appear in a SAML assertion:

<saml2:AttributeStatement>
  <saml2:Attribute Name="roles" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:type="xs:string">admin</saml2:AttributeValue>
  </saml2:Attribute>
  <saml2:Attribute Name="fullName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:type="xs:string">user.firstName+" "+user.lastName</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>
⚠️

Important: Both attributes must be configured in your identity provider for SAML SSO to work correctly. The attribute names are case-sensitive and must match exactly as shown above.

Role Mapping

After configuring the roles attribute in your identity provider, you need to map those role values to Bruno access levels in the License Portal.

Configuring Role Mapping in Bruno

In the Bruno License Portal’s SSO Settings, you’ll find two fields under “Role Mapping”:

  1. Admin Roles: Comma-separated list of role values that should have admin access

    • Example: admin,BrunoAdmin,IT-Administrators
    • Users with these roles can access the admin panel and manage licenses
  2. User Roles: Comma-separated list of role values that should have user access

    • Example: user,Engineering,Developers
    • Users with these roles have standard access to Bruno
Bruno SAML SSO role mapping configuration showing Admin Roles and User Roles fields

How Role Mapping Works:

  1. Your IdP sends the roles attribute value in the SAML assertion (e.g., Engineering)
  2. Bruno checks if this value matches any role in the “Admin Roles” or “User Roles” fields
  3. If it matches “Admin Roles”, the user will be able to access the license portal and manage licenses
  4. If it matches “User Roles”, the user will be able to activate their license with SSO but will not have license portal access
  5. If it doesn’t match either, the user will be denied access

Example Configuration:

  • IdP sends: roles="Engineering"
  • Bruno Admin Roles: admin,BrunoAdmin
  • Bruno User Roles: user,Engineering,QA
  • Result: User gets standard access (matches “Engineering” in User Roles)

Important Implementation Details:

  • Role matching is case-sensitive - adminAdmin
  • A user can have multiple roles in the IdP; Bruno checks if any of them match the configured roles
  • If a user matches “Admin Roles”, they get admin access (even if they also match “User Roles”)
  • When a user is removed from the IdP, they lose access on their next login attempt
⚠️

Important: The role values are case-sensitive. Ensure the values in your IdP’s roles attribute match exactly with the values you configure in Bruno’s Admin Roles or User Roles fields.

License Activation and Access Control

License Activation Flow

For User Role Users:

  • Users can activate their Bruno license using SSO
  • They receive a license key via email on first login
  • They can use this key to activate Bruno on their local machine
  • They do NOT have access to the License Portal

For Admin Role Users:

  • Admins can access the License Portal to manage licenses and users
  • Admins can view all users in their subscription
  • Admins can manage role mappings and SSO configuration
  • Admins can view subscription details and usage

Session Management

  • Session timeout: Configured in Bruno SSO settings (default: 1 hour / 3600 seconds)
  • Minimum timeout: 60 seconds
  • Session cookies: Secure, HTTP-only cookies are used for session management
  • Logout: Users are logged out when the session expires or when they manually log out

Coordination with IdP Sessions: Bruno’s session timeout is independent of your IdP’s session timeout. The shorter timeout will take precedence. For example, if your IdP session expires after 30 minutes but Bruno is set to 1 hour, users will be logged out after 30 minutes.

Next Steps

Ready to configure SAML SSO? Choose your identity provider:

Need help? See our Troubleshooting Guide for common issues and solutions.