Enterprise owners can join organizations owned by their enterprise + revoke enterprise membership (#24145)

lecoursen · web-flow · commit 76d6afad2eed · 2022-03-02T10:20:19.000-06:00
diff --git a/assets/images/help/business-accounts/change-role-in-org.png b/assets/images/help/business-accounts/change-role-in-org.png
diff --git a/assets/images/help/business-accounts/remove-member.png b/assets/images/help/business-accounts/remove-member.png
diff --git a/content/admin/overview/about-enterprise-accounts.md b/content/admin/overview/about-enterprise-accounts.md
@@ -50,7 +50,7 @@ For more information about the management of policies for your enterprise accoun
 
 {% ifversion ghes or ghae %}
 
-From your enterprise account on {% ifversion ghae %}{% data variables.product.product_name %}{% elsif ghes %}a {% data variables.product.prodname_ghe_server %} instance{% endif %}, administrators can view enterprise membership and manage the following for the {% ifversion ghes %}{% data variables.product.prodname_ghe_server %} instance{% elsif ghae %}enterprise on {% data variables.product.prodname_ghe_managed %}{% endif %}.
+From your enterprise account on {% ifversion ghae %}{% data variables.product.product_name %}{% elsif ghes %}a {% data variables.product.prodname_ghe_server %} instance{% endif %}, administrators can view{% if remove-enterprise-members %} and manage{% endif %} enterprise membership{% if enterprise-owner-join-org %}, manage their own membership in organizations owned by the enterprise,{% endif %} and manage the following for the {% ifversion ghes %}{% data variables.product.prodname_ghe_server %} instance{% elsif ghae %}enterprise on {% data variables.product.prodname_ghe_managed %}{% endif %}.
 
 {% ifversion ghes %}
 - License usage{% endif %}
@@ -65,7 +65,7 @@ From your enterprise account on {% ifversion ghae %}{% data variables.product.pr
 
 {% endif %}
 
-{% ifversion ghec or ghes %}When you try or purchase {% data variables.product.prodname_enterprise %}, you can{% ifversion ghes %} also{% endif %} create an enterprise account for {% data variables.product.prodname_ghe_cloud %} on {% data variables.product.prodname_dotcom_the_website %}. Administrators for the enterprise account on {% data variables.product.prodname_dotcom_the_website %} can view membership and manage the following for the enterprise account{% ifversion ghes %} on {% data variables.product.prodname_dotcom_the_website %}{% endif %}.
+{% ifversion ghec or ghes %}When you try or purchase {% data variables.product.prodname_enterprise %}, you can{% ifversion ghes %} also{% endif %} create an enterprise account for {% data variables.product.prodname_ghe_cloud %} on {% data variables.product.prodname_dotcom_the_website %}. Administrators for the enterprise account on {% data variables.product.prodname_dotcom_the_website %} can view {% if remove-enterprise-members %} and manage{% endif %} enterprise membership{% if enterprise-owner-join-org %}, manage their own membership in organizations owned by the enterprise,{% endif %} and manage the following for the enterprise account{% ifversion ghes %} on {% data variables.product.prodname_dotcom_the_website %}{% endif %}.
 
 - Billing and usage (services on {% data variables.product.prodname_dotcom_the_website %}, {% data variables.product.prodname_GH_advanced_security %}, user licenses)
 - Security (single sign-on, IP allow lists, SSH certificate authorities, two-factor authentication)
diff --git a/content/admin/user-management/managing-organizations-in-your-enterprise/index.md b/content/admin/user-management/managing-organizations-in-your-enterprise/index.md
@@ -25,6 +25,7 @@ children:
   - /adding-people-to-teams
   - /viewing-the-audit-logs-for-organizations-in-your-enterprise
   - /streaming-the-audit-logs-for-organizations-in-your-enterprise-account
+  - /managing-your-role-in-an-organization-owned-by-your-enterprise
   - /removing-users-from-teams-and-organizations
   - /removing-organizations-from-your-enterprise
   - /restoring-a-deleted-organization
diff --git a/content/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise.md b/content/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise.md
@@ -0,0 +1,54 @@
+---
+title: Managing your role in an organization owned by your enterprise
+intro: You can manage your membership in any organization owned by your enterprise and change your role within the organization.
+permissions: Enterprise owners can manage their role in an organization owned by the enterprise.
+versions:
+  feature: enterprise-owner-join-org
+type: how_to
+topics:
+  - Administrator
+  - Enterprise
+  - Organizations
+shortTitle: Manage your organization roles
+---
+
+{% note %}
+
+**Note:** The ability for enterprise owners to manage their role in an organization owned by the enterprise is in beta and subject to change.
+
+{% endnote %}
+
+## About role management
+
+You can choose to join an organization owned by your enterprise as a member or as an organization owner, change your role within the organization, or leave the organization.
+
+{% warning %}
+
+**Warning**: If an organization uses SCIM to provision users, joining the organization this way could have unintended consequences. For more information, see "[About SCIM](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim)."
+
+{% endwarning %}
+
+## Managing your role with the enterprise settings
+
+You can join an organization owned by your enterprise and manage your role within the organization, directly from the settings for your enterprise account.
+
+If an organization enforces SAML single sign-on (SSO), you cannot use the enterprise settings to join the organization. Instead, you must join the organization using that organization's identity provider (IdP). Then, you can manage your role in your enterprise settings. For more information, see "[Joining an organization that enforces SAML SSO](#joining-an-organization-that-enforces-saml-sso)."
+
+{% data reusables.enterprise-accounts.access-enterprise %}
+1. On the **Organizations** tab, to the right of the organization you want to manage your role in, select the {% octicon "gear" aria-label="The gear icon" %} dropdown menu and click the action you want to take.
+
+   ![Screenshot of the dropdown menu for the gear icon for an organization](/assets/images/help/business-accounts/change-role-in-org.png)
+
+## Joining an organization that enforces SAML SSO
+
+If an organization enforces SAML SSO, you cannot use the enterprise settings to join the organization. Instead, you must join the organization using that organization's identity provider (IdP).
+
+1. You must be assigned access in your IdP to the application for {% data variables.product.prodname_ghe_cloud %} that is used by the organization. If you're unable to configure your IdP yourself, contact your IdP administrator.
+1. Authenticate to the organization using SAML SSO.
+
+   - If the organization uses SCIM, accept the organization invitation that will be generated by the SCIM integration.
+   - If the organization does not use SCIM, visit the following URL, replacing ORGANIZATION with the name of the organization, then follow the prompts to authenticate.
+
+    `https://github.com/orgs/ORGANIZATION/sso`
+
+After you've joined the organization, you can use the enterprise settings to manage your role in the organization, such as becoming an organization owner. For more information, see "[Managing your role with the enterprise settings](#managing-your-role-with-the-enterprise-settings)."
diff --git a/content/admin/user-management/managing-users-in-your-enterprise/index.md b/content/admin/user-management/managing-users-in-your-enterprise/index.md
@@ -27,6 +27,7 @@ children:
   - /viewing-and-managing-a-users-saml-access-to-your-enterprise
   - /auditing-users-across-your-enterprise
   - /impersonating-a-user
+  - /removing-a-member-from-your-enterprise
   - /managing-dormant-users
   - /suspending-and-unsuspending-users
   - /placing-a-legal-hold-on-a-user-or-organization
diff --git a/content/admin/user-management/managing-users-in-your-enterprise/removing-a-member-from-your-enterprise.md b/content/admin/user-management/managing-users-in-your-enterprise/removing-a-member-from-your-enterprise.md
@@ -0,0 +1,39 @@
+---
+title: Removing a member from your enterprise
+intro: 'You can remove a member from all organizations owned by your enterprise.'
+permissions: Enterprise owners can remove an enterprise member from the enterprise.
+versions:
+  feature: 'remove-enterprise-members'
+type: how_to
+topics:
+  - Enterprise
+shortTitle: Remove member
+---
+
+{% note %}
+
+**Note:** The ability to remove enterprise members is in beta and subject to change.
+
+{% endnote %}
+
+## About removal of enterprise members
+
+When you remove an enterprise member from your enterprise, the member is removed from all organizations owned by your enterprise.
+
+If the enterprise member you're removing is the last owner of an organization owned by your enterprise, you will become an owner of that organization.
+
+If your enterprise or any of the organizations owned by your enterprise uses an identity provider (IdP) to manage organization membership, the member may be added back to the organization by the IdP. Make sure to also make any necessary changes in your IdP.
+
+## Removing a member from your enterprise
+
+{% note %}
+
+**Note:** If an enterprise member uses only {% data variables.product.prodname_ghe_server %}, and not {% data variables.product.prodname_ghe_cloud %}, you cannot remove the enterprise member this way.
+
+{% endnote %}
+
+{% data reusables.enterprise-accounts.access-enterprise %}
+{% data reusables.enterprise-accounts.people-tab %}
+1. To the right of the person you want to remove, select the {% octicon "gear" aria-label="The gear icon" %} dropdown menu and click **Remove from enterprise**.
+
+   ![Screenshot of the "Remove from enterprise" option for an enterprise member](/assets/images/help/business-accounts/remove-member.png)
diff --git a/content/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise.md b/content/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise.md
@@ -30,16 +30,23 @@ For more information about adding people to your enterprise, see "[Authenticatio
 
 {% endif %}
 
-## Enterprise owner
+## Enterprise owners
 
 Enterprise owners have complete control over the enterprise and can take every action, including:
 - Managing administrators
-- {% ifversion ghec %}Adding and removing {% elsif ghae or ghes %}Managing{% endif %} organizations {% ifversion ghec %}to and from {% elsif ghae or ghes %} in{% endif %} the enterprise
+- {% ifversion ghec %}Adding and removing {% elsif ghae or ghes %}Managing{% endif %} organizations {% ifversion ghec %}to and from {% elsif ghae or ghes %} in{% endif %} the enterprise{% if remove-enterprise-members %}
+- Removing enterprise members from all organizations owned by the enterprise{% endif %}
 - Managing enterprise settings
 - Enforcing policy across organizations
 {% ifversion ghec %}- Managing billing settings{% endif %}
 
+{% if enterprise-owner-join-org %}
+Enterprise owners do not have access to organization settings or content by default. To gain access, enterprise owners can join any organization owned by their enterprise. For more information, see "[Managing your role in an organization owned by your enterprise](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise)."
+
+Owners of organizations in your enterprise do not have access to the enterprise itself unless you make them enterprise owners.
+{% else %}
 Enterprise owners cannot access organization settings or content unless they are made an organization owner or given direct access to an organization-owned repository. Similarly, owners of organizations in your enterprise do not have access to the enterprise itself unless you make them enterprise owners.
+{% endif %}
 
 An enterprise owner will only consume a license if they are an owner or member of at least one organization within the enterprise. Even if an enterprise owner has a role in multiple organizations, they will consume a single license. {% ifversion ghec %}Enterprise owners must have a personal account on {% data variables.product.prodname_dotcom %}.{% endif %} As a best practice, we recommend making only a few people in your company enterprise owners, to reduce the risk to your business.
 
@@ -55,7 +62,7 @@ People with outside collaborator access to repositories owned by your organizati
 
 {% ifversion ghec %}
 
-## Billing manager
+## Billing managers
 
 Billing managers only have access to your enterprise's billing settings. Billing managers for your enterprise can:
 - View and manage user licenses, {% data variables.large_files.product_name_short %} packs and other billing settings
diff --git a/content/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization.md b/content/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization.md
@@ -13,10 +13,9 @@ topics:
   - Organizations
   - Teams
 shortTitle: Remove a member
+permissions: 'Organization owners can remove members from an organization.'
 ---
 
-Only organization owners can remove members from an organization.
-
 {% ifversion fpt or ghec %}
 
 {% warning %}
@@ -66,4 +65,5 @@ To help the person you're removing from your organization transition and help en
 
 ## Further reading
 
-- "[Removing organization members from a team](/articles/removing-organization-members-from-a-team)"
+- "[Removing organization members from a team](/articles/removing-organization-members-from-a-team)"{% if remove-enterprise-members %}
+- "[Removing a member from your enterprise](/admin/user-management/managing-users-in-your-enterprise/removing-a-member-from-your-enterprise)"{% endif %}
diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization.md
@@ -31,6 +31,10 @@ Organization owners have full administrative access to the organization. {% data
 
 {% endnote %}
 
+{% if enterprise-owner-join-org %}
+If your organization is owned by an enterprise account, any enterprise owner can make themself an owner of your organization. For more information, see "[Managing your role in an organization owned by your enterprise](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise)."
+{% endif %}
+
 ## Appointing an organization owner
 
 {% data reusables.profile.access_org %}
diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md
@@ -29,6 +29,10 @@ Organization-level roles are sets of permissions that can be assigned to individ
 
 You can assign individuals or teams to a variety of organization-level roles to control your members' access to your organization and its resources. For more details about the individual permissions included in each role, see "[Permissions for organization roles](#permissions-for-organization-roles)."
 
+{% if enterprise-owner-join-org %}
+If your organization is owned by an enterprise account, enterprise owners can choose to join your organization with any role. For more information, see "[Managing your role in an organization owned by your enterprise](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise)."
+{% endif %}
+
 ### Organization owners
 Organization owners have complete administrative access to your organization. This role should be limited, but to no less than two people, in your organization. For more information, see "[Maintaining ownership continuity for your organization](/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization)."
 
diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/about-scim.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/about-scim.md
@@ -28,11 +28,10 @@ These identity providers are compatible with the {% data variables.product.produ
 
 {% endnote %} 
 
+{% data reusables.scim.changes-should-come-from-idp %}
+
 {% data reusables.scim.enterprise-account-scim %}
 
 ## Further reading
 
-- "[About identity and access management with SAML single sign-on](/articles/about-identity-and-access-management-with-saml-single-sign-on)"
-- "[Connecting your identity provider to your organization](/articles/connecting-your-identity-provider-to-your-organization)"
-- "[Enabling and testing SAML single sign-on for your organization](/articles/enabling-and-testing-saml-single-sign-on-for-your-organization)"
 - "[Viewing and managing a member's SAML access to your organization](/github/setting-up-and-managing-organizations-and-teams//viewing-and-managing-a-members-saml-access-to-your-organization)"
diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management.md
@@ -11,7 +11,11 @@ shortTitle: Troubleshooting access
 
 ## Some users are not provisioned or deprovisioned by SCIM
 
-When you encounter provisioning issues with users, we recommend that you check if the users are missing SCIM metadata. If an organization member has missing SCIM metadata, then you can re-provision SCIM for the user manually through your IdP.
+When you encounter provisioning issues with users, we recommend that you check if the users are missing SCIM metadata. 
+
+{% data reusables.scim.changes-should-come-from-idp %}
+
+If an organization member has missing SCIM metadata, then you can re-provision SCIM for the user manually through your IdP.
 
 ### Auditing users for missing SCIM metadata
 
@@ -78,7 +82,7 @@ For more information on using the GraphQL API, see:
 
 ### Re-provisioning SCIM for users through your identity provider
 
-You can re-provision SCIM for users manually through your IdP. For example, to resolve provisioning errors, in the Okta admin portal, you can unassign and reassign users to the {% data variables.product.prodname_dotcom %} app. This should trigger Okta to make an API call to populate the SCIM metadata for these users on {% data variables.product.prodname_dotcom %}. For more information, see "[Unassign users from applications](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-unassign-apps.htm)" or "[Assign users to applications](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-assign-apps.htm)" in the Okta documentation.
+You can re-provision SCIM for users manually through your IdP. For example, to resolve provisioning errors for Okta, in the Okta admin portal, you can unassign and reassign users to the {% data variables.product.prodname_dotcom %} app. This should trigger Okta to make an API call to populate the SCIM metadata for these users on {% data variables.product.prodname_dotcom %}. For more information, see "[Unassign users from applications](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-unassign-apps.htm)" or "[Assign users to applications](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-assign-apps.htm)" in the Okta documentation.
 
 To confirm that a user's SCIM identity is created, we recommend testing this process with a single organization member whom you have confirmed doesn't have a SCIM external identity. After manually updating the users in your IdP, you can check if the user's SCIM identity was created using the SCIM API or on {% data variables.product.prodname_dotcom %}. For more information, see "[Auditing users for missing SCIM metadata](#auditing-users-for-missing-scim-metadata)" or the REST API endpoint "[Get SCIM provisioning information for a user](/rest/reference/scim#get-scim-provisioning-information-for-a-user)."
 
diff --git a/data/features/enterprise-owner-join-org.yml b/data/features/enterprise-owner-join-org.yml
@@ -0,0 +1,4 @@
+versions:
+  ghec: '*'
+  ghes: '>=3.5'
+  ghae: 'issue-5740'
diff --git a/data/features/remove-enterprise-members.yml b/data/features/remove-enterprise-members.yml
@@ -0,0 +1,4 @@
+versions:
+  ghec: '*'
+  ghes: '>=3.5'
+  ghae: 'issue-5739'
diff --git a/data/reusables/scim/changes-should-come-from-idp.md b/data/reusables/scim/changes-should-come-from-idp.md
@@ -0,0 +1 @@
+If SCIM provisioning is implemented for your organization, any changes to a user's organization membership should be triggered from the identity provider. If a user is invited to an organization manually instead of by an existing SCIM integration, their user account may not get properly linked to their SCIM identity. This can prevent the user account from being deprovisioned via SCIM in the future. If a user is removed manually instead of by an existing SCIM integration, a stale linked identity will remain, which can lead to issues if the user needs to re-join the organization.
