[TEC-650] SCIM docs (hold) - #2816
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
| - **Deployment role assignment**: Map IdP groups to Semgrep roles such as **Admin**, **Member**, or **Read-only**. | ||
| - **Team creation from IdP groups** (optional): When [Teams (beta)](/deployment/teams/overview) is enabled, IdP groups that follow Semgrep's `[team]` naming convention can create Semgrep teams for project-scoped access. | ||
|
|
||
| Members provisioned through SCIM are matched and managed by email address. Users who predated the directory connection are matched to existing Semgrep accounts when they use the same SSO connection. |
There was a problem hiding this comment.
Maybe we should call out that the existing Semgrep users will need to be assigned to the directory.
"Users who predated the directory connection will be matched to their existing Semgrep accounts by email when assigned to the directory"
|
|
||
| - **User provisioning**: Create Semgrep members when users are assigned to the Semgrep application in your IdP. | ||
| - **Profile updates**: Update member profile attributes when they change in your IdP. | ||
| - **Deprovisioning**: Remove Semgrep access when users are unassigned or deactivated in your IdP. |
There was a problem hiding this comment.
nit: When a user is removed from a directory it removes access from a single Semgrep deployment, not the other deployments they could've been members of under the same organization / auth provider.
| With SCIM enabled, Semgrep supports: | ||
|
|
||
| - **User provisioning**: Create Semgrep members when users are assigned to the Semgrep application in your IdP. | ||
| - **Profile updates**: Update member profile attributes when they change in your IdP. |
There was a problem hiding this comment.
Remove Profile updates - we don't currently process any profile changes on directory user events.
|
|
||
| Before you set up SCIM, confirm you have the following: | ||
|
|
||
| - A Semgrep plan that includes SSO. Contact your Semgrep account team if you are unsure whether your plan includes SSO. |
There was a problem hiding this comment.
@andy-r2c can/should we explain that the SSO connection must be migrated?
There was a problem hiding this comment.
I think it happens to such a small subset of users that it's probably okay to leave out.
Maybe we can say something like "For some users setting up for the first time, you might encounter an error saying “Requires migrated SSO connection”" — we don’t expect that occur frequently, but if it does for you, please reach out to Support"
| - 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. | ||
| - If you add an **Admin** to a team push group, they appear in the group in Okta but not in the team in Semgrep. This is expected. |
There was a problem hiding this comment.
Maybe update to
"Deployment Admins already have implicit access to all teams, so they can't be explicitly added to a Semgrep team. Assigning a Deployment Admin to a directory group that maps to a team is not a recommended use case — the user will appear in the directory group but won't be added to the Semgrep team."
since it's not really expected it's more a consequence of an unsupported use case.
| - 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. | ||
| - Don't share a SAML/SCIM app across multiple Semgrep deployments. |
There was a problem hiding this comment.
| - Don't share a SAML/SCIM app across multiple Semgrep deployments. | |
| - Each SCIM application is designed to manage a single Semgrep deployment. If you want to build your SCIM integration into an existing SAML application, it's not recommended to do so if that SAML app is used as the SSO connection for multiple deployments. Instead, create a separate SCIM app for each deployment. |
this may be too wordy but some customers got confused thinking this meant SCIM was not designed to work when auth is shared between multiple deployments
|
|
||
| While this feature is in beta, the following limitations apply: | ||
|
|
||
| - Only Okta and Microsoft Entra ID workflows are supported. |
There was a problem hiding this comment.
Can we clarify this and say that Okta and Entra are the only ones we've tested and documented (like above), other IdPs could work but are not explicitly documented here.
| - **User provisioning**: Create Semgrep members when users are assigned to the Semgrep application in your IdP. | ||
| - **Deprovisioning**: Remove access to the Semgrep deployment when users are unassigned or deactivated in your IdP. Deprovisioning applies to the deployment connected to that directory, not to other deployments the user may belong to under the same organization or auth provider. | ||
| - **Deployment role assignment**: Map IdP groups to Semgrep roles such as **Admin**, **Member**, or **Read-only**. | ||
| - **Team creation from IdP groups** (optional): When [Teams (beta)](/deployment/teams/overview) is enabled, IdP groups that follow Semgrep's `[team]` naming convention can create Semgrep teams for project-scoped access. |
There was a problem hiding this comment.
@andy-r2c Do we want a bigger warning here on using push groups for SCIM teams based off the recent feedback we've got? This does already call out the naming convention.
We could also add: If you decide to use Teams (beta), your IdP directory groups must map to two distinct concepts in Semgrep: deployment role groups and Semgrep teams, each with their own role groups. This is why the naming convention is required, to differentiate between them.
We could add this warning to the "Manage teams" sections of the entra and okta pages instead.
| - [Admin privileges](/deployment/teams/overview#roles-and-access) for your Semgrep deployment. | ||
| - Permission in your identity provider to manage the Semgrep application. See [SCIM provisioning with Okta](/kb/semgrep-appsec-platform/scim-okta#prerequisites) or [SCIM provisioning with Microsoft Entra ID](/kb/semgrep-appsec-platform/scim-microsoft-entra-id#prerequisites) for provider-specific requirements. | ||
| - Optional: Enable [Teams (beta)](/deployment/teams/overview) only if you want SCIM to create and manage Semgrep teams from IdP groups. Teams isn't required for user provisioning or deployment-level role mapping. | ||
|
|
There was a problem hiding this comment.
Can we add that SCIM is not available to single-tenant customers?
@andy-r2c is "single-tenant" that right customer-facing terminology?
| ## Limitations | ||
|
|
||
| While this feature is in beta, the following limitations apply: | ||
|
|
There was a problem hiding this comment.
Another callout on push groups for teams (for both okta and entra)
"Make sure the group intended to trigger team creation includes the naming convention [team:<role>] Otherwise, it will be treated only as a group for deployment-role mapping. Team creation won’t be triggered by renaming a group already assigned to match the naming convention. To trigger team creation, create new groups with the correct naming convention from the start, then assign those to the application."
| Members provisioned through SCIM are matched and managed by email address. Users who predated the directory connection are matched to their existing Semgrep accounts by email when assigned to the directory. | ||
|
|
||
| ## How SCIM works with SSO | ||
|
|
There was a problem hiding this comment.
Do you think a note on users need to be also be assigned to the SSO app here would be helpful here too? Or maybe in the SCIM and Okta Manage users section? It's already called out later on https://github.com/semgrep/semgrep-docs/pull/2816/changes#diff-99259a80e487374b02476c621dbd0d686063c6f45f1ed169c10211e53945f9f8R254
@andy-r2c
3 participants
Preview