SAML SSO Setup Guide

This guide walks through everything needed to configure SAML-based Single Sign-On (SSO) for Tulip, covering both the identity provider (client side) and Admin Console (Tulip side) setup.

Overview#

Tulip supports SAML 2.0 for authenticating app users against an external identity provider. When SSO is configured, Tulip redirects users to the client’s login page. After successful authentication, the identity provider redirects back to Tulip with a signed SAML response containing user information.

Key Terminology#

How It Works#

1. A user opens the Tulip app and is redirected to the IdP’s login page.
2. The user authenticates with the IdP (including any MFA the client has configured).
3. The IdP sends a signed SAML Response back to Tulip’s ACS URL.
4. Tulip validates the response signature using the IdP’s certificate.
5. Tulip matches the NameID in the assertion to a Tulip employee record (by externalId or samlNameId).
6. Tulip converts the SAML session into internal OpenID Connect tokens and logs the user in.

Prerequisites#

Before starting configuration, ensure the following:

• Employee data is loaded into Tulip. Each employee must have an externalId (or samlNameId) that matches the NameID value that will be sent in the SAML assertion. See Employee Data Requirements below.
• Access to Admin Console. You need admin-level access to configure identity providers.
• Access to the client’s IdP admin portal. An admin on the client side must configure the SAML application.
• Test accounts. Request at least two test accounts from the client (one associate, one manager) to validate the setup.

Step 1: Provide SAML Configuration Details to the Client#

The client’s IT team needs the following information to configure their IdP:

Replace <tenant> with the client’s actual Tulip tenant hostname.

If the client has multiple Tulip environments (e.g., staging and production), provide the ACS URL for each environment. The EntityID can remain the same across environments if the IdP supports multiple Reply URLs under one application, or it can differ per environment.

Required SAML Assertion Attributes#

The IdP’s SAML assertion must include the following attributes. Attribute names are case-sensitive.

Attributes beyond NameID are required when Provision Users is enabled (automatic user provisioning). If provisioning is disabled, only NameID is mandatory – but the employee must already exist in Tulip.

Step 2: Client Configures Their Identity Provider#

The client creates a SAML application in their IdP and configures it with the values from Step 1. They then provide Tulip with:

Step 3: Configure the Identity Provider in Admin Console#

Navigate to Admin Console > Integrations > Identity Providers > Create.

Field Reference#

After saving, Tulip’s authentication service (Bouncer) will pick up the new configuration within approximately one minute. The login screen will then show the SSO option.

Employee Data Requirements#

For SAML login to succeed, the NameID in the SAML assertion must match a Tulip employee record. There are two ways this matching works:

Default Behavior (SAML Login For Lookup OFF)#

The NameID from the SAML assertion is matched against the employee’s externalId field. This means whatever value the IdP sends as NameID must exactly match the externalId set on the employee in Tulip.

When loading employees (via TGEN, the Aerial API, or another method), ensure each employee’s externalId is set to the value that will come through as their SAML NameID.

Using the samlNameId Field (SAML Login For Lookup ON)#

If the employee’s externalId needs to remain different from their SAML login identifier (e.g., externalId is an HR system ID while SAML uses email), you can use the samlNameId field to decouple them.

When this is configured, the SAML NameID is matched against the employee’s samlNameId field instead of externalId.

To use this approach:

1. Enable the SAML Login For Lookup toggle on the identity provider in Admin Console.
2. Set the samlNameId field on each employee record to match the value that will come through as their SAML NameID.

The samlNameId Field#

The samlNameId is an optional field on the employee resource. It is available in:

• Aerial API – as the samlNameId property on the employee object. Defined as:

  “If using SSO for authentication against a third party system, set the login username in this field if different than the value set in externalId."

• TGEN – as the samlNameId column in employee import CSV files.

Aerial API example (PATCH an employee to set samlNameId):

PATCH /api/2026-04/storeOps/employees/{id}

{
  "samlNameId": "jane.doe@contoso.com"
}

TGEN CSV example (columns):

externalId,samlNameId,disabled,store,displayName,...
EMP001,jane.doe@contoso.com,false,STORE01,Jane Doe,...

In this example, the employee’s externalId is EMP001 (used by other integrations) while their SAML login identifier is jane.doe@contoso.com.

For new tenants with automatic user provisioning enabled, it is recommended to enable SAML Login For Lookup from the start.

Auth User Setup#

If you are pre-loading employees (not using auto-provisioning), each employee also needs an authUser record. The authUser.username must match the SAML NameID value:

{
  "externalId": "EMP001",
  "samlNameId": "jane.doe@contoso.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "authUser": {
    "username": "jane.doe@contoso.com",
    "password": "placeholder123",
    "disabled": false
  }
}

The password will not be used for SAML authentication but must be a valid value (3+ characters).

Example: Setting Up SAML with Microsoft Entra ID (Azure AD)#

This walkthrough demonstrates how to configure SAML SSO using Microsoft Entra ID as the identity provider.

1. Create an Enterprise Application in Entra ID#

1. Sign in to the Microsoft Entra admin center.
2. Navigate to Identity > Applications > Enterprise applications.
3. Click New application > Create your own application.
4. Enter a name (e.g., “Tulip Retail”) and select Integrate any other application you don’t find in the gallery (Non-gallery).
5. Click Create.

2. Configure SAML Single Sign-On#

1. In the new application, go to Single sign-on and select SAML.
2. In Basic SAML Configuration, click Edit and enter:

If you have multiple environments (staging + production), add each ACS URL as a separate Reply URL under the same application. Each environment will include its ACS URL in the SAML request, and Entra ID will respond to the correct one.

Click Save.

In Azure, if you configure multiple Reply URLs, remove the Login URL field from the SAML configuration, as it can only point to a single tenant and may cause routing issues.

3. Configure User Attributes and Claims#

1. In the SAML configuration page, open Attributes & Claims > Edit.

2. Configure the NameID (Name identifier):

   • Click on the Name identifier value row.
   • Set the Source attribute to the field that matches the employee’s externalId (or samlNameId) in Tulip. Common choices:
     • user.employeeid – if the employee ID is synced to Entra
     • user.mail – if using email as the identifier
     • user.userprincipalname – if using UPN
   • Set the Name identifier format to Persistent.
   • Click Save.

3. If Provision Users is enabled in Tulip, add the following additional claims. Click Add new claim for each:

Make sure claim names are lowercase and match exactly as specified (e.g., first_name, not FirstName).

4. Download the IdP Metadata#

1. In the SAML Certificates section, download the Federation Metadata XML file.
2. From this file, extract:
   • Issuer: The entityID attribute from the EntityDescriptor tag.
   • Login URL: The Location attribute from the SingleSignOnService tag with Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST".
   • Certificate: The content of the X509Certificate tag.

Alternatively, the Login URL, Entra Identifier, and Logout URL are displayed directly on the SAML setup page under Set up Tulip Retail.

5. Assign Users#

1. Go to Users and groups in the Enterprise Application.
2. Click Add user/group.
3. Assign the users or groups that should have access to Tulip.

Only users assigned to the application will be able to authenticate.

6. Configure Tulip Admin Console#

Using the values from Step 4, create the identity provider in Admin Console as described in Step 3:

7. Test the Integration#

1. Ensure the test employee accounts exist in Tulip with externalId (or samlNameId) values matching what Entra ID sends as NameID.
2. Open the Tulip app or navigate to https://<tenant>.tulipretail.com.
3. The login page should redirect to the Microsoft login screen.
4. Log in with a test account.
5. On successful authentication, the user should be redirected back to Tulip and logged in.

Troubleshooting#

“SAMLResponse from unknown identity provider issuer”#

The Issuer (EntityID) in the SAML response does not match the Issuer configured in Admin Console. Verify that the Issuer field in the identity provider settings exactly matches the entityID from the IdP’s metadata.

User authenticates at the IdP but gets an error in Tulip#

• Verify that the NameID value in the SAML assertion matches an employee’s externalId or samlNameId in Tulip.
• Ensure that the employee account is not disabled.
• Check that the verification certificate in Admin Console is correct and not expired.

Shared EntityID across multiple environments#

If the client’s IdP requires unique Entity IDs per application (e.g., Entra ID), but Tulip expects https://tulip.com/, you can use a single IdP application with multiple Reply URLs (ACS URLs). Each Tulip environment sends its own ACS URL in the SAML request, and the IdP responds to the appropriate one.

IdP-initiated login flows will always redirect to the default Reply URL. SP-initiated login (user starts from the Tulip app) is recommended for multi-environment setups.

ForceAuthn and Logout URL#

If ForceAuthn is disabled and no Logout URL is configured, users may remain logged in via cached IdP sessions even after logging out of Tulip. Either keep ForceAuthn enabled or configure a Logout URL for single sign-out.