Skip to content

Commit 6549eca

Browse files
guntripisaacmbrownheiskrstacycarterN-Usha
authored
Create new article explaining effects of deprovisioning and reinstating EMU and SCIM accounts (#53071)
Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com> Co-authored-by: isaacmbrown <isaacmbrown@github.com> Co-authored-by: Kevin Heis <heiskr@users.noreply.github.com> Co-authored-by: Stacy Carter <stacycarter@users.noreply.github.com> Co-authored-by: Usha N <n-usha@github.com> Co-authored-by: Adam Ross Russell <adamrr724@github.com> Co-authored-by: Jeff Stasko <y-me-y@github.com>
1 parent 1093b89 commit 6549eca

File tree

3 files changed

+187
-30
lines changed

3 files changed

+187
-30
lines changed

‎content/admin/managing-iam/provisioning-user-accounts-with-scim/deprovisioning-and-reinstating-users.md

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
title: Deprovisioning and reinstating users with SCIM
3+
shortTitle: Deprovision and reinstate users
4+
intro: 'Learn details about deprovisioning or reinstating users{% ifversion ghec %} with {% data variables.product.prodname_emus %}{% endif %}.'
5+
versions:
6+
ghec: '*'
7+
feature: scim-for-ghes-public-beta
8+
type: overview
9+
topics:
10+
- Accounts
11+
- Authentication
12+
- Enterprise
13+
- Identity
14+
- SSO
15+
allowTitleToDifferFromFilename: true
16+
product: 'Enterprises that use {% data variables.product.prodname_emus %}, or {% data variables.product.prodname_ghe_server %} instances with SCIM enabled'
17+
---
18+
19+
{% data reusables.scim.ghes-beta-note %}
20+
21+
If you {% ifversion ghec %}use {% data variables.product.prodname_emus %}{% else %}have enabled SCIM for {% data variables.location.product_location %}{% endif %}, you will use SCIM to:
22+
23+
* Deprovision users and groups to remove their access.
24+
* Reprovision users that were previously deprovisioned.
25+
26+
Before you deprovision a user, it's important to understand the effects of deprovisioning, which depend on the **type of deprovisioning API call** that {% data variables.product.github %} receives from your identity provider.
27+
28+
>[!IMPORTANT] Before reading further, ensure you understand how your enterprise has implemented SCIM. {% data variables.product.company_short %} provides a "paved-path" application if you use a supported identity provider (IdP) for both authentication and provisioning. If you don't use a paved-path application, you will use the REST API to make SCIM requests. See {% ifversion ghec %}[AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users#identity-management-systems){% else %}[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes#supported-identity-providers){% endif %}.
29+
30+
## Types of user deprovisioning
31+
32+
When a user is deprovisioned, the {% data variables.product.github %} account is **suspended**, which means the user cannot access your enterprise. Regardless of the type of deprovisioning, a deprovisioned account is never deleted from an enterprise.
33+
34+
The type of deprovisioning call that {% data variables.product.github %} receives from your identity provider determines whether it is possible to unsuspend (reinstate) a deprovisioned user.
35+
36+
* **Soft-deprovision**: In certain scenarios, the user can be unsuspended via your SCIM integration.
37+
* **Hard-deprovision**: It is not possible to unsuspend the user. A new account must be provisioned if the person needs to regain access.
38+
39+
## Effects of deprovisioning a user
40+
41+
When you deprovision a user account, either through your IdP or the REST API, {% data variables.product.github %} will make changes to the user account.
42+
43+
### Effects of soft-deprovisioning
44+
45+
* The user is **suspended** and **loses access** to your enterprise and any private resources.
46+
* Once the user account is suspended, it will be listed on the "Suspended members" page instead of the "Members" page in the "People" section of the enterprise settings.
47+
* The user's **username is obfuscated** to a hash of the original username{% ifversion ghec %}, followed by `_SHORTCODE` for enterprises on {% data variables.product.prodname_dotcom_the_website %}{% endif %}.
48+
* With Entra ID, the user's email address remains the same. In all other cases, the user's email is obfuscated.
49+
* The user's SCIM identity remains linked to their user account on {% data variables.product.github %}. With Entra ID, the value of the `active` attribute value in their stored linked SCIM identity is updated from `True` to `False`.
50+
* If the user has forks of private or internal repositories, the forks are deleted within 24 hours. The forks will be restored if the user is unsuspended within 90 days.
51+
* If the user is a member of any SCIM-provisioned IdP groups, they are hidden from these groups, and removed from any teams that are mapped to these groups. Note that this happens even if the user is still a member of the group on the IdP side.
52+
* If organization membership is managed by IdP groups, the user will be **removed from organizations** when removed from those IdP groups or removed from all teams that are mapped to IdP groups in the organization.
53+
* If organization membership is managed directly, the user will remain as a "suspended member" of the organization, without access, **until removed manually**.
54+
55+
{% ifversion ghec %}
56+
An enterprise owner can gain temporary access to a suspended member's private repositories (this includes both user namespace repositories and forks that have not yet been deleted). See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise).
57+
{% endif %}
58+
59+
### Effects of hard-deprovisioning
60+
61+
* The user is **suspended** and **loses access** to your enterprise and any private resources.
62+
* Once the user account is suspended, it will be listed on the "Suspended members" page instead of the "Members" page in the "People" section of the enterprise settings.
63+
* The user's **username is obfuscated** to a hash of the original username{% ifversion ghec %}, followed by `_SHORTCODE` for enterprises on {% data variables.product.prodname_dotcom_the_website %}{% endif %}.
64+
* The user's email address is obfuscated.
65+
* The user's display name is set to an empty string.
66+
* The user's linked SCIM identity, including all of the user's SCIM attributes, gets deleted.
67+
* The user's {% data variables.product.pat_generic_plural %}, {% data variables.product.pat_v2_plural %}, SSH keys, GPG keys, and application authorizations get deleted. Deleting keys can affect commit verification. See [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification#persistent-commit-signature-verification).
68+
* Repositories owned by the user are deleted.
69+
* Resources created by the user, such as comments, are **retained**.
70+
* If the user is a member of any SCIM-provisioned IdP groups, they are hidden from these groups, and removed from any teams that are mapped to these groups. Note that this happens even if the user is still a member of the group on the IdP side.
71+
* If organization membership is managed by IdP groups, the user will be **removed from organizations** when removed from those IdP groups or removed from all teams that are mapped to IdP groups in the organization.
72+
* If organization membership is managed directly, the user will remain as a "suspended member" of the organization, without access, **until removed manually**.
73+
74+
## Actions that trigger deprovisioning
75+
76+
Different actions trigger soft-deprovisioning and hard-deprovisioning, and the triggers vary by SCIM integration. Generally, most actions you take in the "paved-path" IdP applications only trigger **soft-deprovisioning**, with some exceptions.
77+
78+
### Triggers of soft-deprovisioning
79+
80+
| SCIM integration | Trigger of soft-deprovisioning |
81+
| ------------------- | ------------------------------ |
82+
| REST API | A `PUT` or `PATCH` request is sent to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`, updating a user's `active` field to `false`. |
83+
| Entra ID | A user is disabled in Entra ID, unassigned from the application, removed from all assigned groups, or soft-deleted from the tenant by the admin. For more details, see [Soft deletions](https://learn.microsoft.com/en-us/entra/architecture/recover-from-deletions#soft-deletions) in the Microsoft documentation. |
84+
| Okta | A user is unassigned from the application, removed from all assigned groups, or deactivated with the "Deactivate" button. Note that the "Suspend" button does not send a request to {% data variables.product.github %}. Okta only sends soft-deprovisioning calls. |
85+
| PingFederate | The user is suspended, disabled, or removed from the user store targeted by the provisioner. |
86+
87+
### Triggers of hard-deprovisioning
88+
89+
| SCIM integration | Trigger of hard-deprovisioning |
90+
| ------------------- | ------------------------------ |
91+
| REST API | A `DELETE` request is sent to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`. |
92+
| Entra ID | The hard-deletion of an Entra ID user account, as described in [Hard deletions](https://learn.microsoft.com/en-us/entra/architecture/recover-from-deletions#hard-deletions) in Microsoft's documentation. Entra ID users who are soft-deleted (found on the "Users > Deleted users" page of the Entra ID admin portal) are automatically hard-deleted by Entra ID 30 days after being soft-deleted. |
93+
| Okta | N/A. Okta does not send hard-deprovisioning calls. |
94+
| PingFederate | If the "Remove User Action" setting is set to "Delete" instead of "Disable" as the result of a misconfiguration, this action will send a hard-deprovisioning call. See the [PingIdentity documentation](https://docs.pingidentity.com/integrations/github/github_emu_provisioner/pf_github_emu_connector_user_and_group_management.html#user-deprovisioning). |
95+
96+
## Reinstating a user account that was soft-deprovisioned
97+
98+
To restore the user's access and account details, you can reprovision the account of a user who was **soft-deprovisioned**, as long as the IdP user account is the same. The IdP user account must be the same because a soft-deprovisioned user account is still linked to this external identity, based on the SCIM `external ID` (IdP user object ID) and SCIM `User ID`. The external identity that is linked to an individual soft-deprovisioned user account cannot be changed.
99+
100+
### Effects of reprovisioning
101+
102+
* The user is unsuspended and regains access to your enterprise.
103+
* The user's username and email address are restored.
104+
* If the user is a member of a SCIM-provisioned IdP group that is mapped to a team in an organization, the user will be added to the organization immediately after their user account is reprovisioned. If they were previously a member of the organization, their membership will be reinstated, as long as it has not been more than 90 days since they were removed. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization#items-that-are-restored-for-reinstated-members).
105+
* If the user is not a member of a SCIM-provisioned IdP group that is mapped to a team in an organization, a {% data variables.product.github %} organization owner will need to manually add their user account to the organization after they are reprovisioned.
106+
* Deleted forks are restored if the user is unsuspended up to 90 days after suspension.
107+
* Items associated with the user are restored, including:
108+
* {% data variables.product.prodname_github_apps %}, {% data variables.product.prodname_oauth_apps %}, and app authorizations
109+
* {% data variables.product.pat_generic_caps_plural %}
110+
* SSH keys
111+
* Token and key authorizations
112+
* User-owned repositories
113+
114+
### Actions that trigger reprovisioning
115+
116+
How you reprovision a user depends on your SCIM integration and the action that triggered soft-deprovisioning.
117+
118+
| SCIM implementation | Action to reprovision users |
119+
| ------------------- | --------------------------- |
120+
| Entra ID | Reenable a disabled account or reassign a user to the application, either directly or via an assigned group. Wait 40 minutes for the changes to process, or expedite with the "Provision on Demand" button. |
121+
| Okta | Reactivate the account or reassign the user to the application, either directly or via a group. |
122+
| PingFederate | Unsuspend or reenable the user in the user store, or readd the user to the datastore group or filter that is targeted by the provisioner. |
123+
| REST API | Send a `PUT` or `PATCH` request to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`, updating the user's `active` field to `true`. |
124+
125+
## Reinstating a user account that was hard-deprovisioned
126+
127+
You **cannot** restore a {% data variables.product.github %} user account that was hard-deprovisioned via SCIM. Instead, you will need to provision a new {% data variables.product.github %} account for the user.
128+
129+
You can reuse the username of the hard-deprovisioned user when provisioning the new account. However, it is not possible to merge the hard-deprovisioned user account with the new user account on {% data variables.product.github %}.
130+
131+
* If the email addresses of the hard-deprovisioned user and the new user match, {% data variables.product.github %} will attribute existing Git commits associated with the email address to the new user.
132+
* Existing resources and comments created by the original user will **not** be associated with the new user.
133+
134+
## Audit log events
135+
136+
The audit log for your enterprise displays details about activity in your enterprise. You can use the audit log to support your configuration of SCIM. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise).
137+
138+
> [!IMPORTANT] We strongly recommend that an enterprise owner enables enterprise audit log features such as audit log streaming, source IP disclosure, and the option to stream API requests. Streaming these events allows administrators to set a log retention policy that fits the needs of their business and use their preferred tooling for querying these logs.
139+
140+
### Events for soft-deprovisioning
141+
142+
When you soft-deprovision a user, the `external_identity.update` event does not appear in the audit log. The following events appear in the audit log:
143+
144+
* `user.suspend`
145+
* `user.remove_email`
146+
* `user.rename`
147+
* `external_identity.deprovision`
148+
* If the request succeeds, `external_identity.scim_api_success`
149+
* If the request fails, `external_identity.scim_api_failure`
150+
* If the user is a member of any IdP groups that are mapped to teams, `team.remove_member`
151+
* If a user's membership in an organization is managed by the IdP and they are removed from all teams that are mapped to IdP groups in the organization, `org.remove_member`
152+
153+
### Events for hard-deprovisioning
154+
155+
* `external_identity.deprovision`
156+
* `user.remove_email`
157+
* If the request succeeds, `external_identity.scim_api_success`
158+
* If the request fails, `external_identity.scim_api_failure`
159+
* If the user is a member of any IdP groups that are mapped to teams, `team.remove_member`
160+
* If a user's membership in an organization is managed by the IdP and they are removed from all teams that are mapped to IdP groups in the organization, `org.remove_member`
161+
162+
### Events for reprovisioning
163+
164+
When you reactivate a user, the `external_identity.update` event does not appear in the audit log. The following events appear in the audit log:
165+
166+
* `user.unsuspend`
167+
* `user.remove_email`
168+
* `user.rename`
169+
* `external_identity.provision`
170+
* If the request succeeds, `external_identity.scim_api_success`
171+
* If the request fails, `external_identity.scim_api_failure`
172+
* If the user is a member of a SCIM-provisioned IdP group, and this group is mapped to a team in an organization, `org.add_member`
173+
174+
## Further reading
175+
176+
* [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api)

‎content/admin/managing-iam/provisioning-user-accounts-with-scim/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ children:
1919
- /disabling-scim-provisioning-for-users
2020
- /provisioning-users-and-groups-with-scim-using-the-rest-api
2121
- /managing-team-memberships-with-identity-provider-groups
22+
- /deprovisioning-and-reinstating-users
2223
- /troubleshooting-team-membership-with-identity-provider-groups
2324
redirect_from:
2425
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users

0 commit comments

Comments
 (0)