What is SCIM

What is SCIM?

SCIM, or the System for Cross-domain Identity Management specification, is an open standard for managing user identity information. SCIM provides a defined schema for representing users and groups and a RESTful API to run CRUD operations on those user and group resources. Essentially, SCIM helps you (the merchant) to use the IdP (Identity Providers) of your choice to manage your users across multiple integrations, whether BT or a different company.

Why SCIM?

We have many merchants. You have many users — hundreds, if not thousands — all of whom need to be onboarded, offboarded, modified, or suspended. You'll need to do this quickly, easily, and in as few operations as possible. Doing this across multiple integrations (such as BT + others) is a pain. So why not do it all in one place? With SCIM, merchants (for example, you) will be able to fully control the provisioning and de-provisioning of users and groups (roles, merchant accounts, grant all merchant accounts) from your own IdPs (Okta, OneLogin, Entra, and so on). This is a huge boon for larger merchants who have a massive amount of users interacting with the Braintree system. With SCIM, instead of removing users one by one from a role, you can now remove all of them from the role with one operation. Likewise, you can onboard users in bulk, offboard users in bulk, and modify permissions in bulk. It seems much simpler, doesn't it?

How does SCIM work?

Essentially, when we set up SCIM for you, we do some data setup on our side, and then we give you an access token for your IDP to interact with us. Consider this similar to an API key or password that helps their service make requests that modify your users or groups on your behalf. After you give that access token to your IdP of choice, we sync up our user data. So, your IDP of choice has the same user data/state as we do. After that's in place, any time you want to make a change to your users, you just make that change in your IdP, and then your IdP will send us the necessary requests to keep our data and their data in sync. For example, if you remove a few users from being able to access a merchant account, your IdP will send us a request to remove those users' access to that merchant account. This way, we keep in sync and everyone's happy. The best part about all this is that we and the IdPs all use an industry-standard protocol, so we all stay on the same page. If you're interested, you can read more about it here: RFC 7644: System for Cross-domain Identity Management: Protocol Something to note with this is that after you onboard to SCIM with us, you can't go off. It's a one-way street. In addition, after you're on SCIM, you won't be able to edit/create/delete SSO users on the BT control panel. This is to keep us and your IdP in sync. For your non-SSO users, they will stay non-SSO and will still be managed using the BT control panel (and only the BT control panel). Only SSO users can be SCIM users.

Troubleshooting and FAQs

When I set up the push groups, the role/merchant account is empty after I link the Okta group as a push group.

When setting up the push groups, it is important to first populate the Okta group with the members who require access. You should link it to the imported app group as a push group only after this. After you link the Okta group, the membership will be updated immediately. Be cautious: linking an empty Okta group to an app group, such as the Account Admin Role group, automatically removes all members from the account admin role.

When I push my group membership, I get a “One or More Member IDs do not exist" error.

Okta is attempting to add a user to the SCIM group that does not exist on the Braintree side. Verify that all users in the SCIM group have corresponding entries on Braintree. This issue should not typically arise during the normal operation of your integration. If you encounter this error, contact Braintree support for assistance.

Whenever there are user login errors or issues, there is a general diagnosis guide you need to follow before reaching out to BT Support.
- Is the user active on the Braintree side?
  1. If a user is suspended, they cannot log in. To resolve this, remove the user from the Braintree application and re-add them. This process will initiate a notification to suspend the user and activate them.
  2. If a user's status is pending, it means they have not yet activated their BT account. This situation is likely because the user's BT account has just been created and this is the first time their specific email has been added to the BT app through Okta. To resolve this, instruct the user to log in through the Okta app widget. After logging in, they should be redirected to an activation flow page on the Braintree website. If the activation page does not appear, remove the user from the app and then re-add them. This process will suspend and then unsuspend them.
- Does the user have any roles?
  - We require all users, whether SSO/SCIM or non-SSO, to have at least one role in order to log in. As such, check to see that your user has at least one role assigned to them on the Braintree control panel. If they do not have one, they will not be able to log in.
- Are other Okta users able to log in?
  - If none of your users can log in, it could be due to a misconfiguration of your SSO metadata on our side. If this is the case, Contact Braintree Support to resolve this. Send us your Sign-on URL, your Sign-out URL, and your signing certificate. These can be found on your Okta page at Application → Sign-On → more details.
  - If the SSO configuration is set up correctly, it could be that you are using a custom regex for the login matching in Okta. Please go to Application → Sign-on → Advanced Sign-on Settings. Please ensure that under Credential Details, your Application username format is set to Email and not Username or some sort of custom regex.

I changed an Okta user's email/username, and now it fails to provision to the application.

Check to ensure the Okta user's username and email are the same. If they are out of sync, it will cause problems with provisioning and log in.

I changed the email or username of an Okta user, and when the user logged into Braintree, they were logged into a new account, while the user with the old email was suspended. What happened?

Because SCIM operates by using matching based on email, we’ve decided to use the email address as the unique identifier for SSO/SAML. Consequently, when you change the email or username of your Okta user, our system will create a new user with the updated email address rather than editing the existing user. Additionally, this will result in the suspension of the old BT user associated with the previous email address.

When I change a group's name on my IdP, the role/merchant account name does not change on PayPal Braintree. How does updating a group's name work with SCIM on Okta/Entra/OneLogin?

When you want to update the name of a role or merchant account, update the group's name on the SCIM IdP first and then update the name of the role/merchant account separately on the BT control panel. This is because the SCIM group that manages the membership of a role or merchant account is actually a separate entity from the actual role or merchant account itself. As such, when you update the group name on Okta/OneLogin/Entra, you ARE updating the display_name of that SCIM group in our system, but because they are separate entities, it will not update the name of the associated role/merchant account. In order to do so, you'll need to go to that role/merchant account's show page and update the name independently. Likewise, if you change the name of a role or merchant account on our UI, it will NOT change the name of the group associated with that role or merchant account on your SCIM IdP. You would need to go make that change separately. Note: You cannot change the name of admin roles.

When I DELETE an Okta user, it does not delete the BT user; it’s left as suspended.

Okta will never send us a call to DELETE a BT user due to their design decisions on implementing SCIM: SCIM 2.0 Protocol Reference. This is not true for IdP/SCIM providers, such as OneLogin or Microsoft Entra. Because they will never send us a call to delete users, we cannot delete the users on our end. Currently, you can suspend BT users by removing them from the Okta BT application; however, you cannot permanently delete them from BT unless you disable Okta. For further assistance, Contact Okta Support or reach out to BT Support if you want to switch to a different Identity Provider (IdP), such as OneLogin or Entra.

When I do a user import or group membership update, it fails with a generic error or mentions a timeout.

Sometimes, Okta or Braintree may take longer than expected to process a request or could be overwhelmed. This is not typical and should not happen 99% of the time, but issues can arise. If you encounter a delay, try resubmitting the request. Additionally, the Okta user interface can sometimes be finicky. In such cases, do a hard refresh of the page and wait a few minutes before trying the request again.

Why can't I add new roles or merchant accounts from the Okta page?

Due to the limitations of the SCIM API RFC, it is currently not feasible to provide the necessary context for Okta to understand the definitions of Roles and Merchant Accounts in relation to Braintree. Because of this lack of context, we do not allow Identity Providers (IdPs) to edit, add, or remove groups within the Braintree application. If you need to make changes to existing Roles or Merchant Accounts, continue to do so through the Braintree Control Panel, just as you did before onboarding to SCIM.

Why can't I use push groups to manage user membership in the Braintree application?

Check Okta's Troubleshooting Group Push for an explanation, but you MUST use a separate group in Okta to manage user membership to the Braintree application. If the correct user assignment process isn't followed, it can lead to users being locked out of Braintree or granted excessive privileges due to a design flaw in Okta. When a user is assigned to the Braintree application through a push group, removing them from that group will only trigger a suspend user action, not a removal from the group. If you later assign the Braintree application directly to the user, it may be reactivated, although it will still appear as if the user lacks group access in the Okta UI.