SAML Configuration

  • Published on Apr 4, 2025
  • 3 minute(s) read

Security Assertion Markup Language (SAML) is a standard that enables Single Sign-On (SSO), allowing users to log in to multiple applications using a single set of credentials.

With SAML:

  • Your Identity Provider (IdP) handles authentication, such as Okta, Auth0, PingOne, OneLogin, or Azure AD.

  • Traceable acts as the Service Provider (SP) and trusts the identity information sent by your IdP.

When users log in via SSO, your IdP sends group information to Traceable. This group data is used to automatically assign users roles (like Developer or Account Owner).

Quick Flow Overview

Here’s how SAML login and role mapping works in Traceable:

User logs in → Identity Provider authenticates → Sends SAML assertion →
Traceable reads 'Group Attribute Name' and value → Matches group to role →
User is logged in with correct Traceable role

Benefits of SAML Integration

  • Users log in via your existing SSO system

  • Roles are assigned automatically based on user groups

  • No need to manage users directly in Traceable

  • Enforce consistent access policies across your organization

Before you begin

  • You must be a Traceable admin

  • You must have admin access to your IdP (Okta, Auth0, PingOne, OneLogin, or Azure AD)

  • The Traceable app must already be configured in your IdP
    (This includes setting up SAML metadata such as ACS URL and Entity ID, and enabling attribute mapping)

  • You must know the Group Attribute Name your IdP sends (e.g., groups, roles, okta.user)

Configure SAML Group Mapping by Identity Provider

To set up SAML group mapping with your Identity Provider (IdP), follow the specific guide for your platform:

Each guide includes step-by-step instructions on how to:

  • Configure the SAML assertion to include group data

  • Test and retrieve the attribute name and values

  • Map those values to Traceable roles inside the Traceable UI

Step 1: Access the SAML Configuration Page

  1. Log in to the Traceable UI

  2. Go to Configuration → Team

  3. Click the SAML Config tab

This section lists existing group mappings and allows you to create new ones.

Step 2: Map SAML Groups to Traceable Roles

You can map groups from your IdP to roles in Traceable to automatically assign permissions during login.

  1. Click + Add Group

  2. In the Map SAML Group to Roles window, enter the SAML Group Attribute Name

What is a SAML Group Attribute Name?

When a user logs in through SSO, your IdP sends a message to Traceable that includes user details, such as their name, email, and group membership. The Group Attribute Name is the label used for the group field.

In this context, a group refers to a defined set of users who share a common characteristic, role, or responsibility, such as:

  • Dev Team — all developers

  • Security Admins — security leads

  • ReadOnlyUsers — users with view-only access

Think of it as a class attendance sheet. The user’s name and class (group) are sent to Traceable, which then uses that info to assign access.

Example

Let us say the SAML assertion includes:

groups: Dev Team

Then:

  • Group Attribute Name: groups

  • Group Value: Dev Team

In Traceable:

  • Set SAML Group Attribute Name to groups

  • Map the Group Value Dev Team to the Developer role

  1. Click + Add Group to define mappings:

    • SAML Group: The group value from your IdP (for example, Security Admins).

    • Role: The Traceable role to assign (e.g., Developer, Viewer, Account Owner).

    • Scope: Define whether the role applies globally or to a specific environment.

  2. Click Add Role, then click Save

Step 3: Test the Configuration

After mapping your groups and saving the configuration, verifying that everything is working as expected is important.

  • Have a user from the mapped group log in using SSO

  • Confirm that the correct role is assigned

  • If the roles are not applied:

    • Check that attribute names and group values match exactly (including case)

    • Verify that the user is assigned to the group in your IdP

    • Inspect the SAML assertion using SAML-tracer

Troubleshooting Tips

If the role mapping is not working as expected, here are a few things to check before reaching out for support:

  • Group names are case-sensitive

  • The attribute name must match exactly

  • Verify that the user is assigned to the app in your IdP

  • Use your IdP’s logs or SAML-tracer to inspect what is being sent to Traceable

What’s Next?

After completing SAML configuration:

  • Users can log in through your organization’s IdP (SSO)

  • Roles are assigned automatically based on group membership

  • You can update mappings in Traceable at any time