---
title: "SAML Configuration"
slug: "saml-configuration"
updated: 2025-04-04T09:35:08Z
published: 2025-04-04T09:35:08Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 (like Developer or Account Owner).

---

## Quick Flow Overview

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

```plaintext
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:

- [Set Up SAML Group Mapping with Okta](/docs/set-up-saml-group-mapping-with-okta)
- [Set Up SAML Group Mapping with Azure AD (Entra ID)](/docs/set-up-saml-group-mapping-with-azure-ad)
- [Set Up SAML Group Mapping with OneLogin](/docs/set-up-saml-group-mapping-with-onelogin)

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:

```plaintext
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