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. SAML configuration also supports SAML Group Mapping, which allows administrators to associate identity provider groups with Traceable roles. When a user authenticates, Traceable evaluates their group membership and automatically applies the corresponding role, removing the need for manual role assignment.
What will you learn in this topic?
By the end of this topic, you will be able to understand:
How to configure SAML authentication for your organization in Traceable.
How to create and manage SAML Group Mappings to automate role assignment.
How Traceable evaluates group membership during authentication to determine user permissions.
The benefits of SAML Group Mapping include consistent access control and reduced administrative overhead.
Understand SAML
Once SAML authentication is configured, you can further simplify user management through SAML Group Mapping. Instead of manually assigning roles whenever users log in, you can map identity provider groups directly to Traceable roles if you are logged in as an administrator. When a user authenticates through the configured SAML provider, Traceable evaluates the user's group membership and automatically assigns the appropriate platform role based on the configured mappings.
SAML Config
Traceable matches the group value in the assertion against your configured mappings and assigns the corresponding role. The login and mapping flow works as follows:
The user logs in, and the IdP authenticates them and sends a SAML assertion.
Traceable reads the Group Attribute Name and its value from the assertion.
Traceable matches the group value to a configured role.
The user is logged in with the 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
Before you proceed to configure SAML, make a note of the following:
Make sure you have the Traceable admin.
Make sure you 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 (for example,
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 User interface.
Step 1 — Access the SAML configuration page
Log in to the Traceable UI
Go to Configuration → Team
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.
Click + Add Group
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 developersSecurity Admins— security leadsReadOnlyUsers— 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
Suppose the SAML assertion includes groups: Dev Team. In Traceable:
Set the Group Attribute Name to
groups.Map the group value
Dev Teamto the Developer role.
Click + Add Group to define mappings:
SAML Group — The group value from your IdP, for example, Security Admins.
Role — The Traceable role to assign, for example, Developer, Viewer, Account Owner.
Scope — Define whether the role applies globally or to a specific environment.
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.
Next steps
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.