> ## Documentation Index
> Fetch the complete documentation index at: https://semgrep-ee9d73d8-abhijna-tec-650-scim-beta-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# SCIM provisioning with Okta
> Supported Okta user and group provisioning workflows for SCIM with Semgrep AppSec Platform.
This article covers how to set up SCIM with Okta and manage the user and group provisioning workflows Semgrep supports.
SCIM provisioning is in **beta**. See [SCIM provisioning (beta)](/deployment/scim) for shared concepts, beta enrollment, how SCIM relates to SSO, team group naming, and general limitations.
## Prerequisites
Meet the [shared SCIM prerequisites](/deployment/scim#prerequisites), then confirm you have Okta permission to create or edit applications, configure SCIM API integration, and manage application assignments and push groups.
## Set up SCIM with Okta
Sign in to [Semgrep AppSec Platform](https://semgrep.dev/login) as an admin.
Go to [**Settings > Access > Login methods**](https://semgrep.dev/orgs/-/settings/access/loginMethods).
Click **Set up** to launch the **Directory Setup Portal**.
Select **Okta** as the identity provider.
The Directory Setup Portal lets you create a new Okta SCIM application or use an existing SAML application with SCIM provisioning. Complete the portal workflow:
1. Create Okta application
2. Configure API integration
3. Configure provisioning actions
4. Assign people and groups
5. Push groups
6. Map groups to roles
7. Test directory connection
Assign users to the directory before adding them to push groups in step 5. Adding an unprovisioned user to a push group does nothing and doesn't trigger just-in-time (JIT) provisioning.
If the test succeeds, SCIM connection status shows **Active** under **Identity management (SCIM)** on [**Settings > Access > Login methods**](https://semgrep.dev/orgs/-/settings/access/loginMethods).
To reopen the Directory Setup Portal later, go to **Login methods**, find **Identity management (SCIM)**, and click **View**.
## Understand assignments and push groups
Okta separates application **Assignments** and **Push Groups**. Don't use the same group for both. See [Okta's guidance on common group push issues](https://help.okta.com/oie/en-us/content/topics/users-groups-profiles/usgp-group-push-troubleshoot.htm).
| Type | Okta location | Purpose |
| :------------------- | :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------- |
| **Group assignment** | Application **Assignments** tab | Provisions users into the Semgrep deployment. Does not create teams or map deployment roles. New users default to **Member**. |
| **Push group** | Application **Push Groups** tab | Maps deployment roles or creates Semgrep teams. Users must already be provisioned into the directory. |
## Manage users
Assign users to the SSO connection as well as the SCIM application. SCIM can provision a user who isn't assigned to SSO, but that user can't sign in.
### Assign an individual user
In the Semgrep Okta application, open the **Assignments** tab.
Click **Assign**, then select **Assign to People**.
Find the user and click **Assign**.
Click **Save and Go Back** to save the assignment and return to the **Assignments** tab.
### Assign users through a group
Under **Assignments**, click **Assign** > **Assign to Groups**.
Find the group and click **Assign**.
Click **Done**.
You should now see the group under **Assignments** > **Filter** > **Groups**, and the provisioned users under **Assignments** > **Filter** > **People**. The users should also appear in Semgrep AppSec Platform.
### Remove a user
Under **Assignments**, select **Filter** > **People** or **Groups**.
Click the **x** icon next to an assigned user or group to remove them from the directory and deployment.
## Manage deployment roles
### Add role push groups
In the Semgrep Okta application, open the **Push Groups** tab.
Click **Push Groups** > **Find groups by name**.
Locate the group, select it, and click **Save**. The group appears in the role-mapping section of the Directory Setup Portal.
### Map push groups to roles
You can map roles during setup, or later by reopening the portal:
Go to [**Settings > Access > Login methods**](https://semgrep.dev/orgs/-/settings/access/loginMethods).
Under **Identity management (SCIM)**, click **View** to open the Directory Setup Portal.
Click **Configure role assignment**.
Use the drop-down in the **Role** column for each group to select its role. Updating the role propagates to all Semgrep users in that group.
Team push groups that use the `[team:]` naming convention also appear in the role mapping table. Don't assign a deployment role to these groups.
### Change a user's deployment role
1. Remove the user from the role push group in Okta. This resets their role to **Member** in Semgrep.
2. Assign the user to a different role push group in Okta. Semgrep updates the user's role to the role mapped to that group.
## Manage teams
To create Semgrep teams from Okta push groups, use the `[team]` naming convention described in [Manage teams with SCIM](/deployment/scim#manage-teams-with-scim). IdP directory groups map to two distinct Semgrep concepts: deployment role groups and Semgrep teams. Each concept has its own role groups. The naming convention tells Semgrep which is which.
Name the push group with `[team]` or `[team:]` before you push it. A group without that suffix is treated as a deployment role group. Renaming a group that's already pushed doesn't trigger team creation. Create a new group with the naming convention, then push it.
You can't manage default teams or sub-teams in Semgrep through SCIM. Attempts to modify these teams through push groups in Okta have no effect in Semgrep.
### Create a team
In the Semgrep Okta application, open the **Push Groups** tab.
Click **Push Groups** > **Find groups by name**.
Locate the `[team]` or `[team:]` named group, select it, and click **Save** to push the group to Semgrep.
### Assign team-level roles
Create one push group per role suffix (`[team:manager]`, `[team:member]`, `[team:readonly]`). Semgrep maps them to the same team.
* Assign a user to only one role-suffixed push group per Semgrep team.
* When changing a member's team permission level, remove them from the first role-suffixed group before adding them to a different one.
* Apply rename and delete operations to all role-suffixed groups for that team.
### Add or remove team members
Users must already be assigned to the directory. Do not add deployment **Admins** to team push groups. Because deployment **Admins** already have access to all teams, Semgrep does not add them to team push groups.
#### Add members
Open the **Push Groups** tab.
Open the group you want to assign users to.
Click **Assign People**, locate the users, and click the **+** icon next to each user.
#### Remove members
Open the **Push Groups** tab and open the relevant group.
Click the **x** icon next to the user you want to remove.
### Rename a SCIM-managed team
If you have multiple role-suffixed push groups for one team, update the name consistently across all of them.
Under **Assignments**, with **Filter** > **Groups** selected, find the group and open it.
Click **Actions** > **Edit**.
Change the name, then click **Save**.
### Delete a SCIM-managed team
Unlinking a push group and deleting it in the target app also deletes the corresponding Semgrep team.
Under the **Push Groups** tab, find the group you want to remove.
Click the **Active** drop-down, then select **Unlink Push Group**.
Select **Delete the group in the target app** (recommended) to avoid orphaning the team in Semgrep.
## Okta-specific behavior and limitations
For shared SCIM limitations, see [Limitations](/deployment/scim#limitations). Okta-specific behavior:
* SCIM events aren't always instantaneous. Changes can take up to a minute or longer to propagate to Semgrep.
* Adding an unprovisioned user to a push group does nothing and doesn't trigger JIT provisioning.
* Okta push groups don't map to Semgrep sub-teams. Don't create an Okta group whose name matches an existing sub-team in Semgrep.
* A push group without a `[team]` or `[team:]` suffix is treated as a deployment role group. Renaming a group that's already pushed doesn't trigger team creation.
* Do not add deployment **Admins** to team push groups. Because deployment **Admins** already have access to all teams, Semgrep does not add them to team push groups. They appear in the Okta group but not on the corresponding Semgrep team.
* Demoting an admin who was added to an Okta group to **Member** or **Read-only** can cause drift. Remove them from the group in Okta and re-add them after their role has changed.
* Mapping an Okta group to the default team and operating on that group has no effect in Semgrep.
* If a push group spans multiple organizations, membership and team changes apply across all of them.
* Each SCIM application manages one Semgrep deployment. Multiple deployments can share an SSO connection, but each deployment needs its own SCIM application.
* Assign users to the SSO connection before the SCIM app. In a multi-app setup, Okta admins can assign directory users to the SCIM app even if they're not assigned to the corresponding SSO connection. Those users can't sign in through SSO.
* Disable social auth when using SCIM. If social auth (GitHub or GitLab) remains enabled, those users' access is still controlled by their GitHub org or GitLab group membership.
* Removing a user from only one role-suffixed push group removes them from the Semgrep team, even if they remain in other role-type groups for that team in Okta.
* Renaming or deleting only one role-suffixed push group renames or deletes the Semgrep team and leaves other role-type groups in Okta unmapped. Always update all role types together.
## See also