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.

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 Braintree Support Articles.

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 through SCIM.

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.

Accessing the Okta Admin Console

• Log in to your Okta Admin Console:
  • Open a web browser and navigate to https://your-org.okta.com/admin.

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.

Configuring SCIM Integration

Note: This step may not be necessary once the App is approved for the marketplace

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 deactivate users in Braintree.
     • Sync Password: You do not need to sync passwords.
2. Map Attributes:
   • Select To App to configure attribute mappings between Okta and your application.
   • Ensure the mappings match the sample:

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.

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. PLEASE BE SURE TO ASSIGN THE USERS TO THE OKTA GROUPS FIRST BEFORE LINKING THEM TO THE APP GROUPS AS A PUSH GROUP OR ELSE IT WILL EMPTY OUT YOUR ROLES. Refer to the below troubleshooting guide for more information.

• 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 using Add users manually.
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 atleast one role to login 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 setup 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.