Single Sign-On (SSO)

important
This guide requires familiarity with single sign-on and SAML. Please ensure someone experienced with setting up service providers is involved in reviewing this content.

You can use Single Sign-On (SSO) to access Braintree. You must use a SAML 2.0 compliant identity provider (IdP) in order to use SSO with Braintree.

Overview

Braintree supports a standard SAML-based login experience.

Users are managed (created, updated, suspended, deleted) from the Braintree Control Panel
Users log in from your IdP
Users suspended in your IdP will not be able to log in to the Braintree Control Panel but will continue to display as active in the interface until they are deleted or suspended in the Braintree Control Panel

Required values

We require the following values in order to configure your setup:

Information needed	Example Value	Notes
Merchant ID	1ab2cdefghij4kl5	This can be found when logged into the Braintree Control Panel as the 16-digit string of letters and numbers following /merchants/ in the URL
Email domain(s) to be used in user IDs	@yourcompany.com	Please provide all domains to be added to your SSO configuration’s allowed list
Single Sign-On HTTP POST Binding URL	https://idpservice.example.com/saml2/sso/post	The HTTP-POST URL for SAML 2.0 callbacks
Certificate for validation	<?xml version="1.0" encoding="UTF-8"?>...</>	The X.509 certificate you use to sign your SAML 2.0 responses

At a minimum, we require the merchant public ID and email domain(s) in order to provide you with the Audience Value / Entity ID and ACS URL needed on your end. Please note, we use the user’s email for the Name ID value.

note

We recommend not enabling SSO for some privileged users; this will allow those users to access the Braintree Control Panel via standard login in the event your IdP experiences an outage.

Additionally, we always recommend testing in a sandbox gateway before configuring SSO in production.

Optional values

Information needed	Example Value	Notes
Logout redirect URL	https://idpservice.example.com/saml2/sso/logout	This value defaults to the Single Sign-On HTTP POST Binding URL

Request template

Copy, paste, and fill out the example values in italics with your own information in your response to us for each gateway you want SSO enabled:

Sandbox
- Merchant ID: 1ab2cdefghij4kl5
- Email domain(s) to be used in user IDs: @yourcompany.com
- Single Sign-On HTTP POST Binding URL: https://idpservice.example.com/saml2/sso/post
- Certificate for validating SAML response: provide SAML metadata or attach cert
Production
- Merchant ID: 1ab2cdefghij4kl5
- Email domain(s) to be used in user IDs: @yourcompany.com
- Single Sign-On HTTP POST Binding URL: https://idpservice.example.com/saml2/sso/post
- Certificate for validating SAML response: provide SAML metadata or attach cert

Configuration within your IdP

We've provided the following fields as examples of values you might need based on your IdP. At a minimum you must use the ACS URL in your configuration.

The Audience Value (or Entity ID) field with the Conditions element of SAML assertion to tell under which security conditions or context the assertion is valid. Braintree will provide this value to you after you provide the above configuration values.
The Recipient field is associated with the Subject element of the SAML assertion. It must be set to the ACS URL, which we will provide you.
The ACS (Assertion Consumer Service) URL is the Service Provider endpoint that accepts SAML Response and validates at that point whether the user is authorized. As stated above, Braintree will provide this value.
The ACS URL Validator field above should be a regular expression to validate the ACS URL. It can remain as the same value as that of the ACS URL.

Post-configuration next steps

Once Braintree has accepted your configuration, you are free to complete the following setup from within your IdP and gateway:

Enable SSO login for an existing test user in your sandbox gateway. You can create a new sandbox if you don't have one.
Confirm you are able to successfully login with that user via your IdP or from https://id.sandbox.braintreegateway.com for sandbox and https://id.braintreegateway.com for production
Confirm that role and merchant account provisioning works as expected
Enable SSO for your remaining gateway users once you've successfully validated a test user's login in production. The “Enable SSO” button is located on each user’s individual detail page.

note
We can provide a one-time backfill enablement for gateways with a large number of existing users.