Okta integration: Set up role assignments
Overview
This document will walk through setting up a roles attribute on the Ramp user profile in Okta that will sync over to Ramp user roles via your existing SCIM integration. For help with initial SCIM setup, visit this article.
Note: Role assignments from Okta are currently only supported for businesses with access to the full Ramp suite, including card issuing. Other Okta SCIM features are still fully available.
How it works
Roles will be applied to users upon creation or update and will behave similarly to those manually updated in the Ramp application. If a user’s role cannot be updated successfully, an error will be displayed in the Ramp People tab.
To begin, click into Profile Editor under Directory in the Okta sidebar menu.
Click into your Ramp application user profile (the name depends on your initial configuration of Ramp).
Click Add Attribute to create a new attribute for role assignments.
You'll need to configure the following settings (a screenshot is attached to the end of this document):
- Choose any display name and variable name that makes sense for your organization
- Set the External name to roles.^[type=='rampUserRole'].value
- Set the External namespace to urn:ietf:params:scim:schemas:core:2.0:User
- Add a description of your choice to help other administrators understand the attribute's purpose
In the Attribute enum section, configure the following roles:
| Display name | Value |
|---|---|
| Owner | BUSINESS_OWNER |
| Admin | BUSINESS_ADMIN |
| Cardholder | BUSINESS_USER |
| Accounting | BUSINESS_BOOKKEEPER |
| Guest | GUEST_USER |
| IT Admin | IT_ADMIN |
We recommend leaving the role attribute as optional. When no role value is specified, Ramp will either:
- Keep the user's existing role (for updates to existing users)
- Default to creating the user as a BUSINESS_USER (for new users)
To assign roles to users, navigate to the Profile Mappings section of your application. Here you can create rules to automatically assign roles based on:
- Group membership
- Other profile attributes
- Any combination of conditions supported by Okta's expression language
Once configured, users provisioned to Ramp will receive their designated roles based on your mapping rules. Users should appear in Ramp's People with their updated roles within approximately 10 minutes of provisioning
More documentation on setting up custom role attributes in Okta can be found at this link.
Please note the following:
- Cardholder includes both users and managers. Manager users should be assigned the BUSINESS_USER role.
- The GUEST_USER role can only be assigned during initial user creation. Consider using group-based assignments to ensure users who need the Guest role receive it during their initial provisioning.
Recommended Okta Role attribute setup.