Provision users with SCIM

System for Cross-domain Identity Management (SCIM) lets Okta manage your Crusoe Cloud users. When you assign, update, or unassign a user in Okta, Okta pushes the change to Crusoe Cloud. Offboarding a user in Okta removes their Crusoe Cloud access without a separate step in the Console.

SCIM provisioning supports Okta only.

How SCIM works with Crusoe Cloud

After you connect SCIM, Okta becomes the source of truth for your users:

• Create: Assigning a user to your SCIM app in Okta creates their Crusoe Cloud account with single sign-on (SSO) required. If the user already has an account in your organization, Okta takes over managing it.
• Update: Changes to a user's name, email address, or organization role in Okta sync to Crusoe Cloud.
• Deactivate: Unassigning or deactivating a user in Okta deletes their Crusoe Cloud account, including their project roles and API keys. If you reactivate the user in Okta, Crusoe Cloud creates a new account with the organization role from Okta.
• Roles: Okta sets each user's organization role. See Map organization roles.

While SCIM is connected:

• New users come from Okta. Crusoe Cloud no longer creates accounts at a user's first SSO sign-in, so a user that Okta hasn't provisioned can't sign in. Existing users keep their access.
• For SCIM-managed users, you manage the name, organization role, and SSO requirement in Okta, and you remove users there. The Console shows these settings as read-only.
• You still assign project roles in the Console.

Prerequisites

To set up SCIM, you need:

• The org-admin role in your Crusoe Cloud organization
• An active Okta SSO connection
• SCIM enabled for your organization—to enable it, contact your Crusoe Cloud account team or Crusoe support
• Administrator access to your Okta tenant

Create SCIM credentials in Crusoe Cloud

Okta uses SCIM credentials—a SCIM API endpoint and an API key—to call Crusoe Cloud. Create the API key from a shared admin account, such as one that uses an email alias, rather than a personal account.

To create the credentials:

1. In the Crusoe Cloud Console, go to IAM > User Authentication > SCIM.
2. Click Configure SCIM.
3. Enter an Alias for the API key, such as okta-scim.
4. (Optional) To set an expiration, turn on Expiration and choose an Expiration Date. Keys never expire by default.
5. Click Create API Key.
6. Copy the SCIM API endpoint and the API key. The API key appears only once.

The SCIM API endpoint has this format:

https://api.cloud.crusoe.ai/scim/v2/integrations/<integration-id>

Create the SCIM app in Okta

SCIM uses its own Okta app, separate from your SSO app. To create it:

1. In the Okta Admin Console, create an app integration. Set Sign-in method to SWA - Secure Web Authentication and Application type to Web Application.
2. On the General tab, enable SCIM provisioning.
3. On the Provisioning tab, open Integration settings and enter:
   • SCIM connector base URL: the SCIM API endpoint from Crusoe Cloud
   • Unique identifier field for users: userName
   • Authentication Mode: HTTP Header
   • Authorization: Bearer followed by a space and the API key from Crusoe Cloud
4. Enable Push New Users and Push Profile Updates.
5. Click Test Connector Configuration. After the test passes, click Save.
6. On the Provisioning tab, open To App settings and enable Create Users, Update User Attributes, and Deactivate Users.

You can also start from the SCIM 2.0 Test App (Header Auth) template in the Okta Integration Network. On its Provisioning tab, click Enable API Integration, and then enter the same endpoint and Bearer API key.

Map organization roles

Okta sends each user's organization role in the SCIM roles attribute. The role must be org-admin, org-editor, org-reader, or org-member. The Console shows org-member as No org role. See available roles.

First, add the role attributes to your SCIM app:

1. In the Okta Admin Console, go to Directory > Profile Editor and select your SCIM app's user profile.
2. Add these two required string attributes in the urn:ietf:params:scim:schemas:core:2.0:User namespace:

Display name	Variable name	External name
Role Value	roleValue	roles.^[primary==true].value
Role Type	roleType	roles.^[primary==true].type

Then choose how Okta sets each user's role. Most organizations set roles by group.

Set roles by group

Assign a role to each Okta group that you assign to the SCIM app:

1. In your SCIM app, go to Provisioning > To App and confirm that roleValue and roleType aren't mapped. Mapped attributes override values from group assignments.
2. Create one Okta group per role, or reuse existing groups.
3. On the Assignments tab, assign each group to the SCIM app. Set roleValue and roleType to that group's role, such as org-admin.
4. If users belong to more than one assigned group, order the groups with the most-privileged group at the top and your default group at the bottom.

(Optional) Set roles from user profiles

Store each user's Crusoe Cloud role on their Okta profile instead of setting it by group:

1. In Directory > Profile Editor, select the User (default) profile.

2. Add a string attribute with the variable name crusoeRole. Select Define enumerated list of values, and add org-member, org-reader, org-editor, and org-admin.

3. In your SCIM app, go to Provisioning > To App. Map both roleValue and roleType to this expression:

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

   Users without a crusoeRole value get org-member. To use a different default, replace org-member in the expression.

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

Assign users

To start provisioning, assign users or groups to your SCIM app on its Assignments tab. Assigning an existing Crusoe Cloud user in your organization converts them to a SCIM-managed user.

To keep access in sync, assign the same Okta group to your SSO app and your SCIM app. Removing a user from that group then removes them from both apps.

important

Keep at least one admin outside SCIM for emergency access and use a shared admin account with MFA required.

After Okta pushes users, the SCIM page in Crusoe Cloud shows Last activity and Users synced. To see each sync event, click View audit log.

Rotate the SCIM API key

Each SCIM connection supports up to five API keys, so you can rotate keys without downtime. To rotate the key:

1. On the SCIM page, click Create SCIM API Key and copy the new key.
2. In Okta, replace the API key in the Authorization value and test the connection.
3. In Crusoe Cloud, delete the old key from the SCIM API Keys table.

If you delete your only key, Okta stops syncing until you create a new key and enter it in Okta.

Disconnect SCIM

When you remove the SCIM connection, existing users stay in Crusoe Cloud and become manually managed accounts. Crusoe Cloud rejects later requests from the Okta SCIM app. To disconnect SCIM:

1. To stop outgoing updates, turn off provisioning for the app in Okta, and unassign its users.
2. On the SCIM page in Crusoe Cloud, click Remove SCIM Connection.
3. Type your organization name and click Delete SCIM.

Limitations

• SCIM doesn't support identity providers other than Okta.
• SCIM syncs users only. Okta groups don't appear in Crusoe Cloud.
• SCIM doesn't sync project roles. Assign them in the Console.
• Okta can't remove the last org-admin in your organization.

Troubleshooting

Issue	Resolution
Enable SSO to configure SCIM appears on the SCIM page	Connect Okta SSO first.
Okta connection test fails with an authorization error	Check that the Authorization value is Bearer followed by the full API key, and that the key hasn't expired or been deleted.
maximum of 5 tokens per SCIM integration reached	Delete an unused key before you create a new one.
user belongs to a different organization	The user's email address belongs to an account in another Crusoe Cloud organization. See Users with an existing account.
cannot remove the last org-admin from an organization	Assign org-admin to another user before you change or deactivate this one.
A user sees Your organization requires users to be provisioned via SCIM at sign-in	Assign the user to your SCIM app in Okta.