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:

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

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 steps

IdP-initiated SSO

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.

IdP-initiated SSO

For setting this up in Okta, please refer to the below guide:

• Submit a ticket to us through your CSM/TAM or through https://developer.paypal.com/braintree/help. We need your merchant public ID (for example, the yzv4t9j9vjdtk5ym in sandbox.braintreegateway.com/merchants/yzv4t9j9vjdtk5ym/home, but for your BT merchant) and what email domains you want to allow for your SSO users. Once you have your OIN app setup, we will need the SSO Target URL and the SSO cert that are generated for that application, but we will get to that later.
• We will set up a blank callback configuration for you and give you the SSO Callback URL: https://id.sandbox.braintreegateway.com/sso/callback/a0d7409d-f4df-496a-9d12-a6428de79cb0.
• Once we have the SSO configuration set up on our side and have given you the SSO Callback URL, please open your Okta org admin dashboard.
• Select Applications, then browse app catalog. Search braintree, then click add application.
• Follow the prompts to add the application. For BT SSO Partial Callback URI, please use the hash at the end of the SSO Callback URL we provided you in the previous step. So for the above example, use a0d7409d-f4df-496a-9d12-a6428de79cb0. For SCIM Endpoint (don't include https://), if your merchant is in sandbox, please put sandbox.id.braintreegateway.com. If your merchant is in production, use id.braintreegateway.com.
• The next step is configuring the SAML settings in Okta. This may be presented to you automatically in the application setup flow, or you may have to go to the sign-on tab of the created application. For your "Single sign-on URL " and "Audience URI (SP Entity ID)", use the full callback URL provided by us. So for this example, you would use https://id.sandbox.braintreegateway.com/sso/callback/a0d7409d-f4df-496a-9d12-a6428de79cb0. Leave default relay state blank. For Name ID format, please use EmailAddress. For Application username, please use Email. Please use Create and Update for Update application username on. Leave Attribute Statements and Group Attribute Statements blank.
• After you've created the application and saved the above sign-on configurations, navigate to the sign-on page, then click more details. Locate and copy the Sign on URL and the Signing Certificate, and then give those to your BT CSM/TAM/CX agent. We need those to fill in the SSO config on our side.
• Add a user and test if the SSO sign-in works. You should be able to do it both from the Okta SSO page and our own SSO page: https://id.sandbox.braintreegateway.com/sso/sessions/new.

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.