How-To Set Up Okta SCIM Provisioning for Crusoe Cloud

Introduction

SCIM (System for Cross-domain Identity Management) lets Okta create, update, and deactivate users in your Crusoe Cloud organization automatically. Once configured, assigning someone to the Crusoe SCIM app in Okta provisions them in Crusoe with the role you choose, and unassigning them removes their access. No one has to invite users or clean up accounts in the console by hand.

The integration is Okta-driven. You create a SCIM connector in the Crusoe Console, which gives you a SCIM Base URL and a bearer token. You paste both into an Okta SCIM app, and Okta calls Crusoe's SCIM API whenever a user is assigned, changed, or removed. The token inherits the permissions of the org admin who created it, so the connector must be created by an org admin.

A user's Crusoe role comes from the SCIM roles attribute, which you populate in Okta either per group assignment or per user profile. SCIM supports the four organization-level roles: org-admin, org-editor, org-reader, and org-member. If a user arrives with no role or an unrecognized value, Crusoe defaults them to org-member, which the console displays as No org role. Project-level roles are not managed by SCIM; an org admin grants those in the console after provisioning.

SCIM builds on SSO rather than replacing it. Users still sign in through Okta SSO; SCIM only controls who exists in your org and what org role they hold. SCIM-managed users show a SCIM source in the Team table, and their role, name, and login method become read-only in the console because Okta owns them.

Prerequisites

• Okta SSO Configured and Working for Your Crusoe Organization (See How-To Set Up Okta SSO for the Crusoe Cloud Console)
• SCIM Enabled on Your Organization by Crusoe Support (See Step 1)
• Org Admin Role in Crusoe Cloud (Dedicated Admin Account on a Shared Email Alias Recommended)
• Okta Administrator Access to Create Apps and Edit Profiles

Instructions

Step 1: Ask Crusoe Support to Enable SCIM

1. Open a support ticket at support.crusoecloud.com requesting SCIM for your organization. If you are also setting up SSO, ask for both in the same ticket.
2. Once Support confirms it is enabled, log out of the Crusoe Console and back in. You should see a SCIM tab under Organization > User Authentication with a Configure SCIM Connector button.

ℹ️ Note: The SCIM tab requires both an active SSO provider and the org admin role. If you see Enable SSO to configure SCIM, finish your SSO setup first. If you see no SCIM tab at all, confirm you are an org admin and that you started a fresh session.

Step 2: Create the SCIM Connector in the Crusoe Console

1. Sign in to the Crusoe Console as an org admin. We recommend a dedicated admin account on a shared email alias, with MFA, rather than a named person, so the integration does not break if that person leaves.
2. Go to Organization > User Authentication > SCIM > Configure SCIM Connector.
3. Copy the SCIM Base URL.
4. Copy the API bearer token and store it in your password manager immediately.
5. Confirm the new connector appears in the list.

⚠️ Warning: The token is shown once. After you close the dialog the console displays only its first four characters. If you lose it, create a new SCIM API key from the integration page and update Okta; the old key can be deleted.

Step 3: Create the SCIM App in Okta

You can use Okta's SCIM 2.0 Test App (Header Auth) template or build your own app integration.

Using the template:

1. In the Okta Admin Console, go to Applications > Applications > Browse App Catalog, search for SCIM 2.0 Test App (Header Auth), and add it.
2. On the app's Provisioning tab, click Configure API Integration and check Enable API Integration.
3. In SCIM 2.0 Base Url, paste the Base URL from Step 2.

4. In API Token, enter the word Bearer, a space, then your token:

   Bearer <YOUR_SCIM_TOKEN>

5. Click Test API Credentials. You should see a success message.

Building your own app:

1. In the Okta Admin Console, go to Applications > Applications > Create App Integration, choose SWA as the sign-in method and Web Application as the type.
2. On the app's General tab, enable SCIM under Provisioning.
3. On the Provisioning > Integration tab, set the connector base URL, choose HTTP Header authentication, and paste the token. The Bearer prefix is not needed for a custom app.
4. Test the connection.

ℹ️ Note: An Unauthorized error on the connection test almost always means one of three things: the Bearer prefix is missing (template app), the connector was created by a user who is not an org admin, or the token and Base URL came from two different connectors. Check these before contacting Support.

Step 4: Enable Provisioning Features in Okta

1. In the Okta Admin Console, open the SCIM app's Provisioning tab, select To App, and click Edit.
2. Enable:
   • Create Users
   • Update User Attributes
   • Deactivate Users
3. Click Save.

Step 5: Define the Role Attributes in Okta

Crusoe reads a user's role from the SCIM roles attribute. You expose it in Okta as two custom attributes on the SCIM app's profile.

1. In the Okta Admin Console, go to Directory > Profile Editor and open the User profile belonging to your SCIM app. This is a separate profile from Okta's default User profile; make sure you are editing the app's profile.
2. Click Add Attribute and create two string attributes in the urn:ietf:params:scim:schemas:core:2.0:User namespace:
   • roleValue - external name roles.^[primary==true].value
   • roleType - external name roles.^[primary==true].type
3. If you plan to assign roles by group (Option A below), set each attribute's Attribute type to Group. Only Group attributes can be set on a group assignment.

Then choose one of the two approaches below.

Step 6, Option A: Assign Roles by Okta Group

Best when you already organize people into groups. All of these steps happen in the Okta Admin Console.

1. In the SCIM app, under Provisioning > To App > Attribute Mappings, confirm roleValue and roleType are not mapped. A mapped attribute overrides whatever you set on a group assignment.
2. Create one Okta group per Crusoe role you need, for example Crusoe – Admins, Crusoe – Editors, Crusoe – Readers.
3. On the SCIM app's Assignments tab, choose Assign > Assign to Groups, pick a group, and set both roleValue and roleType to that group's Crusoe role name, exactly as written: org-admin, org-editor, org-reader, or org-member.
4. Repeat for each group.
5. If a user may belong to more than one assigned group, order the groups in the Assignments tab with the most privileged at the top and your default at the bottom. Okta applies the first match.

💡 Tip: You do not need a group for org-member. Users with no role or an unrecognized role default to it automatically.

Step 6, Option B: Assign Roles per User

Best when roles do not line up with existing groups. All of these steps happen in the Okta Admin Console.

1. In Directory > Profile Editor, open Okta's default User profile and add a string attribute named crusoeRole. Check Define enumerated list of values and add org-admin, org-editor, org-reader, org-member.

2. In your SCIM app, go to Provisioning > To App > Attribute Mappings and map both roleValue and roleType to the following expression:

   user.crusoeRole != null && String.len(user.crusoeRole) > 0 ? user.crusoeRole : "org-member"

3. Set crusoeRole on each user's Okta profile.

Step 7: Assign Users and Test

1. In the Okta Admin Console, on the SCIM app's Assignments tab, assign a test user or group.
2. In the Crusoe Console, check Organization > Team. The user should appear with SCIM as their source and the expected org role.
3. Have the test user sign in to Crusoe via Okta SSO.
4. In Okta, assign an existing Crusoe user to the SCIM app to confirm they convert to SCIM-managed without losing access.

💡 Tip: If you assign the same Okta group to both your SSO app and your SCIM app, removing someone from that group removes them from both. This is the recommended pattern.

Step 8: Migrate Everyone, but Keep a Break-Glass Admin

Once testing passes, assign the rest of your users in Okta.

Keep at least one org admin outside SCIM, ideally a dedicated admin account on a shared email alias with MFA required. If the Okta integration is ever misconfigured or the token is lost, that account is how you recover.

Example

A security team is required to offboard contractors within an hour of their Okta deactivation and is tired of auditing Crusoe's Team page by hand. They create the SCIM connector under a crusoe-scim@example.com service alias with org admin and MFA, add the Test App in Okta with Bearer <token>, and pass the connection test on the first try.

They already have Okta groups per team, so they pick Option A: three groups mapped to org-admin, org-editor, and org-reader, ordered most-privileged first. A contractor added to the readers group appears in Crusoe within a minute as a SCIM-managed org-reader; an admin grants them their one project.

When the contract ends, removing them from the Okta group deactivates them in Crusoe and, because the same group feeds the SSO app, they can no longer sign in either. The team's original human admin stays outside SCIM as the break-glass account.

Frequently Asked Questions

A user was provisioned but cannot see any projects.

Expected. SCIM assigns organization-level roles only. An org admin grants project-level roles in the console after the user is provisioned. If you want users to arrive with access to everything, provision them as org-editor or org-reader rather than org-member.

Is org-member the same as "No org role" in the console?

Yes. Both describe a member of the organization with no organization-wide permissions, intended to be paired with project-level roles.

I set roleValue and roleType on the group assignment but the user came through as org-member.

Check, in order: the role name is spelled exactly (org-reader, not Org Reader); roleValue and roleType are not mapped under Provisioning > To App; the attributes are defined on the SCIM app's profile with Group attribute type; and the group is assigned to the SCIM app, not the SSO app.

Okta says there are no attributes to set when I assign a group.

The attributes are either Personal rather than Group type, defined on Okta's default User profile instead of the SCIM app's profile, or already mapped under To App. See Step 5.

Can I change a SCIM-managed user's role or delete them in the console?

No. Okta owns those fields. Change the user's group or profile attribute in Okta, or unassign them from the SCIM app to deactivate them.

What happens if I delete the SCIM connector?

All SCIM-managed users become Crusoe-managed users and keep their current roles and access. Crusoe rejects further requests from your Okta app. Unassign those users from the SCIM app in Okta afterwards to avoid errors in Okta's logs.

Does deactivating a user in Okta revoke their API keys?

Deactivation removes the user's identity and roles in Crusoe. As a precaution, also revoke any API keys or SSH keys that user created, and unassign them from the SSO app so they cannot sign in again.

Can SCIM push Okta groups into Crusoe?

Not today. SCIM manages users and their org role. Groups are used only on the Okta side to decide which role to send.

Which identity providers are supported?

Okta only.

Related Articles

• How-To Set Up Okta SSO for the Crusoe Cloud Console
• API key fails with "401 Authentication failed" after user removal

Additional Resources

• Log in to Crusoe Cloud with Single Sign-On (SSO) (Crusoe Cloud Docs)
• Managing Users (Crusoe Cloud Docs)
• Manage your API keys (Crusoe Cloud Docs)