Brex and Okta SCIM
Overview
PremiumEnterpriseSmart card
A System for Cross-domain Identity Management (SCIM) is an integration that helps you automate user access for your company’s Brex account. It can be used to provision Brex user accounts for your employees after being added to your Okta instance. It can also disable users after their removal from your Okta instance.
Okta SCIM setup
You can connect an Okta SCIM account with your Brex account by following these steps: Note: Steps 1 and 2 are optional. If you’d prefer not to set up your Okta SAML SSO, skip to Step 3, however if you want to configure both Okta SSO and SCIM, make sure you complete the steps in the following order. Step 1: Set up the Okta SAML SSO for your account by reaching out to Brex Support with this information:
- Your business name
- Your email address (or the email address of the individual from your team that will be working on the SAML SSO setup)
- A test user to be used for SAML SSO setup
- A list of email domains that should be supported for SSO & SCIM
- Whether or not you have HRIS enabled already
- Whether or not you want users to be sent an invitation email automatically after being added to SCIM
- If so, whether you want these users invited as the employee role type or the reimbursements-only role type.
Step 2: Wait 3-5 business days for a response email from our team with instructions on how to create the SAML SSO application in Okta. Once successfully set up, our team will test an enable SAML SSO for your account. Step 3: Go to the Applications page in your Okta admin dashboard. Step 4: Click Browse App Catalog to create a new SCIM application. Step 5: Search for SCIM and choose the SCIM 2.0 Test App (Basic Auth). Step 6: Click Add Integration. Step 7: Enter a name for your application, check the box to hide the application from users, and click Next.
Step 8: If not already, set Application username format to Okta username. Leave everything else as the default and click Done to create the application.
Step 9: Go to the Provisioning tab and click Configure API Integration.
Step 10: Enter your SCIM API credentials (these will be sent to you via a secure document from our team) and click Test API Credentials to confirm the settings are correct.
Step 11: Go to the To App tab and click the checkbox to enable Create Users, Update User Attributes, and Deactivate Users. You can also verify mapping in the attribute mapping section below. The defaults we expect for mappings can be found in the screenshot at the bottom of the page.
Attributes map to Brex as follows:
- Department: This maps to the department attribute in Brex.
- Cost Center: This maps to the cost center attribute in Brex.
- Division: This attribute maps to the legal entity in Brex.
- Note: Currently, legal entities are expected to already exist in Brex before employees can be mapped to them. To create legal entities please go to the Brex dashboard.
- Manager value: This attribute maps to the manager email in Brex. For manager import, make sure to map the manager’s email to the manager value. More times than not this will be the “user.managerId” in Okta. But if it isn't, map the correct attribute here.
- Country: This attribute currently maps to the Location attribute in Brex. Okta supports this as a 2 character country code.
- You can supply any other value as the location attribute in Brex by providing a custom profile mapping in Okta.
Mapping custom attributes (location)
Step 1: In your Brex SCIM app, go to Provisioning > Attribute Mappings and click Go to Profile Editor.
Step 2: Select Add Attribute.
Step 3: Define the attribute details for location.
- Data type = string
- Display name: Location
- Variable name: location
- External name: location
- External namespace: urn:ietf:params:scim:schemas:extension:brex:User
- Attribute type: Personal or Group
Step 4: In your Brex SCIM app, go to Provisioning > Attribute Mappings > Show Unmapped Mappings and click the pencil icon for Location.
Step 5: Map the relevant user attribute value from the Okta user profile to location (user.city is an example).
You’ve now integrated Okta SCIM with your Brex account. You can test your setup by assigning the SCIM app to an Okta user to verify the user is provisioned in the Teams page of your Brex dashboard.
Recommended attribute mappings
| Attribute | Attribute type | Value | Apply on |
|---|---|---|---|
| Username userName | Personal | Configured in Sign On settings | |
| Given name givenName | Personal | user.firstName | Create and update |
| Family name familyName | Personal | user.lastName | Create and update |
| Middle name middleName | Personal | user.middleName | Create and update |
| Honorific prefix honorificPrefix | Personal | user.honorificPrefix | Create and update |
| Honorific suffix honorificSuffix | Personal | user.honorificSuffix | Create and update |
| Email email | Personal | user.email | Create and update |
| Primary email type emailType | Personal | (user.email != null && user.email !=”) ? ‘work’ :” | Create and update |
| Title title | Personal | user.title | Create and update |
| Display name displayName | Personal | user.displayName | Create and update |
| Nickname nickname | Personal | user.nickName | Create and update |
| Profile Url profileUrl | Personal | user.profileUrl | Create and update |
| Primary phone primaryPhone | Personal | user.primaryPhone | Create and update |
| Primary phone type primaryPhoneType | Personal | (user.primaryPhone != null && user.primaryPhone != “) ? work :” | Create and update |
| Address type addressType | Personal | (user.streetAddress != null && user.primaryPhone != “) ? ‘work’ :” | Create and update |
| Street address streetAddress | Personal | user.streetAddress | Create and update |
| Locality locality | Personal | user.city | Create and update |
| Region region | Personal | user.state | Create and update |
| Postal Code postalCode | Personal | user.zipCode | Create and update |
| Country country | Personal | user.countryCode | Create and update |
| Formatted formatted | Personal | user.postalAddress | Create and update |
| Preferred language preferredLanguage | Group | user.preferredLanguage | Create and update |
| Locale Name locale | Group | user.locale | Create and update |
| Time zone timezone | Group | user.timezone | Create and update |
| User type userType | Group | user.userType | Create and update |
| Employee number employeeNumber | Personal | user.employeeNumber | Create and update |
| Cost center costCenter | Group | user.costCenter | Create and update |
| Organization organization | Group | user.organization | Create and update |
| Division division | Group | user.division | Create and update |
| Department department | Group | user.department | Create and update |
| Manager value managerValue | Personal | user.managerid | Create and update |
| Manager display name managerDisplayName | Personal | user.manager | Create and update |
| (optional) Location location | Personal or Group | Expression from Okta user profile | Create and update |