Repository navigation
Conversation
…er-scim-ga-updates-for-okta Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Mark Drake <mark@chainguard.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
| @@ -49,17 +49,19 @@ chainctl iam identity-providers scim enable $IDENTITY_PROVIDER | |||
|
|
|||
| Generate the token first: `scim enable` fails with `etag: etag is required` if the identity provider has no token issued yet. If it instead fails with a message about owner-tier identities, your organization doesn't yet have two directly assigned owners; refer to the [prerequisites for SCIM provisioning](/platform/administration/custom-idps/scim-provisioning/scim-overview/#prerequisites). | |||
There was a problem hiding this comment.
Enabling SCIM needs at least one owner who can sign in and whose owner role is assigned directly (not through SCIM or a group mapping), not two. The same "two owners" wording is at okta-scim line 24 and scim-overview.md lines 40 and 71, outside this diff. Two is a good recommendation, but it isn't enforced.
| Then map the Okta group to a Chainguard role. Replace `<okta_group_name>` with the group's name exactly as it appears in Okta, and `<role_name>` with the role to grant, such as `viewer` or `editor`: | ||
|
|
||
| ```sh | ||
| chainctl iam external-group-role-mappings create \ |
There was a problem hiding this comment.
Two additions: the mapping must use the group's name as it was first pushed, and you can only map a role you already hold. owner and support are never granted through SCIM: a mapping to either is accepted but gives no access.
| ``` | ||
|
|
||
| {{< note >}} | ||
| Okta doesn't send a stable identifier for groups, so Chainguard matches a pushed group by its name. If you rename the group in Okta, the mapping stops matching, and Chainguard reports no error. After a rename, create a mapping for the new name. |
There was a problem hiding this comment.
This is the reverse of what happens. After a rename the group keeps the name it had at its first push as the key, so the existing mapping keeps working and a mapping for the new name matches nothing.
Suggested: "Okta doesn't send a stable identifier for groups, so Chainguard identifies a group by its name the first time it is pushed, matched exactly including case. If you rename the group in Okta, the mapping keeps working under the original name, so keep using the original name in mappings. You can't reuse the original name for a new group until you unlink the original with Delete the group in the target app."
| 1. If you set up the provisioning app before group push was available, open its **Provisioning** tab, select **Integration**, click **Edit**, and select **Push Groups** under **Supported provisioning actions**. | ||
| 2. On the provisioning app's **Assignments** tab, click **Assign** > **Assign to Groups**, and assign the group. Okta pushes group membership only for users assigned to the app, and assigning the group also provisions its members as Chainguard users. | ||
| 3. On the **Push Groups** tab, click **Push Groups** > **Find groups by name**, and enter the group's name. | ||
| 4. Leave **Push group memberships immediately** selected, and click **Save**. |
There was a problem hiding this comment.
Worth adding how to retire a group. Delete the group in the target app removes the group and the roles only it granted. Leave the group in the target app sends nothing, so the group and its roles stay as they were and people removed from it later keep their roles. Deleting a group never deprovisions its members: unassign them from the app to remove them.
|
|
||
| The group's **Push Status** changes to **Active** once Okta has pushed it. | ||
|
|
||
| ### Verify the role bindings |
There was a problem hiding this comment.
Two additions. A new mapping or a membership change takes up to about five minutes to apply, and a person's first sign-in applies theirs immediately. And chainctl iam identity-providers scim groups list $IDENTITY_PROVIDER shows the pushed group, its name and member count, so readers can confirm the group arrived before anyone has signed in.
|
|
||
| To confirm that removal works, remove the member from the group in Okta, then list the role bindings again. Chainguard deletes the binding shortly after Okta sends the change. | ||
|
|
||
| If you assigned the member to the provisioning app only through the group, removing them from the group also deactivates their Chainguard user. Okta doesn't remove a deactivated user from the group it pushed, so the user can get the group's role back if they're reactivated. If that happens, open the **Push Groups** tab and select **Push now** from the group's **Push Status** menu. Okta then sends the group's current membership, and Chainguard removes the role. |
There was a problem hiding this comment.
The workaround is right, but the cause is slightly different. Okta deactivates the user without sending a membership removal, so Chainguard still holds the membership, and after reactivation the role is restored from it, normally within about five minutes. Push now makes Okta send the group's current members, which removes the stale member.
Suggested: "...the user can get the group's role back a few minutes after they're reactivated. To prevent this, select Push now before you reactivate the user."
| * **Deactivation takes effect at the user's next login or token refresh.** When your IdP deactivates or unassigns a provisioned user, their current access token runs out on its own schedule (up to an hour), and Chainguard refuses every attempt to log in or refresh after the deactivation. Reactivating the user in your IdP restores their ability to log in; it does not restore any role bindings that were removed while they were deactivated. | ||
| * **Provisioning does not assign roles.** A provisioned user who logs in gets the identity provider's default role, plus any group-mapped roles and role bindings they hold, same as any other user. | ||
| * **Deactivation takes effect at the user's next login or token refresh.** When your IdP deactivates or unassigns a provisioned user, their current access token runs out on its own schedule (up to an hour), and Chainguard refuses every attempt to log in or refresh after the deactivation. Reactivating the user in your IdP restores their ability to log in; it does not restore any role bindings that were removed while they were deactivated. Bindings from Okta group push are the exception: Chainguard re-creates them from the user's group memberships. | ||
| * **Provisioning assigns roles only through pushed groups.** A provisioned user who logs in gets any group-mapped roles and role bindings they hold, same as any other user. With Okta, they also get role bindings from the groups Okta pushes, as described in [Push groups to grant roles](/platform/administration/custom-idps/scim-provisioning/okta-scim/#step-5-push-groups-to-grant-roles). Enabling SCIM clears the identity provider's default role. |
There was a problem hiding this comment.
"Chainguard re-creates them from the user's group memberships" should add "within a few minutes", since a background process restores them.
This branch was successfully deployed
2 participants
[ ] Check if this is a typo or other quick fix and ignore the rest :)
Type of change
Documentation Update
What should this PR do?
resolves https://linear.app/chainguard/issue/DOCS-270/customer-facing-docs-cover-scim-ga-updates-for-okta
Documents Okta SCIM group push, which grants Chainguard roles from Okta groups, for the SCIM GA release.
Why are we making this change?
At GA, Okta can push groups over SCIM, and Chainguard grants mapped roles as persistent role bindings. The published pages said the opposite: that SCIM assigns no roles and that readers should leave group push turned off.
What are the acceptance criteria?
/Groupsenabled.Open questions for reviewers. I tested everything on staging, but these points rest on observed behavior rather than a spec:
chainctl iam external-group-role-mappings createfor SCIM groups, although its--external-group-idhelp still describes a token claim value.How should this PR be tested?
Any documentation published to Chainguard Academy is reviewed carefully for accuracy. GUI procedures, API commands, and CLI code snippets in a draft are run and tested thoroughly — by both the author and the reviewer — to confirm they work exactly as written. This helps ensure that readers can follow along and get the same results. See the
edurepo's README./Groupsis enabled. During testing, staging (chainops.dev) supported it and production returned501.🤖 Generated with Claude Code