How to setup SAML SSO integration with TruTrip

TruTrip supports Single Sign-On (SSO) using SAML 2.0. With SAML SSO, your team signs in to TruTrip through your organisation's identity provider (IdP), such as JumpCloud, instead of using a separate TruTrip password.

This article is for IT administrators setting up SAML SSO for their company. It covers what you need before you start, how to configure your identity provider, how to test the connection, and what to do if something goes wrong.

Note: SAML SSO is used for sign-in only. It does not create TruTrip accounts. Each user must already have a TruTrip account, or have been invited to TruTrip, before they can sign in with SSO.

Before you start

Make sure that:

• Your organisation has an active TruTrip company account.
• You have contacted TruTrip Support to request SAML SSO for your company. Our team will help you through the setup.
• Everyone who needs SSO access already has a TruTrip account or has been invited.
• Each user's email address in your identity provider matches their TruTrip account email exactly.
• Your identity provider supports SAML 2.0.
• You have administrator access to create a SAML application in your identity provider.

Step 1: Create the TruTrip application in your identity provider

In your identity provider, create a new SAML 2.0 application for TruTrip and enter the following values.

The SAML response or assertion must be signed. Leave assertion encryption turned off unless TruTrip Support advises otherwise.

Note: The SP Entity ID and ACS URL must match the values above exactly. Even a small difference, such as an extra space or a missing character, will stop sign-in from working.

Step 2: Map user attributes

Include the following user details in the SAML assertion.

For example, for a user called John Doe:

NameID: john.doe@example.com
email: john.doe@example.com
firstName: John
lastName: Doe

Using Microsoft Entra ID (Azure AD)? By default, Entra ID sends the user principal name (UPN) as the NameID, not the email address. If your users' UPNs are different from their email addresses, change the NameID claim to use the user's email address. Also check that your claim names are set to email, firstName and lastName.

Step 3: Send your identity provider details to TruTrip

Once the application is created, send the following details to TruTrip Support:

You can usually find these on your identity provider's SAML application page, often in a section called "SSO information" or "Metadata".

Important: Only send the public X.509 certificate. Never send your identity provider's private key to TruTrip or anyone else.

Step 4: Test with one user

We recommend testing with a single user before rolling SAML SSO out to your whole company. Choose an existing user who already has an account in both TruTrip and your identity provider, with the same email address in both. You do not need to create a new test user.

1. Choose your test user. Pick someone who already has a TruTrip account and an account in your identity provider, and check that the email address is exactly the same in both.
2. Assign the TruTrip application to that user in your identity provider.
3. Sign in. Ask the user to open your identity provider's user portal and select the TruTrip application.
4. Confirm it worked. The user should land on the TruTrip homepage without being asked for a TruTrip password.

Once the test succeeds, assign the TruTrip application to the rest of your users or user groups.

How users sign in

Users sign in by opening the TruTrip application from their identity provider's portal (for example, the JumpCloud User Portal). They are then signed in to TruTrip automatically.

Note: Starting SAML SSO sign-in from the TruTrip sign-in page is not currently available. Users should always start from your identity provider.

If SAML SSO is set as your company's required sign-in method, users sign in through your identity provider only and do not need a separate TruTrip password.

What stays managed in TruTrip

SAML SSO confirms who the user is. It does not change what they can do in TruTrip. The following remain managed in TruTrip and are never set by your identity provider:

• Company membership
• User roles and permissions
• Billing access
• Travel policies
• Approval permissions

Before signing anyone in, TruTrip checks that the SAML response is genuine, comes from your configured identity provider, and belongs to an existing user in your company.

Troubleshooting

The user signs in to the identity provider, but TruTrip sign-in does not complete

Check that the user already has a TruTrip account or has been invited. SAML SSO does not create new TruTrip users.

The user's email does not match

TruTrip treats different email addresses as different users. For example, john@example.com in your identity provider and john.doe@example.com in TruTrip will not match. Make sure the email sent by your identity provider is exactly the same as the TruTrip account email. If you use Microsoft Entra ID, see the note in Step 2 about the NameID.

The user cannot see the TruTrip application

Check that the user, or a group they belong to, is assigned to the TruTrip application in your identity provider.

Sign-in fails with a configuration error

Check that the ACS URL and SP Entity ID in your identity provider exactly match the values in Step 1.

Sign-in fails with a signature error

The certificate TruTrip has on file may not match the one your identity provider is currently using. This often happens after a certificate has expired or been replaced. Contact TruTrip Support to update it.

Changing your signing certificate

SAML signing certificates expire and need to be replaced from time to time. Before you switch to a new certificate in your identity provider, send the new public X.509 certificate to TruTrip Support. This lets us update your configuration and keep sign-in disruption to a minimum.

Important: Never send your identity provider's private key.

Turning off SAML SSO

Contact TruTrip Support before you remove or disable the TruTrip application in your identity provider. If SAML SSO is your company's required sign-in method, we will first switch your company to another sign-in method so your users do not lose access to TruTrip.

Contacting TruTrip Support about a sign-in issue

To help us resolve the issue quickly, please include:

• Your company name
• The affected user's email address
• Your identity provider (for example, JumpCloud or Microsoft Entra ID)
• The approximate time of the sign-in attempt
• Any error message the user saw (a screenshot is helpful)

Please do not send passwords, private keys, access tokens, session data, or any other sign-in secrets.

Go-live checklist

Before rolling out SAML SSO to your users, confirm that:

• The TruTrip SAML application has been created in your identity provider.
• The SP Entity ID and ACS URL match the values in Step 1 exactly.
• The NameID is the user's email address, using the email address NameID format.
• The email, firstName and lastName attributes are mapped.
• The SAML response or assertion is signed using RSA-SHA256.
• Your IdP Entity ID, SSO URL and public certificate have been sent to TruTrip Support.
• Your chosen test user has signed in successfully from your identity provider.
• All users who need access have a TruTrip account with a matching email and are assigned to the TruTrip application.