Braintree Single Sign-On (SSO) Integration Guide

What is SSO? What is SAML? How does this all work? 

Single Sign-On (SSO) is a technology that allows users to access multiple applications with a single login. Instead of entering credentials for each individual app, users authenticate once and gain seamless access to all their assigned SaaS applications. SSO is sort of like a bar. In a bar, customers only show ID once to order drinks, instead of re-verifying for each round. Similarly, with SSO, users verify their identity once and then gain access to multiple services without repeated logins.

The basic steps of a SSO/SAML Login flow are as such: 

1. User attempts to access a service (like Salesforce).

2. The service provider redirects the user to the identity provider (like Okta, Entra, OneLogin etc.).

3. The identity provider authenticates the user (usually with credentials or MFA).

4. Upon successful login, the identity provider generates a SAML assertion (an XML-based document).

5. The SAML assertion is passed back to the service provider, verifying that the user is authenticated.

6. The service provider grants access to the user without requiring a separate login.

What does SSO/SAML at Braintree look like? 

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's site via https://id.braintreegateway.com/sso/sessions/new in production or https://id.sandbox.braintreegateway.com/sso/sessions/new in sandbox. 

• We also support IdP-Initiated SSO, where users begin login from their IdP dashboard. 

Required Setup Values

Optional Values

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:

Step-by-Step Setup (Any IdP)

1. 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)

2. Fill out our SSO onboarding form. This will allow us to better serve you and make your onboarding easier and more efficient. 

3. Braintree will respond with your SSO Callback URL (e.g., https://id.sandbox.braintreegateway.com/sso/callback/UUID)

Okta 

1. 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: id.sandbox.braintreegateway.com

     • Production: id.braintreegateway.com

2. 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

3. 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. 

4. Test login via `Post-Configuration Steps` 

   ---

OneLogin 

1. In OneLogin:

   • Log into the OneLogin Admin Portal.

   • Navigate to Apps → Add App.

   • Select the “SAML Test Connector (IdP)” app.

   • Give the app a display name like “Braintree Dashboard”.

2. Configure the App in OneLogin

   • Open OneLogin's Configuration tab for the new app.Click `Edit` in the top right

   • Retrieve the SSO Callback URL given to you by BT Support. 

   • Paste the Braintree SSO Callback URL into the ACS (Consumer) URL, Recipient, Audience, and ACS (Consumer) URL Validator fields in OneLogin. 

   • Save

3. 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. 

4. Test login via `Post-Configuration Steps`

Microsoft Entra ID (Azure AD)

1. Add Braintree as an Enterprise App:

   • Sign into the Microsoft Entra admin center.Navigate to Apps → Add App.

   • Go to Entra ID → Enterprise apps → All applications.

   • Click New application → Create your own application.

   • Name the app, for example “Braintree SSO”, select “Integrate any other application…” (Non‑gallery), and click Create

2. Configure SAML‑SSO in Entra ID

   • Navigate to the newly created Braintree app, then open Single sign-on and select SAML.

   • Click the pencil icon in the Basic SAML configuration section and enter the BT SSO Callback URL you should've recieved from BT support, into the Identifier (Entity ID), Reply URL (ACS URL), and Sign-on URL fields and save. 

   • Save the configuration once complete.

3. Obtain Certificate & Metadata:

   • From the same SAML pane, scroll to the SAML Certificates section.

   • Download either the Raw or Base64 certificate file—this is needed by Braintree.

   • Also copy the App Federation Metadata URL.

   • Send both values to BT support.

   • We will use these values to update your SSO config on our side. We will also enable SSO for your BT merchant. 

4. Test login via `Post-Configuration Steps`

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 Braintree control panel, go to user's 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. 

• If you are looking to onboard to SCIM, please ensure you convert all the non-SSO users you want to use SSO first, before attempting to onboard to SCIM. Once you are on SCIM, you will no longer be able to convert non-SSO users to SSO. Please refer to our SCIM FAQ for further details, specifically the "Now that I'm on SCIM, I'm not able to create new SSO users or edit existing ones. What gives?" section.  

• Once you do the above, please refer to the same SCIM FAQ for further information about our SCIM integration. If you desire to onboard, please refer to our onboarding guide