System for Cross-domain Identity Management (SCIM) can be set up to connect your Identify Provider (IdP) with your Ramp account. SCIM allows you to invite and terminate Ramp users directly from your IdP. We currently support the SCIM integration for Okta only.
This article explains how to set up the integration from your Ramp account, configure your SCIM settings within the Ramp app, and what to expect when using the SCIM integration to invite and terminate users.
We've called out many suggestions and "things you should know" for using the integration so we strongly recommend you read this before setting up your SCIM integration!
Set up the integration on Ramp (Start here!)
Before you begin
Determine which profile field you want to use for the user's department in Ramp. By default this is set to "department" but you can map to any profile field in Okta. Other common options are "Cost Center", "Organization", or "Division".
Determine which profile field you want to use for the user's location in Ramp. By default this is set to "city" but you can map to any profile field in Okta. Other common options are "Cost Center", "Locale", "State", "Country Code".
Audit your users in Okta to ensure there is a department AND location set for each user. Any user who does not have one of these values will not be provisioned in Ramp.
"Groups" in Okta can make it easier to manage user assignments. If you choose to use Okta groups, please fully review the "Inviting user groups" section below.
If you already have users on your Ramp account:
- Confirm that the employee profile information in Ramp matches the data in your IdP. When you provision a user via SCIM and they already exist in Ramp, the IdP becomes the source of truth and will override the user's Ramp profile if it doesn't match.
- If a user's email address doesn't match, SCIM will use the Okta email address to create a second account for the user
If you are disconnecting from HRIS to set up SCIM
- Please ensure that the HRIS fields that you use for Department and Location are synced to your IdP (Okta). If you disconnect HRIS, and the data does not match your IdP, the SCIM integration will override the employee profile information on Ramp. (Reminder that you can map to any IdP field you'd like.)
- We recommend contacting your Ramp partner for support
(Later) Once you have the integration set up, before you terminate anyone via SCIM, you’ll want to determine your preferred options for handling user deletion in regards to how Ramp will handle their cards and status in approval chains. (See Terminations section below)
- Go to: Settings > Integrations > User Management
- Select SCIM
- Note: You cannot integrate with both SCIM and HRIS at the same time. If you are connected to HRIS, you will need to disconnect the HRIS integration in order to set up SCIM.
- Select your identity provider (currently supporting Okta only)
- When you select your provider, you will be prompted with instructions on how to set up the integration with your IdP. These instructions vary by provider and will guide you through setup.
- Okta instructions can also be found here.
- Once you complete setup, you’ll land on the SCIM integration page where you can view and configure your SCIM settings.
Onboarding and offboarding with SCIM
SCIM settings page
The SCIM Settings page is your Ramp control center for SCIM. Here you can:
- View the last sync time.
- This is the last time we received a SCIM update from your IdP. We recommend checking this timestamp if you think that there’s an issue with your connection.
- See number of users invited and terminated via SCIM
- Configure your offboarding options (See Terminations section below)
- View integration information in case you need to reconnect at some point
- “Disconnect” the integration.
- Disconnecting will prevent any future data syncing. To fully disconnect, go to your IdP and follow the steps to delete the SCIM integration.
When you connect to your IdP (Okta) via SCIM, you will be able to automatically invite users to Ramp from your IdP.
Ramp requires the following information to send the invite:
- First Name
- Last Name
- Email address
If a user has a manager assigned to them in your IdP, you can push that information to Ramp as well, and we recommend doing so. (This is configurable from Okta)
Note that if you invite a user with a manager who has not been invited to Ramp yet, we will not be able to assign the manager until the manager has been invited to Ramp.
In order to successfully send a user invite via SCIM, the required fields must be populated in your IdP, otherwise the invite will not be sent. If the user is missing any required fields the request will fail. You can track errors/unsent invites in Okta.
Note that you can map any Okta field to the Ramp attributes; the recommended fields are pre-populated in Okta, but you can change them.
Ramp invites are sent to users via email. The invite email “sender” is set to the user’s manager. If the user doesn’t have a manager, then it falls back to the Ramp account owner. In other words, new users provisioned via SCIM will receive an invite email from their manager, if they don’t have a manager, then it will come from the Ramp account owner.
If you also have SSO/SAML set up, your users can access Ramp using SSO and don't need to accept the invite via email.
Inviting user groups in Okta
You have the option to invite users as individuals or as part of user groups from your Okta account.
It is common to have workflows in Okta that automatically add or remove a user to/from a group based on certain criteria. If a user is (automatically or manually) moved from a group where they are assigned to Ramp, they will be immediately terminated from Ramp. This applies even if they are added to a new group that's also assigned to Ramp; Okta treats this as two separate actions, which results in the user being terminated and then recreated with a new user account.
Due to this, we recommend you assign users to Ramp using a group that is manually managed rather than managed through automations and workflows. If you do need to move users between groups, we recommend adding the user to the new group BEFORE removing them from any other groups, OR temporary disabling "de-provisioning" from the SCIM settings while you make group changes. This will ensure they stay provisioned to Ramp and do not accidentally get terminated.
When you assign the Ramp app to a group, Okta will prompt you to set a department for the entire group. You can choose to assign the department at the group level, but if you prefer to use the department that's set on the individuals' profiles, you will need to update one of your configuration settings to do so. To disable this in Okta:
- Go to: Applications -> Applications -> Ramp -> Provisioning
- Under "Ramp Attribute Mappings" click the "Go to Profile Editor" button
- Click the pencil next to "Department" to edit this attribute
- Uncheck the "Attribute required" checkbox and save
Now, when you assign a group it will still ask you for a department for the entire group but you can leave it blank and the users in the group will be invited to Ramp from the department value that's saved to their profile.
User setup in Ramp
If a user is assigned as someone’s manager in your IdP when they're invited, then we will automatically assign them the Manager role on Ramp, otherwise, all users invited via SCIM will be assigned the Employee role. You can update a user’s role from your Ramp account after they accept their invite.
IT admins and Bookkeepers on Ramp cannot act as Managers. When you try to provision or update a user whose manager is an IT admin or Bookkeeper, you will receive an error and the attempt to provision or update will fail.
When a user is invited via SCIM, we will issue any default Spend Programs that you’ve configured for your business.
When a user is de-provisioned from your IdP, we will automatically terminate them from your Ramp account. There are a couple of configurable options to handle user cards and approver responsibilities when terminating a user. Note: Ramp account business owners cannot be terminated via SCIM.
When a user is terminated:
- Their physical cards are always terminated
- Virtual cards can be reassigned or terminated (depending on your configurations, see below)
- Approved reimbursements will be paid out
- Unapproved reimbursements will be deleted
- Their transaction history is still available
- They cannot be reactivated. ie: If you re-invite the user, it creates a completely new Ramp account for them, with no historical data associated with the new account.
Handling Cards when Auto-Terminating
When a user is automatically terminated from Ramp, they may have active cards that need to be reassigned to another user in case their cards are being used for important spend. The following options are available for handling virtual cards that belong to an employee being auto-terminated:
- Terminate all cards (default setting)
- Automatically reassign all virtual cards to a selected Ramp user
- Automatically reassign all virtual cards to manager (if the user doesn’t have a manager, it will fall back to the business owner)
Note: Physical cards cannot be reassigned and will always be terminated when the user is terminated.
For card reassignment, we recommend automatically terminating all cards to prevent unwanted spend. We suggest that you handle card reassignments before terminating a user from your IdP, so that if there is any critical spend that you don’t want to disrupt, you can reassign the card before it gets terminated.
Handling Approvals when Auto-Terminating
When a user is automatically terminated from Ramp, they may also be active in one or more approval flows. In this case, we offer two options for automatically replacing the user in approval chains. This is mandatory, as a missing approver may prevent other employees from spending or closing the books. The following options are available:
- Replace auto-terminated approvers with their Manager on Ramp. If there’s no Manager available, the approvals will fall back to the business owner (Default setting)
- Replace any auto-terminated approver with a selected Ramp user
If the user is a department owner, location owner or in a custom approver group, then they will be replaced by the designated user.
Any time a user’s information is updated in your IdP system, the SCIM integration will update the user’s information in Ramp. Your IdP will be the source of truth for all employee information. The follow information is automatically updated via SCIM:
- Role (only if an Employee on Ramp is assigned as someone’s Manager in your IdP, we will upgrade them to Manager on Ramp)
This feature is in Beta
If you would like to set up SCIM during our beta period:
Enroll your business in Ramp Beta in your company settings (this will give you access to all Ramp beta features going forward)
- Go to Settings > Company settings > Ramp beta tab
- Contact your Ramp partner to request access
- Contact our Support team by going