Cardholders may find other articles in the Ramp overview section to be more applicable.
Overview
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 deactivate Ramp users directly from your IDP.
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!
Note: Changes made via SCIM may take up to 20 minutes to be reflected in Ramp, and in rare cases, slightly longer. For urgent actions, such as terminating a compromised Ramp user or card, we recommend completing the action directly in Ramp.
Jump to:
- Overview
- Set up the integration on Ramp
- SCIM settings page
- Provisioning users
- Deactivations
- Automatic updates
Set up the integration on Ramp
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 Microsoft Entra. 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 Microsoft Entra. Other common options are "cost center", "locale", "state", and "country code".
-
Audit your users in Microsoft Entra 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 Microsoft Entra can make it easier to manage user assignments. If you choose to use Microsoft Entra 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 Microsoft Entra 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 (Microsoft Entra). 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)
-
Know the supported features
- Create users (Invite to Ramp)
- Update user attributes (Name, Department, Location, Manager)
- Deactivate users
Integration setup
- Go to Settings > Apps
- Search and select Microsoft Entra
- 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.
- When you select your provider, you will be prompted with instructions on how to set up the integration with Microsoft Entra.
- Install the Ramp app in your Microsoft Entra tenant.
- Use the provided URL and API token from your Ramp dashboard to configure the app in Microsoft Entra.
- Follow the directions in the setup flow to map the appropriate Microsoft Entra attributes to Ramp attributes.
- Ensure that the following are checked and enabled in the "Provision Microsoft Entra ID Users" menu:
- Create
- Update
- Delete
Setting the attribute mappings
The following are the recommended attribute mappings. Please note: that you can assign any desired Microsoft Entra value to the Ramp attributes. Ensure the attribute names match the capitalization below (e.g., in "userName" make sure the "N" is capitalized).
customappsso Attribute | Value | Notes |
userName | userPrincipalName | |
active | Switch([IsSoftDeleted], , "False", "True", "True", "False") | |
emails[type eq "work"].value | ||
name.givenName | givenName | |
name.familyName | surname | |
addresses[type eq "work"].locality | city | This value will be used to set the user’s location in Ramp. If the location does not exist in Ramp yet, it will be automatically created. If Ramp receives a request to create or update a user with no locality set, it will be rejected unless you have set a default location. |
externalId | mailNickname | |
urn:ietf:params:scim:schemas: extension:enterprise:2.0:User: employeeNumber |
employeeId | |
urn:ietf:params:scim:schemas: extension:enterprise:2.0:User: department |
department | This value will be used to set the user’s department in Ramp. If the department does not exist in Ramp yet, it will be automatically created. If Ramp receives a request to create or update a user with no department set, it will be rejected unless you have set a default department. |
urn:ietf:params:scim:schemas: extension:enterprise:2.0:User: manager |
manager |
Attribute <> Ramp User Profile Mapping
Attribute Name | Ramp User Profile | Required? |
userName | Not shown on the Ramp user profile. We use this as a unique identifier on the back end. |
Yes |
active | Activation/deactivation state for Ramp user. We do not handle full account deletion through SCIM (see below). | |
emails[type eq "work"].value | Email address | |
name.givenName | First name | |
name.familyName | Last name | |
addresses[type eq "work"].locality | Ramp location | |
externalId | Alternate unique identifier provided by Microsoft Entra. Not shown in Ramp. | |
urn:ietf:params:scim:schemas: extension:enterprise:2.0:User: employeeNumber |
Employee ID, shown in some data exports. | |
urn:ietf:params:scim:schemas: extension:enterprise:2.0:User: department |
Ramp department | |
urn:ietf:params:scim:schemas: extension:enterprise:2.0:User: manager |
Ramp identifier for this user's manager in Ramp. |
Once you complete setup, you’ll land on the SCIM integration page where you can view and configure your SCIM settings.
Troubleshooting
If you run into any issues configuring SCIM, please get in touch with our Support team. To contact Ramp support, go to your Ramp dashboard and click on the (?) icon at the bottom right of your screen. Just type 'contact,' and we'll send an email to Ramp's support team. A team member will get back to you as soon as possible.
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 an SCIM update from your IdP. If you think your connection is having an issue, we recommend checking this timestamp.
- See the number of users invited and terminated via SCIM
- Configure your offboarding options (See Deactivations 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.
Provisioning users
Invites
When you connect to your IdP (Microsoft Entra) 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
- Department
- Location
- Manager
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 Microsoft Entra)
Note that if you invite a user with a manager who has not been invited to Ramp yet, their manager will not be configured until they are provisioned 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 Microsoft Entra.
Note that you can map any Microsoft Entra field to the Ramp attributes; the recommended fields are pre-populated in Microsoft Entra, 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, 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, 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 Microsoft Entra
You have the option to invite users as individuals or as part of user groups from your Microsoft Entra account.
It is common to have workflows in Microsoft Entra 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 deactivated from Ramp.
Now, when you assign a group, it will still ask you for a department for the entire group, but you can leave it blank. 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, 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.
Deactivations
When a user is de-provisioned from your IdP, we will automatically deactivate them in your Ramp account.
SCIM deactivation
When a user is deactivated by the Identity Provider:
- Users on Ramp will be put in an (new) inactive state where they:
- Cannot log in
- Cannot spend on cards
- Will not receive Ramp notifications
- Users on Ramp will not be deleted or have their cards terminated (the previous behavior).
This inactive state is reversible. Upon reactivation:
- Users can log in to Ramp again.
- Users can spend on their previously issued cards.
- Users will resume receiving Ramp notifications.
Impact on workflows and approvals
While a user is inactive:
- They will be indicated as “(Inactive)” on the People table.
- They will remain in their assigned Ramp workflows.
- They will remain as managers if they are assigned as such.
- However, they will be unable to perform actions related to these duties due to their inability to log in to Ramp.
Deleting users and terminating cards
Ramp will no longer automatically delete users and terminate their cards based on a SCIM instruction. If a customer wants to delete users and terminate their cards permanently, they need to log in to Ramp and perform these actions manually.
When performing these actions on Ramp, customers will have options to:
- Terminate or reassign any active cards.
- Replace the user in any active workflows.
Automatic updates
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 following information is automatically updated via SCIM:
- Name
- Department
- Location
- Manager
- Role