Set up SCIM mappings for custom user fields

Overview

SCIM (System for Cross-domain Identity Management) mappings allow you to sync custom user field data from your identity provider (IdP) to Ramp. This keeps user attributes like department, location, and custom fields automatically updated across systems. Ramp supports SCIM integrations with Okta and Microsoft Entra. When configured, your IdP becomes the source of truth for employee information, and any updates sync automatically to Ramp. Changes made through SCIM may take up to 5 minutes to be reflected in Ramp.

Before you begin

Before setting up SCIM mappings, complete these preparation steps:

1. Determine your field mappings — Decide which IdP profile fields you want to map to Ramp attributes. Common mappings include:

• Department: Can map to "department," "cost center," "organization," or "division"
• Location: Can map to "city," "locale," "state," or "country code"

2. Audit your user data — Ensure every user in your IdP has values for department AND location. Users missing these values will not be provisioned in Ramp.
3. Review existing users — If you already have users in Ramp, confirm their profile information matches your IdP data. When you provision via SCIM, the IdP becomes the source of truth and will override existing Ramp profiles.
4. Plan for HRIS transition — If you’re disconnecting from HRIS to set up SCIM, ensure your HRIS fields for department and location are synced to your IdP first.
5. Create custom fields in Ramp — Custom fields must be created before they can be mapped via SCIM. See the “Set up custom user fields with SCIM” section below for detailed steps.

Set up custom user fields with SCIM

Custom Fields can be integrated with SCIM to map additional attributes from your IdP to user profiles in Ramp. This allows you to maintain consistent custom data across systems and use it in Ramp workflows.

Step 1: Create custom fields in Ramp

Before mapping, you must create custom fields in Ramp. If no custom fields exist, the mapping section won't appear in your SCIM settings.

To create custom fields, see Custom fields.

Step 2: Map IdP attributes to custom fields in Ramp

Once you’ve configured the mappings in your IdP, you need to connect them in Ramp:

1. From the People page, click the three-dot menu on the top right
2. Select “Configure Okta setting” (or “Configure Entra setting” for Microsoft Entra)
3. Scroll down to the Custom field mappings section
4. Click Add mapping
5. Enter the SCIM attribute name:

• For Okta: Use the “External name” you configured (e.g., budget_manager )
• For Entra: Use only the attribute name after the Ramp namespace (e.g., approver from urn:ietf:params:scim:schemas:extension:ramp:2.0:User:approver )

6. Select the corresponding Ramp custom field from the dropdown
7. Click Save Changes

Each custom field can only be mapped to one SCIM attribute. If you send attribute names in camelCase from your IdP (for example, userOrganization), Ramp will automatically convert them to snake_case (for example, user_organization).

The custom field values will sync automatically when users are provisioned or updated. Custom field data typically appears in Ramp within 5-10 minutes for Okta, or within 10 minutes for Microsoft Entra.

Step 3: Verify custom field sync

To confirm custom fields are syncing correctly:

1. Go to People in Ramp
2. Click on a user to view their profile
3. Verify the custom field data appears correctly

You can also populate custom field values through CSV upload or the Developer API.

Set up SCIM mappings in Okta

First, complete the initial Okta SCIM setup by following Set up Ramp’s SCIM integration with Okta. Once connected, return here to configure custom field mappings.

Configure custom field mappings in Okta

To map custom fields from Okta to Ramp:

1. In Okta, go to Applications > Ramp > Provisioning > To App
2. Under Attribute Mappings , click Go to Profile Editor
3. Click Add Attribute and configure:

• Data type: Choose string or string array
• Display name: User-friendly name (can be any value)
• Variable name: Internal Okta name (can be any value)
• External name: Must match your Ramp configuration in snake_case (for example, budget_manager )
• External namespace: urn:ietf:params:scim:schemas:extension:ramp:2.0:User
• Attribute required: Leave unchecked until testing is complete

4. Save the attribute
5. Return to Attribute Mappings and map Okta user profile attributes to your new custom attributes, or manually specify values for users
6. Set each mapping to apply on "Create and Update"

Set up SCIM mappings in Microsoft Entra

First, complete the initial Entra SCIM setup by following Set up Ramp's SCIM integration with Microsoft Entra. Once connected, return here to configure custom field mappings.

Configure custom field mappings in Entra

To add custom fields in Microsoft Entra:

1. In your Microsoft Entra, click Provisioning > Attribute mapping (Preview) > Provision Microsoft Entra ID Users
2. At the bottom of the screen, click Show advanced options > Edit attribute list for customappsso
3. Add your custom attribute with these settings:

• Name: Prefix with Ramp namespace: urn:ietf:params:scim:schemas:extension:ramp:2.0:User: followed by your attribute name (e.g., urn:ietf:params:scim:schemas:extension:ramp:2.0:User:approver )
• Type: String
• Multi-Value? Check this box if the attribute contains multiple values

4. Save the configuration and navigate back to the Attribute mapping page
5. Click Add New Mapping below the table of existing attribute mappings
6. Configure the mapping using one of these methods:

• Direct mapping: Select an existing Entra user profile attribute from the dropdown
• Constant value: Enter a fixed value for all users
• Expression: Create a custom expression (ensure arrays are used for multi-value attributes)

7. Save the mapping
8. Wait for automatic provisioning which happens about hourly. Or you can do on-demand provisioning for up to 5 users at once

Frequently asked questions

Which custom field types can be synced via SCIM?

The following custom field types can be synced through SCIM:

• Ramp Object - References to other Ramp objects (for example, another user). Map using the associated user’s email address.
• Select - Custom categories (for example, job title). Note: Values received from SCIM systems will automatically have a value for that option created in the Ramp system.
• Boolean - Yes/no fields (for example, remote worker, has parking)
• Text - Free-form text (for example, notes). Note: this field type has less workflow flexibility than Custom Object.

What happens if a custom field value is empty in the IdP?

Empty values will sync as blank in Ramp. Ensure your IdP data is complete before enabling SCIM sync for custom fields.

Can I map multiple IdP attributes to one custom field?

No. Each Ramp custom field maps to a single IdP attribute. Create separate custom fields if you need to track multiple attributes.

What data types are supported for custom fields in SCIM?

Ramp supports string (single value) and string array (multiple values/list). This configuration cannot be changed after the attribute is created in your IdP.

What naming convention must I use for custom field external names?

External names must be in snake_case format using only lowercase letters and underscores (for example, budget_manager, cost_center_owner). Display names and variable names in your IdP can be any value.

For general SCIM FAQs, see Setting up SCIM and managing user provisioning.

Related articles

• Setting up SCIM and managing user provisioning
• Set up Ramp's SCIM integration with Okta
• Set up Ramp's SCIM integration with Microsoft Entra
• Custom fields