SAML Configuration

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 you will learn from 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.

Before you begin

Before you proceed to configure SAML, make a note of the following:

• Make sure that you have the Traceable Account Owner access with Edit permissions.

• Make sure you have admin access to your IdP (Okta, Auth0, PingOne, OneLogin, or Azure AD).

• Make sure the Traceable app is already configured in your IdP, including setting up SAML metadata, such as ACS URL and Entity ID, and enabling attribute mapping.

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.

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:

1. The user logs in, and the IdP authenticates them and sends a SAML assertion.

2. Traceable reads the Group Attribute Name and its value from the assertion.

3. Traceable matches the group value to a configured role.

4. The user is logged in with the correct Traceable role.

Configure SAML group mapping

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

• Set Up SAML Group Mapping with Okta

• Set Up SAML Group Mapping with Azure AD (Entra ID)

• Set Up SAML Group Mapping with OneLogin

These guides explain how to configure the SAML assertion to include group information and identify the group attribute name and values required for the mapping.

Add a SAML group mapping

To add a SAML group mapping, complete the following steps:

1. Navigate to Settings → Team, then open the SSO Config tab.

2. Click + Add group.

3. Complete the following fields to configure the group mapping in the opened slide-out panel:

   • Type — Select SAML.

   • SAML Group Attribute Name — Enter the name of the attribute in the SAML assertion that contains the user's group information.

   • SAML Group — Enter the group value provided by your IdP.

   • Role — Select the Traceable role to assign to users in the specified group.

   • Scope — Select the scope to which the role applies.

4. Click Add Role to assign additional roles to the group, if required.

5. Click + Add Group to configure additional group mappings, if required.

6. Click Save.

Example

For example, if your IdP includes the following group information in the SAML assertion:

demo_group: sample_SAML

Configure the corresponding mapping in Traceable as follows:

• Type — Select SAML to indicate that the mapping uses SAML group information.

• SAML Group Attribute Name — Specfiy thedemo_group, which is the attribute name provided in the SAML assertion.

• SAML Group — Specify sample_SAML, which is the group value sent by the IdP.

• Role — Select Developer to assign the Developer role to users in this group.

• Scope — Select the environment for which you wish to apply this role. For example, if you wish to apply this to All Environments, select All.

With this configuration, when a user in the sample_SAML group signs in through SSO, Traceable assigns the Developer role to the user with the specified scope.

Verify the group mapping

After saving the mapping, have a user who belongs to the mapped IdP group sign in through SSO. Verify that Traceable assigns the expected role and scope. If the role is not assigned as expected, verify the following:

• The SAML Group Attribute Name exactly matches the attribute name in the SAML assertion.

• The SAML Group value exactly matches the group value sent by the IdP.

• The user is assigned to the corresponding group in the IdP.

• The SAML assertion contains the expected group attribute and value.

Troubleshooting

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.