Braintree Single Sign-On (SSO) Integration Guide

Note: This guide assumes familiarity with SAML and SSO. Please refer to https://www.geeksforgeeks.org/computer-networks/introduction-of-single-sign-on-sso/ if you need to brush up on the topics.

Overview

Braintree supports SAML 2.0-based Single Sign-On (SSO), allowing users to log in through your organization's identity provider.

Users are created, edited, suspended, and managed in the Braintree Control Panel
Users log in via your IdP -> No password on our site.
Users suspended in the IdP will be denied access to Braintree but will still appear active in the Control Panel unless manually suspended or deleted
We support SP-Initiated SSO, or when users begin login at Braintree
We also support IdP-Initiated SSO, where users begin login from their IdP dashboard

Required Setup Values

Field	Example	Notes
Merchant ID	`1ab2cdefghij4kl5`	Found in the Control Panel URL after `/merchants/`
Email Domain(s)	`@yourcompany.com`	List all domains used for user login. Any users with an email address NOT listed will NOT be able to login.
SSO HTTP POST Binding URL	`https://idp.example.com/saml2/sso/post`	The SAML callback/POST endpoint from your IdP
X.509 Certificate	`<?xml version="1.0" ... >`	For validating SAML responses

💡 You'll receive the Audience/Callback URL from Braintree once the above details are shared with us and we can setup your SSO configuration on our side. You'll need this for setting up SSO on your IdP.

Optional Values

Field	Example	Notes
Logout Redirect URL	`https://idp.example.com/saml2/sso/logout`	Defaults to your SSO POST Binding URL if not provided

When reaching out to Braintree to enable SSO, please include all of the above values. We cannot onboard you without them.

IdP-Side Configuration Details

These are values you'll need to configure in your IdP’s SAML settings:

Field	Description
Audience Value (Entity ID)	Provided by Braintree
ACS URL (Assertion Consumer Service)	Same as Audience Value
Recipient / Callback URL	Same as Audience Value
NameID Format	`Email/Email address`
NameID Value	User's email address

Step-by-Step Setup (Any IdP)

Submit a request to your CSM/TAM or via Braintree support with:
- Merchant ID
- Email domains
- SSO Certificate (If using Okta, you won't have these until you start the below onboarding section)
- SSO HTTP Post-Binding URL (If using Okta, you won't have these until you start the below onboarding section)
Braintree will respond with your SSO Callback URL (e.g., https://id.sandbox.braintreegateway.com/sso/callback/UUID)

Okta

In Okta:
- Go to Applications → Browse Catalog
- Search and select Braintree
- Add the app and use the UUID from your Callback URL for the "BT SSO Partial Callback URI"
- Set the SCIM endpoint:
  - Sandbox: sandbox.id.braintreegateway.com
  - Production: id.braintreegateway.com
Configure SAML settings:
- Navigate to the `Sign-On` tab
- Click `Edit` in the top right
- Application username format: email
- Update application username on: create and update
- Leave everything else default
- Save
After saving:
- Go to Sign-On → View Setup Instructions
- Copy the Sign-On URL and Signing Certificate
- Send them to your Braintree contact
- We will use these values to update your SSO config on our side. We will also enable SSO for your BT merchant.
Test login via `Post-Configuration Steps`

OneLogin

In the Admin portal, go to Apps → Add App
Search for and select SAML Test Connector (Advanced): https://support.onelogin.com/kb/4266907/saml-custom-connector-advanced
App name: Braintree
Configuration tab:
- ACS URL: Provided by Braintree
- Entity ID: Provided by Braintree
Parameters tab:
- Add parameter email → Map to Email
SSO tab:
- Download metadata or copy the metadata URL
Share metadata and email domain info with Braintree Support
Test login using OneLogin or https://id.braintreegateway.com

Microsoft Entra ID (Azure AD)

Guide from Entra: https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso

In Azure Portal → Enterprise Applications → + New Application
Choose “Integrate any other application you don’t find in the gallery”
App name: Braintree
Under Single Sign-On → Choose SAML
Input configuration:
- Identifier (Entity ID): Provided by Braintree
- Reply URL (ACS): Provided by Braintree
Attributes & Claims:
- email → user.mail
Download Federation Metadata XML
Send metadata and SSO details to Braintree Support
Test login via Azure Dashboard or Braintree SSO URL, details in the section below.

Post-Configuration Steps

Once Braintree confirms setup:

Add an existing Braintree user's corresponding IdP user to the new SSO app you just setup.
On the BT control panel, go to said user's user page (ex: https://sandbox.braintreegateway.com/merchants/yzv4t9j9vjdtk5ym/users/kr3hvmqvqrdt9gs9)
Click `Enable` under `Single Sign-On`. If you do not see a `Single-Sign On` section for the user page, please contact us. We might have forgotten to enable SSO for your merchant on our side.
Wait up to five minutes for the caches to update.
Have the user try to login both via the IdP (a new tile with the app name should now appear in their homepage) and via our SSO login page https://id.sandbox.braintreegateway.com/sso/sessions/new
Once test is complete and working, enable SSO for remaining users via the “Enable SSO” button on each user's detail page. For organizations with many users, Braintree offers a one-time mass SSO enablement option. For this, please reach out to us and give us a csv with the list of users you want SSO-enabled. Please include their email address in the CSV.