Overview

This guide provides step-by-step instructions on how to add the Braintree SCIM (System for Cross-domain Identity Management) app from the Okta Integration Network (OIN) marketplace to your Okta organization. The Braintree app enables automated user provisioning, de-provisioning, and user role and merchant account access management through Okta.

If you are looking to integrate via SCIM with Braintree using Entra, OneLogin, or another IdP solution, we are currently working on guides for these options. For now, please refer to the IdP's own guide on creating a custom SCIM app/integration.

Prerequisites and requirements

Before starting, ensure that:

1. You have administrative access to your Okta organization.
2. You are already an SSO merchant with Braintree with Okta as your IdP. If you are not, refer to this guide to onboard to SSO. 
3. All of the existing users you want to use SSO are already SSO enabled. Please refer to our SCIM FAQ, specifically the "Now that I'm on SCIM, I'm not able to create new SSO users or edit existing ones. What gives?" point for further details, but you will NOT be able to convert existing non-SSO users to SSO once you are onboarded to SCIM. 
4. You have both a production and sandbox merchant with us. If you do not have a sandbox merchant, please create one via https://apply.braintreegateway.com/signup/sandbox and send us the merchant public id. A sandbox merchant is REQUIRED for us to onboard you to SCIM, as we do not allow onboarding to SCIM in production without said sandbox merchant being onboarded first. 

Supported Features

Braintree's SCIM integration supports User Create, Get, Update, and Delete. We also support Group Update. We do not support creating or deleting groups for roles and merchant accounts through SCIM. Roles and merchant accounts themselves must continue to be managed through the BT website. 

Setup and configuration steps

Reach out to Braintree support

• To begin with, reach out to Braintree support and ask to be onboarded to SCIM on Braintree.
  • The Braintree Identity team will need to run some internal tasks to get your merchant account ready for the SCIM integration with Okta.
  • When we do this, we will disable your ability to edit SSO users on the control panel to ensure data consistency.
  • We will also provide you with a SCIM access token with Okta. This is what is used by Okta to access your Braintree merchant account and take actions upon it on your behalf.

• Please fill out our SCIM/SSO onboarding form. This will allow us to be more efficient in your onboarding and make it easier for both parties. 

Accessing the Okta Admin Console

• Log in to your Okta Admin Console

Adding the SCIM app

1. Navigate to the Applications Section:
   • In the left-hand menu, select Applications, then select Applications again.
2. Open the Okta Integration Network (OIN):
   • Select Browse App Catalog.
3. Search for the SCIM app:
   • Use the search bar to find the Braintree app.
4. Select and add the app:
   • Select the Braintree app from the search results.
   • Select the Add button to start the integration process.
5. Configure general settings:
   • Follow the prompts to configure the basic settings for the app. This is when you'll input your SSO callback and Audience URL to the application so it knows how to connect.
   • For Partial Callback URL, this comes from your SSO configuration. Please ask the Braintree team for this value.
   • For SCIM Endpoint, for sandbox, please use id.sandbox.braintreegateway.com. For production, please use id.braintreegateway.com.
   • Select Done after you have completed the configuration.

6. Note: If you are already using Okta for SSO with an existing custom app, you'll have to do a cutover of the SSO target from the old app to this new OIN app instance. Please send us the new OIN app's cert, SSO target url, and the timeframe by which you want us to do the cutover and then we can change, on our side, which app we expect users to use to login. You will need to assign all of your existing users to the new OIN app before we do the cutover, or else they won't be able to login. 

Configuring SCIM Integration

1. Open the SCIM App Settings:
   • After adding the app, go back to Applications > Applications.
   • Select the SCIM app you just added to open its settings.
2. Access the Provisioning Tab:
   • Select the Provisioning tab.
3. Configure API Integration:
   • Select Configure API Integration.
   • Check the box labeled Enable API Integration.
   • Enter the required SCIM API credentials:
   • Base URL: The SCIM endpoint URL provided by your application.
     For sandbox, this value is: https://id.sandbox.braintreegateway.com/scim.
     For production, this value is: https://id.braintreegateway.com/scim.
   • OAuth Bearer Token: The token used to authenticate API requests. This is the token you should've received from Braintree.
4. Test API Credentials:
   • Select Test API Credentials to verify the connection to your application.
   • If the test is successful, select Save.

Defining Provisioning Settings

1. Enable Provisioning Features:
   • In the Provisioning tab, then the To App tab, enable the necessary provisioning features by checking the relevant boxes:
   • Create Users: Automatically creates users in Braintree.
   • Update User Attributes: Automatically updates user information in Braintree.
   • Deactivate Users: Automatically deactivates users in Braintree.
   • Sync Password: You do not need to sync passwords.
2. Map Attributes:
   • Select To Okta to configure attribute mappings between Okta and your application.
   • Ensure the mappings match the sample. You can also leave it as the defaults:
   • 

Running the User Import

1. Manual User Import:
   • After setting up the application and the SCIM connection, you must run the user import to automatically set up the Braintree users and their roles in Okta.
   • Open the Import tab.
   • Select Import Now.
2. Review Import Results:
   • After the import is completed, review the results.
   • You likely will have users you need to confirm before Okta will create them automatically from the Braintree data it just imported. These users will show up on the import page as unconfirmed users. Please review the data and confirm the users. You can refer to the following Matching and Confirming Users section below on how to do this.
   • Select View Logs to check for errors or issues during the import process.
   • Go to the People section to see the newly imported users and their profiles.

3. Note: Pending users (i.e, SSO users that have been created in Braintree but have not logged in yet) do not have a name. As such, when you try to import them to Okta, it will fail due to the users having a lack of a name. The workaround is to manually create these users on Okta (or use the existing user on Okta), then assign those users manually to the new OIN app we created. This will cause Okta to send us a call to update the name on our side. 

Matching and Confirming Users

1. Matching Users:
   • Okta will attempt to match imported users with existing Okta users based on attributes such as email address or username.
   • Review the matched users to ensure they are correctly identified.
2. Confirming Users:
   • Confirm the new users to finalize the import.
   • For unmatched users, decide whether to create new Okta user accounts or ignore them.

Assigning push groups to the app groups

• After the import, the app groups in Okta will be automatically created, and users will be assigned to them.
• To push changes to these users' groups in Braintree, set each group as a push group.
• Refer to push group and enable group push section.
• You should also setup a master Okta group to manage which users are assigned to Braintree. Please create a new Okta group and assign it to the Braintree app. Then, assign all users you want to have access to Braintree to this group. You cannot use push groups as a way to manage users' overall access to Braintree. This can lead to bad edge cases. Please refer to the below troubleshooting guide for more information.

Assigning Users to the App post-import

1. Create the user in Okta.
2. Navigate to the Groups Tab:
   • Select the master Braintree user group we created in the previous step.
3. Assign Users or Groups:
   • Select Assign > Assign to People.
   • Select the user you want to provision to the application.
   • Select Assign and then Done to complete the assignment.
   • Braintree users require at least one role to log in to Braintree, so you'll want to assign this user to a push group as well.
   • Follow the above steps for adding to the master group, but for one of the push groups we set up above.
   • If your push groups are set up to push synchronously, it will push this change automatically to Braintree.
   • If your push groups are async, you'll need to manually push the group changes by going to the Push Groups tab on the Application page.

Testing Provisioning

1. Verify User Creation:
   • Assign a test user to the application and check if the user is created in Braintree.
2. Verify Attribute Updates:
   • Update the test user's group membership in Okta and ensure the changes are reflected in Braintree.
3. Verify User Deactivation:
   • Deactivate the test user in Okta and confirm that the user is suspended in Braintree.

Monitoring and Troubleshooting

1. Check Provisioning Logs:
   • In the SCIM app settings, go to the Provisioning tab.
   • Select View Logs to see the provisioning logs and check for errors or issues.
2. Review SCIM Events:
   • Go to Reports > System Log to review SCIM-related events.
3. Resolve Issues:
   • If any errors occur, consult the logs and verify that SCIM endpoint details and attribute mappings are correctly configured and that you are getting a successful response from Braintree. The Okta user's username MUST match the email.
   • If you cannot resolve the issue, contact Okta support.

For more information, check out our FAQ

Conclusion

You can add and configure the pre-made SCIM Braintree app from the Okta marketplace, enabling automated user provisioning and de-provisioning for your organization. For more detailed information or advanced configurations, please refer to the Okta documentation.