SCIM with Okta

This page covers configuring Okta as your SCIM client to provision users, groups, and licenses into LocalStack. Before starting, make sure you’ve completed the steps in the SCIM overview to enable SCIM and obtain the SCIM Base Connector URL and Bearer Auth Token from the LocalStack web app.

Configuring SCIM with Okta

Use the following steps to configure SCIM Base Connector URL and Bearer Auth Token:

1. Select your application — Go to Applications → Applications and select the application you want to enable SCIM provisioning for.
2. Navigate to Provisioning settings — In the application settings, go to the Provisioning tab and click Integration or Edit (wording may vary).
3. Enter the SCIM connection details:
   • SCIM connector base URL: Paste the SCIM Base Connector URL from the LocalStack SCIM configuration panel.
   • Authentication Mode: Select HTTP Header.
   • Bearer Token: Paste the SCIM bearer token from the LocalStack SCIM configuration panel.
4. Test the connection — Click Test Connector Configuration to confirm Okta can connect successfully.
5. Enable provisioning features (optional) — Once the connection succeeds, enable the desired provisioning actions (Create Users, Update User Attributes, Deactivate Users) under the To App settings tab. There is no need to enable Sync Password, as SSO does not require a password.
6. Save — Save and apply the integration settings.

Note

The exact menu names may vary depending on Okta’s UI version and app type, but the key settings are always the SCIM Base Connector URL and Bearer Auth Token under the provisioning or integration section.

User Management

Provisioning Individual Users

LocalStack supports full provisioning and deprovisioning of individual user accounts via SCIM.

Note

For security reasons, SCIM can only provision user accounts for users who do not already exist in the LocalStack web app. If a user was originally created via SCIM and later removed from your workspace, you must invite them again through the LocalStack Users & Licenses. The user will receive an email invitation and must explicitly accept it to rejoin the workspace.

1. In the Okta Admin Console, go to your application and click the Assignments tab.
2. Select Assign → Assign to People.
3. Search for and select the users you want to provision, then click Assign and Done.
4. Okta will automatically send a SCIM request to LocalStack to create the user account. The user will be visible in LocalStack and their account details will sync from Okta.

Tip

Legacy users (existing LocalStack accounts) can also be assigned to the Okta application, provided their email address matches the one they used to register with the LocalStack web app.

Updating User Accounts

Changes to user attributes (first name, last name, email) in Okta are automatically pushed to LocalStack via SCIM while the integration is active.

Deprovisioning Users

1. In Okta, go to your application’s Assignments tab.
2. Find the user you want to remove and click Remove next to their name.
3. Confirm the action.

Okta will send a SCIM deprovisioning request and the user will be removed from LocalStack.

Provisioning Groups of Users

Groups in Okta can be used to provision multiple users to LocalStack at once.

Assigning a Group

1. In the Okta Admin Console, go to your application and click the Assignments tab.
2. Select Assign → Assign to Groups.
3. Search for and select the groups you want to provision, then click Assign and Done.

Okta will send a SCIM request to LocalStack to create a user account for each member of the group. Changes to a group’s membership in Okta are automatically pushed to LocalStack via SCIM.

Deprovisioning a Group

1. In Okta, return to your application’s Assignments tab.
2. Find the group and click Remove next to its name.
3. Confirm the action.

Okta will send a SCIM request to remove the group’s users from LocalStack. Users who were provisioned solely through this group assignment will also be deprovisioned.

Tip

Any changes in Okta (user/group attribute changes, group memberships, etc.) are automatically synchronized with LocalStack as long as the SCIM integration is active.

Migrating an Existing OpenID Connect or SAML Application

If you have an existing OIDC or SAML app in Okta that already has SSO users assigned, follow these steps to add SCIM provisioning:

1. On the General tab of your Okta application, set Provisioning to SCIM.

2. Go to the Provisioning tab and click Edit to configure the SCIM connection:

   • SCIM connector base URL: Paste the URL from LocalStack.
   • Unique identifier field for users: Enter userName (the Okta default).
   • Supported provisioning actions: Enable all available options.

   

3. Select HTTP Header as the Authentication Mode and paste the Bearer token from the LocalStack SCIM configuration panel. Click Save.

4. After a successful connection test, go to the To App tab, click Edit, and enable Create Users, Update User Attributes, and Deactivate Users. Save your changes.

5. Click the Assignments tab. Okta will show error messages for users who were assigned before provisioning was enabled. Click Provision User and confirm the action to sync all existing users. If the task fails, you can retry it under Dashboard → Tasks.

6. After syncing completes, refresh the page — the error messages should be gone and all users will be fully managed via Okta SCIM.

Role Management

LocalStack workspace roles (admin and member) are assigned to users by pushing SCIM groups whose name identifies the target role. The role groups themselves do not need to exist in LocalStack before the push — they are synthetic SCIM groups keyed off the displayName.

Caution

Each user can only be in one role group at a time. Attempting to add a user who is already in the admin role group to the member role group (or vice versa) returns a 409 conflict. Remove the user from the previous role group first, then add to the new one.

Group Name Convention

Role groups are matched by displayName using a case-insensitive substring check:

• Any group whose name contains admin → admin role group
• Any group whose name contains member → member role group

All of the following are valid names for the admin role group:

• LocalStack-Admin
• LocalStack-Admins-Prod
• engineering-admins

The first time you push a role group from Okta, LocalStack persists that displayName so subsequent GET responses to your IdP reflect the name you sent. You can also rename the group later via SCIM and LocalStack will track the rename.

Creating and Pushing a Role Group in Okta

1. Create a new Okta group whose name contains either Admin (for the admin role) or Member (for the member role). For example: LocalStack-Admin or LocalStack-Member.

2. Add users to the group (users must already be assigned to the LocalStack SCIM application).

3. In your application, go to the Push Groups tab.

4. Push the group to LocalStack via SCIM.

5. Once synced, LocalStack will assign the corresponding role to all members of the group.

   

Moving a User Between Roles

To change a user’s role from member to admin (or vice versa):

1. Remove the user from their current role group in Okta.
2. Add them to the target role group.

Perform these operations as a single atomic action where possible. Adding a user to the new role group while they are still in the old one will return a 409 conflict.

Last-Admin Protection

LocalStack will reject any SCIM request that would leave the workspace without an admin. If you attempt to remove the only admin from the admin role group, the request fails with 409 Cannot remove the last workspace admin. Assign another admin in LocalStack first, then retry the removal.

License Management

Licenses are assigned to users by pushing specifically named SCIM groups that correspond to your LocalStack subscriptions.

Caution

Each user can only be a member of one license group (subscription) per organization. Assigning a user to multiple license groups will result in an error and provisioning will fail for that user.

Group Name Format

License group names follow this format:

{PLAN}-{EMULATOR}-{SUBSCRIPTION_ID}

For example: Enterprise Plan-AWS-sub_1RqpMYGCs0LNOzY9UszOGJkL

The exact group name for each subscription is displayed in the SCIM configuration panel in the LocalStack web app. Use the subscription dropdown to select the plan you want to manage, and the correct group name will be shown for you to copy.

Tip

Legacy users can be added to a license assignment group in Okta, provided their email address matches their LocalStack registration email, they have been assigned to the Okta application, and the group name matches the correct subscription.

Creating and Pushing a License Group in Okta

1. Create a new Okta group named exactly as shown in the LocalStack SCIM configuration panel.
2. Add users to the group (users must already be assigned to the LocalStack SCIM application).
3. In your application, go to the Push Groups tab.
4. Push the group to LocalStack via SCIM.
5. Once synced, LocalStack will recognize the group and assign the corresponding license to all members.

License revocation risk

The Okta group’s membership is the source of truth for license assignments on this subscription. Any change to this group in Okta (adding users, removing users, or syncing it) will reconcile the subscription’s licenses to match the group exactly. Users who are licensed on this subscription but not in the Okta group will have their licenses revoked, regardless of how the license was originally assigned (manually or via SCIM).

This means:

• If you sync an empty group, every license on this subscription will be revoked.
• If you sync a partial group (for example, 2 users in Okta but 5 currently licensed), the 3 users not in the group will lose their licenses.

If you are enabling SCIM on a subscription that already has licensed users, follow the Migrating Users with Existing Licenses steps below before any sync occurs. Once SCIM is enabled, manage license assignments exclusively through Okta.

Migrating Users with Existing Licenses

If your organization already has users with assigned licenses and you want to manage them through SCIM:

1. Create a license group in Okta with the correct name.
2. Add it to the application via the Push Groups tab.
3. Add the existing licensed users to that group through the application. Once added, they will be automatically synced (Push Status becomes Active) and managed through SCIM going forward.