GitHub Enterprise Server 3.14 release candidate (#51664)
Co-authored-by: Sophie <29382425+sophietheking@users.noreply.github.com> Co-authored-by: Laura Coursen <lecoursen@github.com> Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Co-authored-by: Pallavi <96553709+pallsama@users.noreply.github.com> Co-authored-by: Casey Tucker <dctucker@github.com> Co-authored-by: Hao Jiang <45571951+jianghao0718@users.noreply.github.com> Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com> Co-authored-by: Hirsch Singhal <1666363+hpsin@users.noreply.github.com> Co-authored-by: docs-bot <77750099+docs-bot@users.noreply.github.com> Co-authored-by: Florin Coada <coadaflorin@github.com> Co-authored-by: Devin Dooley <dooleydevin@github.com> Co-authored-by: Greg Padak <gpadak@github.com> Co-authored-by: Taylor Reis <taylorreis@github.com> Co-authored-by: Steve Guntrip <stevecat@github.com>
This commit is contained in:
Isaac Brown
@@ -22,7 +22,7 @@ redirect_from:
|
||||
After you disable SAML or OIDC SSO and SCIM provisioning for your enterprise, the following effects apply:
|
||||
|
||||
* All external identities for the enterprise will be removed. For more information, see "[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise)."
|
||||
* All {% data variables.enterprise.prodname_managed_users %} will be suspended. The suspended accounts will not be renamed. For more information, see "[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-suspended-members-in-an-enterprise-with-managed-users)."
|
||||
* All {% data variables.enterprise.prodname_managed_users %} will be suspended. The suspended accounts will not be renamed. For more information, see "[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-suspended-members)."
|
||||
* All {% data variables.product.pat_generic_plural %} and SSH keys associated with {% data variables.enterprise.prodname_managed_users %} will be deleted.
|
||||
* All of the external groups provisioned by SCIM will be deleted. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups)."
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ children:
|
||||
- /using-ldap-for-enterprise-iam
|
||||
- /using-saml-for-enterprise-iam
|
||||
- /configuring-authentication-for-enterprise-managed-users
|
||||
- /provisioning-user-accounts-for-enterprise-managed-users
|
||||
- /provisioning-user-accounts-with-scim
|
||||
- /reconfiguring-iam-for-enterprise-managed-users
|
||||
- /managing-recovery-codes-for-your-enterprise
|
||||
---
|
||||
|
||||
@@ -1,93 +0,0 @@
|
||||
---
|
||||
title: Configuring SCIM provisioning for Enterprise Managed Users
|
||||
shortTitle: Configure SCIM provisioning
|
||||
intro: 'You can manage the lifecycle of your enterprise''s user accounts on {% data variables.location.product_location %} from your identity provider (IdP) using System for Cross-domain Identity Management (SCIM).'
|
||||
product: '{% data reusables.gated-features.emus %}'
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Accounts
|
||||
- Enterprise
|
||||
---
|
||||
|
||||
## About provisioning for {% data variables.product.prodname_emus %}
|
||||
|
||||
{% data reusables.enterprise_user_management.about-scim-provisioning %}
|
||||
|
||||
After you configure provisioning for {% data variables.product.prodname_emus %}, your IdP uses SCIM to provision user accounts on {% data variables.location.product_location %} and add the accounts to your enterprise. If you assign a group to the application, your IdP will provision new {% data variables.enterprise.prodname_managed_users %} for all members of the group.
|
||||
|
||||
{% ifversion emu-public-scim-schema %}
|
||||
|
||||
If you use a partner IdP, you can simplify the configuration of SCIM provisioning by using the partner IdP's application. If you don't use a partner IdP for provisioning, you can implement SCIM using calls to {% data variables.product.company_short %}'s REST API for SCIM, which is in beta and subject to change. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users#about-authentication-and-user-provisioning)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
SCIM manages the lifecycle of user accounts in your enterprise. When you update information associated with a user's identity on your IdP, your IdP will update the user's account on {% data variables.product.prodname_dotcom %}. When you unassign the user from the IdP application for {% data variables.product.prodname_emus %} or deactivate a user's account on your IdP, your IdP will communicate with {% data variables.product.prodname_dotcom %} to invalidate any sessions and disable the member's account. The disabled account's information is maintained and their username is changed to a hash of their original username with the short code appended. If you reassign a user to the IdP application for {% data variables.product.prodname_emus %} or reactivate their account on your IdP, the {% data variables.enterprise.prodname_managed_user %} on {% data variables.product.prodname_dotcom %} will be reactivated, and the username will be restored.
|
||||
|
||||
To configure team and organization membership, repository access, and permissions on {% data variables.product.product_name %}, you can use groups on your IdP. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups)."
|
||||
|
||||
## Prerequisites
|
||||
|
||||
If you're configuring SCIM provisioning for a new enterprise, make sure to complete all previous steps in the initial configuration process. See "[AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users)."
|
||||
|
||||
## Configuring provisioning for {% data variables.product.prodname_emus %}
|
||||
|
||||
After creating your {% data variables.product.pat_generic %} and storing it securely, you can configure provisioning on your IdP. {% ifversion emu-public-scim-schema %} The instructions you should follow differ depending on whether you use a partner IdP's application for both authentication and provisioning.
|
||||
|
||||
* [Configuring provisioning if you use a partner IdP's application](#configuring-provisioning-if-you-use-a-partner-idps-application)
|
||||
* [Configuring provisioning for other identity management systems](#configuring-provisioning-for-other-identity-management-systems)
|
||||
|
||||
### Configuring provisioning if you use a partner IdP's application
|
||||
|
||||
To use a partner IdP's application both authentication and provisioning, review the partner's instructions for configuring provisioning in the links in the following table. {% else %} For instructions about the configuration of provisioning on your IdP, click a link in the following table.
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% rowheaders %}
|
||||
|
||||
| IdP | SSO method | More information |
|
||||
|---|---|---|
|
||||
| Microsoft Entra ID (previously known as Azure AD) | OIDC | [Tutorial: Configure GitHub Enterprise Managed User (OIDC) for automatic user provisioning](https://docs.microsoft.com/azure/active-directory/saas-apps/github-enterprise-managed-user-oidc-provisioning-tutorial) on Microsoft Learn |
|
||||
| Entra ID | SAML | [Tutorial: Configure GitHub Enterprise Managed User for automatic user provisioning](https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/github-enterprise-managed-user-provisioning-tutorial) on Microsoft Learn |
|
||||
| Okta | SAML | "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta)" |
|
||||
| PingFederate | SAML | [Configure PingFederate for provisioning and SSO](https://docs.pingidentity.com/r/en-us/pingfederate-github-emu-connector/pingfederate_github_connector_configure_pingfederate_for_provisioning_and_sso) and [Managing channels](https://docs.pingidentity.com/r/en-us/pingfederate-112/help_saasmanagementtasklet_saasmanagementstate) in the PingFederate documentation |
|
||||
|
||||
{% endrowheaders %}
|
||||
|
||||
{% ifversion emu-public-scim-schema %}
|
||||
|
||||
Alternatively, if you configured authentication on a partner IdP, but you would like to provision users from a different identity management system, you can have your IdP make calls to {% data variables.product.company_short %}'s REST API endpoints for SCIM provisioning.
|
||||
|
||||
### Configuring provisioning for other identity management systems
|
||||
|
||||
If you don't use a partner IdP, or if you only use a partner IdP for authentication, you can manage the lifecycle of user accounts using {% data variables.product.company_short %}'s REST API endpoints for SCIM provisioning. These endpoints are in beta and subject to change. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-and-groups-with-scim-using-the-rest-api)."
|
||||
|
||||
{% data reusables.emus.sign-in-as-setup-user %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: {% data reusables.enterprise-accounts.emu-password-reset-session %}
|
||||
|
||||
{% endnote %}
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.settings-tab %}
|
||||
{% data reusables.enterprise-accounts.security-tab %}
|
||||
1. Under "Open SCIM Configuration", select "Enable open SCIM configuration".
|
||||
1. Manage the lifecycle of your users by making calls to the REST API endpoints for SCIM provisioning. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-and-groups-with-scim-using-the-rest-api)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Assigning users and groups
|
||||
|
||||
{% data reusables.enterprise-managed.assigning-users %}
|
||||
|
||||
{% data reusables.enterprise-managed.assigning-roles %}
|
||||
|
||||
Entra ID does not support provisioning nested groups. For more information, see [How Application Provisioning works in Microsoft Entra ID](https://learn.microsoft.com/entra/identity/app-provisioning/how-provisioning-works#assignment-based-scoping) on Microsoft Learn.
|
||||
@@ -1,115 +0,0 @@
|
||||
---
|
||||
title: Configuring SCIM provisioning with Okta
|
||||
shortTitle: SCIM using Okta
|
||||
intro: 'If you use Okta as an identity provider (IdP), you can manage the lifecycle of your enterprise''s user accounts on {% data variables.location.product_location %} using System for Cross-domain Identity Management (SCIM).'
|
||||
product: '{% data reusables.gated-features.emus %}'
|
||||
versions:
|
||||
ghec: '*'
|
||||
redirect_from:
|
||||
- /early-access/github/articles/configuring-provisioning-for-managed-users-with-okta
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-with-okta
|
||||
type: tutorial
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- SSO
|
||||
---
|
||||
|
||||
## About provisioning with Okta
|
||||
|
||||
If you use Okta as an IdP, you can use Okta's application to provision user accounts, manage enterprise membership, and manage team memberships for organizations in your enterprise. Okta is a partner IdP, so you can simplify your authentication and provisioning configuration by using the Okta application for {% data variables.product.prodname_emus %}. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users#about-authentication-and-user-provisioning)."
|
||||
|
||||
{% ifversion emu-public-scim-schema %}
|
||||
|
||||
Alternatively, if you only intend to use Okta for SAML authentication and you want to use a different IdP for provisioning, you can integrate with {% data variables.product.prodname_dotcom %}'s REST API for SCIM. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-with-scim-using-the-rest-api)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
For more information about provisioning for {% data variables.product.prodname_emus %}, see "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users)."
|
||||
|
||||
## Supported features
|
||||
|
||||
{% data variables.product.prodname_emus %} supports the following provisioning features for Okta.
|
||||
|
||||
| Feature | Description |
|
||||
| --- | --- |
|
||||
| Push New Users | Users that are assigned to the {% data variables.product.prodname_emu_idp_application %} application in Okta are automatically created in the enterprise on {% data variables.product.product_name %}. |
|
||||
| Push Profile Update | Updates made to the user's profile in Okta will be pushed to {% data variables.product.product_name %}. |
|
||||
| Push Groups | Groups in Okta that are assigned to the {% data variables.product.prodname_emu_idp_application %} application as Push Groups are automatically created in the enterprise on {% data variables.product.product_name %}. |
|
||||
| Push User Deactivation | Unassigning the user from the {% data variables.product.prodname_emu_idp_application %} application in Okta will disable the user on {% data variables.product.product_name %}. The user will not be able to sign in, but the user's information is maintained. |
|
||||
| Reactivate Users | Users in Okta whose Okta accounts are reactivated and who are assigned back to the {% data variables.product.prodname_emu_idp_application %} application will be enabled. |
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** {% data variables.product.prodname_emus %} does not support modifications to usernames.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
{%- ifversion emu-public-scim-schema %}
|
||||
|
||||
* You must use Okta's application for both authentication and provisioning.
|
||||
|
||||
{%- endif %}
|
||||
* {% data reusables.scim.your-okta-product-must-support-scim %}
|
||||
|
||||
* {% data reusables.scim.use-pat-from-setup-user %}
|
||||
|
||||
## Setting your enterprise name
|
||||
|
||||
After your {% data variables.enterprise.prodname_emu_enterprise %} has been created, you can begin to configure provisioning by setting your enterprise name in Okta.
|
||||
|
||||
1. Navigate to your {% data variables.product.prodname_emu_idp_application %} application on Okta.
|
||||
1. Click the **Sign On** tab.
|
||||
1. To make changes, click **Edit**.
|
||||
1. Under "Advanced Sign-on Settings", in the "Enterprise Name" text box, type your enterprise name. For example, if you access your enterprise at `https://github.com/enterprises/octoinc`, your enterprise name would be "octoinc".
|
||||
1. To save your enterprise name, click **Save**.
|
||||
|
||||
## Configuring provisioning
|
||||
|
||||
After setting your enterprise name, you can proceed to configure provisioning settings.
|
||||
|
||||
To configure provisioning, the setup user with the **@<em>SHORT-CODE</em>_admin** username will need to provide a {% data variables.product.pat_v1 %} with the **admin:enterprise** scope. For more information on creating a new token, see "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users#creating-a-personal-access-token)."
|
||||
|
||||
1. Navigate to your {% data variables.product.prodname_emu_idp_application %} application on Okta.
|
||||
1. Click the **Provisioning** tab.
|
||||
1. In the settings menu, click **Integration**.
|
||||
1. To make changes, click **Edit**.
|
||||
1. Select **Enable API integration**.
|
||||
1. In the "API Token" field, enter the {% data variables.product.pat_v1 %} with the **admin:enterprise** scope belonging to the setup user.
|
||||
|
||||
{% data reusables.scim.import-groups-unsupported %}
|
||||
|
||||
1. Click **Test API Credentials**. If the test is successful, a verification message will appear at the top of the screen.
|
||||
1. To save the token, click **Save**.
|
||||
1. In the settings menu, click **To App**.
|
||||
1. To the right of "Provisioning to App", to allow changes to be made, click **Edit**.
|
||||
1. Select **Enable** to the right of **Create Users**, **Update User Attributes**, and **Deactivate Users**.
|
||||
1. To finish configuring provisioning, click **Save**.
|
||||
|
||||
## Assigning users and groups
|
||||
|
||||
{% data reusables.enterprise-managed.assigning-users %}
|
||||
|
||||
{% data reusables.scim.emu-scim-rate-limit %}
|
||||
|
||||
You can also automatically manage organization membership by adding groups to the "Push Groups" tab in Okta. When the group is provisioned successfully, it will be available to connect to teams in the enterprise's organizations. For more information about managing teams, see "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups)."
|
||||
|
||||
{% data reusables.enterprise-managed.assigning-roles %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** You can only set the "Roles" attribute for an individual user, not a group. If you want to set roles for everyone in a group that's assigned to the {% data variables.product.prodname_emu_idp_application %} application, you must use the "Roles" attribute for each group member, individually.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
## Deprovisioning users and groups
|
||||
|
||||
To remove a user or group from {% data variables.product.product_name %}, remove the user or group from both the "Assignments" tab and the "Push groups" tab in Okta. For users, make sure the user is removed from all groups in the "Push Groups" tab.
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
title: Provisioning user accounts for Enterprise Managed Users
|
||||
shortTitle: Provision managed user accounts
|
||||
product: '{% data reusables.gated-features.emus %}'
|
||||
intro: 'Learn how to provision accounts and manage organization and team membership for users of your {% data variables.enterprise.prodname_emu_enterprise %}.'
|
||||
versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Enterprise
|
||||
- Accounts
|
||||
- Authentication
|
||||
children:
|
||||
- /configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /configuring-scim-provisioning-with-okta
|
||||
- /provisioning-users-and-groups-with-scim-using-the-rest-api
|
||||
- /managing-team-memberships-with-identity-provider-groups
|
||||
- /troubleshooting-team-membership-with-identity-provider-groups
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users
|
||||
---
|
||||
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
title: Configuring authentication and provisioning with Entra ID
|
||||
shortTitle: Set up Entra ID
|
||||
intro: 'You can use a tenant in Microsoft Entra ID (previously known as Azure AD) as an identity provider (IdP) to centrally manage authentication and user provisioning for {% data variables.location.product_location %}.'
|
||||
permissions: Site administrators with admin access to the IdP
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /admin/identity-and-access-management/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-entra-id
|
||||
- /admin/managing-iam/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-entra-id
|
||||
---
|
||||
|
||||
{% data reusables.scim.ghes-beta-note %}
|
||||
|
||||
## About authentication and user provisioning with Entra ID
|
||||
|
||||
Entra ID is a service from Microsoft that allows you to centrally manage user accounts and access to web applications. For more information, see [What is Microsoft Entra ID?](https://learn.microsoft.com/entra/fundamentals/whatis) in the Microsoft Docs.
|
||||
|
||||
{% data reusables.saml.idp-saml-and-scim-explanation %}
|
||||
|
||||
For more information, see "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes)."
|
||||
|
||||
## Prerequisites
|
||||
|
||||
{% ifversion scim-for-ghes-public-beta %}
|
||||
The general prerequisites for using SCIM on {% data variables.product.product_name %} apply. See the "Prerequisites" section in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#prerequisites)."
|
||||
|
||||
In addition:
|
||||
|
||||
* To configure SCIM, you must have completed **steps 1 to 4** in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
* You will need the {% data variables.product.pat_v1 %} created for the setup user to authenticate requests from Entra ID.
|
||||
{% else %}
|
||||
* {% data reusables.saml.ghes-you-must-configure-saml-sso %}
|
||||
* {% data reusables.saml.create-a-machine-user %}
|
||||
{% endif %}
|
||||
* To configure authentication and user provisioning for {% data variables.product.product_name %} using Entra ID, you must have an Entra ID account and tenant. For more information, see the [Entra ID website](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) and [Quickstart: Set up a tenant](https://learn.microsoft.com/entra/identity-platform/quickstart-create-new-tenant) in the Microsoft Docs.
|
||||
|
||||
{% ifversion scim-for-ghes-public-beta %}
|
||||
|
||||
## 1. Configure SAML
|
||||
|
||||
>[!NOTE] Even if you have previously configured SAML on Entra ID, you will need to configure SAML and SCIM on a **new application** to enable SCIM provisioning.
|
||||
|
||||
Before starting this section, ensure you have followed steps **1 and 2** in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
|
||||
### In Entra ID
|
||||
|
||||
1. Create the "{% data variables.product.prodname_ghe_server %}" application in Entra ID. For instructions, see the "Adding {% data variables.product.prodname_ghe_server %} from the gallery" section in Microsoft's guide [Tutorial: Microsoft Entra SSO integration with GitHub Enterprise Server](https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-ae-tutorial#adding-github-enterprise-server-from-the-gallery).
|
||||
|
||||
>[!NOTE] Do **not** use the application labeled "(Legacy)."
|
||||
|
||||
1. In the "{% data variables.product.prodname_ghe_server %}" application settings, click **Single sign-on** in the left sidebar, then click **SAML**.
|
||||
1. In the "Basic SAML Configuration" section, click **Edit**, then add the following details.
|
||||
|
||||
* "Identifier": your {% data variables.product.prodname_ghe_server %} host URL (`https://HOSTNAME.com`)
|
||||
* "Reply URL": your host URL, followed by `/saml/consume` (`https://HOSTNAME.com/saml/consume`)
|
||||
|
||||
1. In the "SAML certificates" section, download the SAML certificate (Base64).
|
||||
1. In the "Set up {% data variables.product.prodname_ghe_server %}" section, make a note of the Login URL and Microsoft Entra Identifier.
|
||||
|
||||
### On {% data variables.product.product_name %}
|
||||
|
||||
1. Sign in to {% data variables.location.product_location %} as a user with access to the Management Console.
|
||||
1. Configure SAML using the information you have gathered. See "[AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso)."
|
||||
|
||||
## 2. Configure SCIM
|
||||
|
||||
Before starting this section, ensure you have followed steps **1 to 4** in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
|
||||
1. In the "{% data variables.product.prodname_ghe_server %}" application in Entra ID, click **Provisioning** in the left sidebar, then click **Get started**.
|
||||
1. Select the "Automatic" provisioning mode.
|
||||
1. In the "Admin Credentials" section, add the following details.
|
||||
|
||||
* "Tenant URL": your {% data variables.product.prodname_ghe_server %} host URL, followed by `/api/v3/scim/v2` (`https://HOSTNAME.com/api/v3/scim/v2`)
|
||||
* "Secret Token": the {% data variables.product.pat_v1 %} created for the setup user
|
||||
1. Click **Test Connection**.
|
||||
1. When the test is complete, click **Save**.
|
||||
|
||||
When you have finished configuring SCIM, you may want to disable some SAML settings you enabled for the configuration process. See "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#6-disable-optional-settings)."
|
||||
|
||||
{% else %}
|
||||
|
||||
## Configuring authentication and user provisioning with Entra ID
|
||||
|
||||
1. Configure SAML SSO for {% data variables.location.product_location %}. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso)."
|
||||
1. Configure user provisioning with SCIM for your instance. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise)."
|
||||
|
||||
## Managing enterprise owners
|
||||
|
||||
The steps to make a person an enterprise owner depend on whether you only use SAML or also use SCIM. For more information about enterprise owners, see "[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)."
|
||||
|
||||
If you configured provisioning, to grant the user enterprise ownership in {% data variables.product.product_name %}, assign the enterprise owner role to the user in Entra ID.
|
||||
|
||||
If you did not configure provisioning, to grant the user enterprise ownership in {% data variables.product.product_name %}, include the `administrator` attribute in the SAML assertion for the user account on the IdP, with the value of `true`. For more information about including the `administrator` attribute in the SAML claim from Entra ID, see [How to: customize claims issued in the SAML token for enterprise applications](https://docs.microsoft.com/azure/active-directory/develop/active-directory-saml-claims-customization) in the Microsoft Docs.
|
||||
|
||||
{% endif %}
|
||||
@@ -0,0 +1,291 @@
|
||||
---
|
||||
title: Configuring authentication and provisioning with PingFederate
|
||||
intro: 'You can use PingFederate as an identity provider (IdP) to centrally manage authentication and user provisioning for {% data variables.location.product_location %}.'
|
||||
permissions: Site administrators with admin access to the IdP
|
||||
shortTitle: Set up PingFederate
|
||||
versions:
|
||||
feature: scim-for-ghes-public-beta
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
---
|
||||
|
||||
{% data reusables.scim.ghes-beta-note %}
|
||||
|
||||
{% data reusables.saml.idp-saml-and-scim-explanation %} For more information, see "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes)."
|
||||
|
||||
## Overview
|
||||
|
||||
This guide will help you to set up both SAML authentication and SCIM provisioning for {% data variables.product.prodname_ghe_server %} on PingFederate.
|
||||
|
||||
Before you start, please note the following:
|
||||
|
||||
* The use of PingFederate as an IdP for {% data variables.product.prodname_ghe_server %} is in beta. Please contact your account team to provide feedback.
|
||||
* This guide is based on PingFederate version 12.1. Instructions may vary for other versions.
|
||||
* This guide assumes that you are using an LDAP server as the backing data store. JDBC data stores should work, but the instructions may vary slightly.
|
||||
* This guide provides the minimal steps to configure a working setup. Because your identity directory may be connected to PingFederate differently, you’ll need to pick the correct data attributes for SAML and SCIM based on what is available from your backing data store.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The general prerequisites for using SCIM on {% data variables.product.product_name %} apply. See the "Prerequisites" section in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#prerequisites)."
|
||||
|
||||
In addition:
|
||||
|
||||
* To configure SCIM, you must have completed **steps 1 to 4** in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
* You will need the {% data variables.product.pat_v1 %} created for the setup user to authenticate requests from PingFederate.
|
||||
* You must have installed the "GitHub EMU connector" on PingFederate. To download and install the connector, see [Install the connector](https://docs.pingidentity.com/r/en-us/pingfederate-github-emu-connector/pingfederate_github_connector_install_the_connector) in the PingIdentity documentation.
|
||||
* You may need to configure the firewall in PingFederate to allow outbound connections to the `https://HOSTNAME/api/v3/scim/v2` endpoint on your {% data variables.product.prodname_ghe_server %} instance.
|
||||
* PingFederate's "provisioner mode" must be set to a value that allows SCIM provisioning. See the "Before you begin" section in PingIdentity's [Configuring outbound provisioning settings](https://docs.pingidentity.com/r/en-us/pingfederate-112/help_protocolsettingstasklet_saasglobalprovisioningsettingsstate) guide.
|
||||
* During this procedure, you will need to upload an X509 certificate to PingFederate. You may want to create and store the certificate before proceeding. You will also need the challenge password for the certificate. See the "[Example of creating an X509 certificate](#example-of-creating-an-x509-certificate)" section later in this article.
|
||||
|
||||
## 1. Configure SAML
|
||||
|
||||
In this section you will create a SAML connector in PingFederate, set up an LDAP IdP adapter instance, and manage SAML output from your IdP adapter.
|
||||
|
||||
1. [Create a SAML adapter](#create-a-saml-adapter)
|
||||
1. [Set up an LDAP IdP adapter instance](#set-up-an-ldap-idp-adapter-instance)
|
||||
1. [Manage SAML output from your IdP adapter](#manage-saml-output-from-your-idp-adapter)
|
||||
|
||||
Before starting this section, ensure you have followed steps **1 and 2** in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
|
||||
### Create a SAML adapter
|
||||
|
||||
1. Open the PingFederate administrative console.
|
||||
1. Click **Applications** in the header, then click **SP Connections** in the left sidebar.
|
||||
1. Click **Use a template for this connection**, then select the "GitHub EMU Connector" from the "Connection Template" dropdown.
|
||||
|
||||
>[!NOTE] If you don't see this option, the GitHub EMU Connector has not been installed. If you need assistance, contact your Ping representative.
|
||||
1. In a new tab, sign in to your {% data variables.product.prodname_ghe_server %} instance as the built-in setup user, then navigate to `https://HOSTNAME/saml/metadata`. Download the page as an XML file.
|
||||
1. On the PingFederate "SP Connection" page, upload the file from the previous step as the metadata file. Ensure you do this within 5 minutes of downloading the file.
|
||||
1. Go to the "Connection Type" tab.
|
||||
1. Select **Browser SSO Profiles**, and deselect **Outbound provisioning** (this will be enabled later).
|
||||
1. Click **Next**.
|
||||
1. On the "Connection Options" tab, ensure only **Browser SSO** is selected.
|
||||
1. Click **Next**.
|
||||
1. On the "General Info" tab, enter the following details.
|
||||
|
||||
* "Partner’s Entity ID": your {% data variables.product.prodname_ghe_server %} host URL (`https://HOSTNAME.com`)
|
||||
* "Connection Name": A descriptive name for your SP connection within PingFederate
|
||||
* "Base URL": your {% data variables.product.prodname_ghe_server %} host URL (`https://HOSTNAME.com`)
|
||||
* "Transaction Logging": Standard
|
||||
* All other fields may be left blank.
|
||||
|
||||
1. Click **Next**.
|
||||
1. Click **Configure Browser SSO**.
|
||||
1. Click **Configure Assertion Creation**.
|
||||
1. On the "Authentication Source Mapping" tab, click **Map New Adapter Instance**.
|
||||
1. On the "Adapter Instance" Tab, click **Manage Adapter Instances**.
|
||||
1. Click **Create New Instance**.
|
||||
|
||||
### Set up an LDAP IdP adapter instance
|
||||
|
||||
>[!NOTE] This section applies if you use an LDAP server. If you don't use LDAP, you will need to connect to your adapter using the appropriate settings for your requirements.
|
||||
|
||||
1. On the "Create Adapter Instance" page on PingFederate, on the "Type" tab, enter the following details.
|
||||
|
||||
* "Instance Name": A name to identify the instance, such as `pfghadapter`
|
||||
* "Instance ID": An ID for the instance, such as `pfghadapter`
|
||||
* "Type": HTML Form IDP Adaptor
|
||||
* "Parent Instance": None
|
||||
1. Click **Next**.
|
||||
1. On the "IDP Adapter" tab, at the bottom of the page, click **Manage Password Credential Validators**.
|
||||
1. Click **Create New Instance**.
|
||||
1. On the "Type" tab, enter the following details.
|
||||
|
||||
* "Instance Name": A name to identify the instance, such as `pfghdocscv`
|
||||
* "Instance ID": An ID for the instance, such as `pfghdocscv`
|
||||
* "Type": LDAP Username Password Credential Validator
|
||||
* "Parent Instance": None
|
||||
1. Click **Next**.
|
||||
1. On the "Instance Configuration" tab, click **Manage Data Stores**.
|
||||
1. Click **Add New Data Store**.
|
||||
1. On the "Data Store Type" tab, enter the following details.
|
||||
|
||||
* "Instance Name": Any unique value, such as `pfghdocsds`
|
||||
* "Type": Directory (LDAP)
|
||||
* "Mask Values In Log": Deselected
|
||||
|
||||
1. Click **Next**.
|
||||
1. On the "LDAP Configuration" tab, configure your LDAP server details.
|
||||
1. Click **Test Connection**. You should see "Connectivity test was successful."
|
||||
1. At the bottom of the page, click **Advanced**.
|
||||
1. Click the "LDAP Binary Attributes" tab, and add `guidAttribute` and `objectGUID` as attributes.
|
||||
1. Click **Done**. You should be back on the "LDAP Configuration" tab.
|
||||
1. Click **Next**, then **Save**.
|
||||
1. On the "Manage Data Stores" tab, click **Done**.
|
||||
1. On the "Instance Configuration" tab, enter the following details.
|
||||
|
||||
* "LDAP Datastore": The name of the data store you created above
|
||||
* "Search Base": The location in the directory where you want LDAP searches to begin
|
||||
* "Search Filter": A filter that ensures the username the user enters when signing in matches a field in the LDAP server (for example: `sAMAccountName=${username}`)
|
||||
* "Scope of Search": Subtree
|
||||
* "Case-Sensitive Matching": Selected
|
||||
|
||||
1. Click **Next**, **Next** again, then **Save**.
|
||||
|
||||
### Manage SAML output from your IdP adapter
|
||||
|
||||
1. On the "Manage Password Credential Validators" page, click **Done**.
|
||||
1. On the "IDP Adapter" tab, enter the following details.
|
||||
|
||||
* "Password Credential Validator Instance": The name of the validator instance you created above (for example `pfghdocscv`). Click **Update** to finalize your selection.
|
||||
* All other fields can be left as the defaults, or modified to your requirements.
|
||||
1. Click **Next**, then **Next** again.
|
||||
1. On the "Adapter Attributes" tab, enter the following details.
|
||||
|
||||
* "Unique User Key Attribute": `username`
|
||||
* Next to the `username` attribute, select "Pseudonym".
|
||||
|
||||
>[!NOTE] This step is important. The adapter attribute is used to uniquely identify a user on your instance during SCIM provisioning.
|
||||
1. Click **Next**, then **Next** again.
|
||||
1. Review your settings on the summary page, then click **Save**.
|
||||
1. On the "IdP Adapters" tab, you should see the adapter you just created. Click **Done**.
|
||||
1. On the "Adapter Instance" tab, in the "Adapter Instance" dropdown, select the adapter you just created.
|
||||
1. Click **Next**.
|
||||
1. On the "Mapping Method" tab, select **Use only the Adapter Contract Values in the SAML Assertion** (other selections may work, but have not been confirmed).
|
||||
1. Click **Next**.
|
||||
1. On the "Attribute Contract Fulfillment" tab, map the `SAML_SUBJECT` to "Adapter" as the source and `username` as the value.
|
||||
|
||||
>[!NOTE] This step is important. The normalized `SAML_SUBJECT` will need to match the normalized usernames of users provisioned by SCIM.
|
||||
1. Click **Next**, **Next** again, then **Done**.
|
||||
1. You should be back on the "Authentication Source Mapping" tab, and the "Adapter Instance Name" section should contain the adapter instance that you just created.
|
||||
1. Click **Next** and **Done** until you reach the "Credentials" tab.
|
||||
1. On the "Credentials" tab, click **Configure Credentials**, then click **Manage Certificates**.
|
||||
1. On the "Certificate Management" page, click **Import**, then upload an X509 certificate (for help, see the "[Example of creating an X509 certificate](#example-of-creating-an-x509-certificate)" section).
|
||||
1. For the "Password," use the challenge password for the certificate.
|
||||
1. Click **Next**, then **Save**.
|
||||
1. On the "Certificate Management" tab, you should see the certificate you just imported. Click **Done**.
|
||||
1. On the "Digital Signature Settings" tab:
|
||||
|
||||
* Select the certificate you just created for the "Signing Certificate."
|
||||
* You can leave the secondary certificate blank and the "Include the certificate in the signature" checkbox deselected.
|
||||
* The signing algorithm should be "RSA SHA256."
|
||||
|
||||
1. Click **Next**, then **Done**, then **Next**.
|
||||
1. On the "Summary" tab, enable the toggle for "SSO Application Endpoint."
|
||||
1. Click **Save**. You should be taken back to the list of SP connections, where you should see your newly created SP connection.
|
||||
|
||||
### Collect information for your SAML configuration
|
||||
|
||||
You will need some details from PingFederate to configure SAML on {% data variables.product.prodname_dotcom %}.
|
||||
|
||||
1. On the "SP Connections" page, in the row for your new connection, click **Select Action**, then **Export Metadata**.
|
||||
1. On the "Metadata Signing" tab, in the row for your new connection, select the signing certificate you created above. To download the certificate, click **Next**, then click **Export**.
|
||||
1. On PingFederate, click **System** in the header, then **Server**, then **Protocol Settings**. Check that the `SAML 2.0 ENTITY ID` is defined. Make a note of this, as you will need it for the “Issuer” field in {% data variables.product.prodname_dotcom %}'s SAML settings.
|
||||
1. Open the metadata file you downloaded, and have it ready for the next steps.
|
||||
|
||||
### Configure {% data variables.product.prodname_ghe_server %}
|
||||
|
||||
1. Sign in to {% data variables.location.product_location %} as a user with access to the Management Console.
|
||||
1. Navigate to the "Authentication" section of the Management Console, then enable SAML. See "[AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso)."
|
||||
1. Enter the following values from the metadata file you downloaded in the previous section.
|
||||
|
||||
* For the "Single sign-on URL," use the `location` value of the `<md: SingleSignOnService>` field. This should be a URL ending `/idp/SSO.saml2`.
|
||||
* For the "Issuer," use the `entityId` value of the `<md: EntityDescriptor>` field (a URL).
|
||||
|
||||
1. For the "Verification certificate," upload the X509 certificate file that you created earlier.
|
||||
1. Click **Save settings**.
|
||||
|
||||
## 2. Configure SCIM
|
||||
|
||||
In this section, you'll configure SCIM settings and attribute mapping on PingFederate.
|
||||
|
||||
1. [Configure SCIM settings](#configure-scim-settings)
|
||||
1. [Map LDAP fields to SCIM](#map-ldap-fields-to-scim)
|
||||
1. [Finish configuration and test](#finish-configuration-and-test)
|
||||
|
||||
Before starting this section, ensure you have followed steps **1 to 4** in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
|
||||
### Configure SCIM settings
|
||||
|
||||
1. Go back to the "SP Connections" page on PingFederate, and select the SP connection you created earlier.
|
||||
1. Click the "Connection Type" tab.
|
||||
1. Select **Outbound Provisioning**.
|
||||
1. Ensure **Browser SSO Profiles** is selected.
|
||||
1. Click **Next** until you reach the "Outbound Provisioning" tab, then click **Configure Provisioning**.
|
||||
1. On the "Target" tab, enter the following details.
|
||||
|
||||
* "Base URL": `https://HOSTNAME/api/v3/scim/v2/`
|
||||
* "Access Token": The {% data variables.product.pat_v1 %} created for the built-in setup user
|
||||
1. Click **Next**.
|
||||
1. On the "Manage Channel" tab, click **Create**, then enter a unique channel name, such as `pfghscim`.
|
||||
1. Click **Next**.
|
||||
1. On the "Source" tab, choose the data store that you created earlier.
|
||||
1. Click **Next**.
|
||||
1. On the "Source Settings" tab, you can keep all default settings. Other settings are likely to work, but have not been confirmed.
|
||||
1. Click **Next**.
|
||||
1. On the "Source Location" tab, configure where in your LDAP server you would like provisioned users to come from. This will vary depending on your setup and needs. After configuring, click **Next**.
|
||||
|
||||
### Map LDAP fields to SCIM
|
||||
|
||||
On the "Attribute Mapping" tab, you will need to map fields from your LDAP server to SCIM fields. See the following list for {% data variables.product.prodname_dotcom %}'s supported SCIM fields and the values expected in each one.
|
||||
|
||||
* **Username**: This will be normalized and used as the {% data variables.product.company_short %} username for the provisioned user. See "[AUTOTITLE](/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication#about-username-normalization)." This must match the normalization of the subject sent with the SAML assertion that you configured with the `SAML_SUBJECT` property in PingFederate.
|
||||
* **Email**: A field containing the user's email address.
|
||||
* **Display Name**: A human-readable name for the user.
|
||||
* **Formatted Name**: The user's full name, including all middle names, titles, and suffixes, formatted for display.
|
||||
* **First Name**: The first name of the user.
|
||||
* **Last Name**: The last name of the user.
|
||||
* **External ID**: This identifier is generated by an IdP provider.
|
||||
* **Roles**: This field should contain a string that represents the user's intended role on {% data variables.product.prodname_dotcom %}. Valid roles are `enterprise_owner` and `user`.
|
||||
|
||||
When you have finished configuring these settings, click **Next**.
|
||||
|
||||
### Finish configuration and test
|
||||
|
||||
1. On the "Activation & Summary" tab, for the "Channel Status," select **Active**.
|
||||
1. On the "Manage Channels" tab, click **Done**.
|
||||
1. On the "Outbound Provisioning" tab, click **Save**. SCIM is now configured and enabled.
|
||||
1. Wait a few minutes for provisioning to run, then open a new private browser window and navigate to your instance at `https://HOSTNAME/login`.
|
||||
1. Click **Sign in with SAML**. You should be redirected to the PingFederate login page.
|
||||
1. You should be able to sign in with the credentials for a user in the LDAP server that has been provisioned to {% data variables.product.prodname_ghe_server %}.
|
||||
|
||||
PingFederate provisioning handles users and groups independently. Users must be assigned directly in order to be provisioned. Users who are in an assigned group but not directly assigned will not be provisioned.
|
||||
|
||||
When you have finished configuring SCIM, you may want to disable some SAML settings you enabled for the configuration process. See "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#6-disable-optional-settings)."
|
||||
|
||||
## Example of creating an X509 certificate
|
||||
|
||||
There are multiple ways to create an X509 certificate. Here is an example that may work for your requirements.
|
||||
|
||||
1. In a terminal window, check that OpenSSL is installed by running `openssl version`. If it's not installed, install it.
|
||||
1. Generate the private key using the following command.
|
||||
|
||||
```shell copy
|
||||
openssl req -nodes -sha256 -newkey rsa:2048 -keyout MyPrivateKey.key -out MyCertificateRequest.csr
|
||||
```
|
||||
|
||||
Enter the required information, and **take note** of the challenge password you create.
|
||||
1. To ensure the key was created, run the following command. A file named `MyPrivateKey.key` should be listed in the command output.
|
||||
|
||||
```shell copy
|
||||
ls | grep MyPrivateKey.key
|
||||
```
|
||||
|
||||
1. Generate the certificate using the following command.
|
||||
|
||||
```shell copy
|
||||
openssl x509 -req -days 365 -sha256 -in MyCertificateRequest.csr -signkey MyPrivateKey.key -out pfgh256.crt
|
||||
```
|
||||
|
||||
1. To ensure the certificate was created, run the following command. A file named `pfgh256.crt` should be listed in the command output.
|
||||
|
||||
```shell copy
|
||||
ls | grep pfgh256.crt
|
||||
```
|
||||
|
||||
1. Export a PKCS #12 file using the following command. This is the file you should **upload to PingFederate**.
|
||||
|
||||
```shell copy
|
||||
openssl pkcs12 -export -in pfgh256.crt -inkey MyPrivateKey.key -out pfgh256.p12
|
||||
```
|
||||
|
||||
1. To ensure the file was exported, run the following command. A file named `pfgh256.p12` should be listed in the command output.
|
||||
|
||||
```shell copy
|
||||
ls | grep pfgh256.p12
|
||||
```
|
||||
@@ -0,0 +1,196 @@
|
||||
---
|
||||
title: Configuring SCIM provisioning {% ifversion ghec %}for Enterprise Managed Users{% else %}to manage users{% endif %}
|
||||
shortTitle: Configure SCIM provisioning
|
||||
intro: 'You can manage the lifecycle of your enterprise''s user accounts from your identity provider (IdP) using System for Cross-domain Identity Management (SCIM).'
|
||||
allowTitleToDifferFromFilename: true
|
||||
permissions: '{% ifversion scim-for-ghes-public-beta %}Site administrators{% endif %}'
|
||||
product: '{% data reusables.gated-features.emus %}'
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
versions:
|
||||
ghec: '*'
|
||||
feature: scim-for-ghes-public-beta
|
||||
topics:
|
||||
- Accounts
|
||||
- Enterprise
|
||||
---
|
||||
|
||||
{% data reusables.scim.ghes-beta-note %}
|
||||
|
||||
{% data reusables.enterprise_user_management.about-scim-provisioning %}
|
||||
|
||||
If you use a partner IdP, you can simplify the configuration of SCIM provisioning by using the partner IdP's application. If you don't use a partner IdP for provisioning, you can implement SCIM using calls to {% data variables.product.company_short %}'s REST API for SCIM{% ifversion ghec %}, which is in beta and subject to change{% endif %}. For more information, 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 %}
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
## About user lifecycle management with SCIM
|
||||
|
||||
{% data reusables.enterprise_user_management.scim-manages-user-lifecycle %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
If you're configuring SCIM provisioning for a new enterprise, make sure to complete all previous steps in the initial configuration process. See "[AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users)."
|
||||
|
||||
{% else %}
|
||||
|
||||
* For authentication, your instance must use SAML SSO, or a mix of SAML and built-in authentication.
|
||||
* You cannot mix SCIM with other external authentication methods. If you use CAS or LDAP, you will need to migrate to SAML before using SCIM.
|
||||
* After you have configured SCIM, you must keep SAML authentication enabled to continue using SCIM.
|
||||
* You must have administrative access on your IdP to configure user provisioning for {% data variables.product.product_name %}.
|
||||
* You must have access to the Management Console on {% data variables.product.product_name %}.
|
||||
* If you are configuring SCIM on an instance with existing users, ensure you have understood how SCIM will identify and update these users. See "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes#what-will-happen-to-existing-users-on-my-instance)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% ifversion ghes %}
|
||||
|
||||
## 1. Create a built-in setup user
|
||||
|
||||
To ensure you can continue to sign in and configure settings when SCIM is enabled, you'll create an enterprise owner using built-in authentication.
|
||||
|
||||
1. Sign in to {% data variables.product.product_name %} as a user with access to the Management Console.
|
||||
1. If you have **already enabled SAML authentication**, ensure your settings allow you to create and promote a built-in setup user. Go to the "Authentication" section of the Management Console and enable the following settings:
|
||||
|
||||
* Select **Allow creation of accounts with built-in authentication**, so you can create the user.
|
||||
* Select **Disable administrator demotion/promotion**, so admin permissions can be granted outside of your SAML provider.
|
||||
|
||||
For help finding these settings, see "[AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso)."
|
||||
|
||||
1. Create a built-in user account to perform provisioning actions on your instance. See "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider#inviting-users-outside-your-provider-to-authenticate-to-your-instance)."
|
||||
|
||||
>[!NOTE] Ensure the user's email and username are different from any user you plan on provisioning through SCIM. If your email provider supports it, you can modify an email address by adding `+admin`, for example `johndoe+admin@example.com`.
|
||||
|
||||
1. Promote the user to an enterprise owner. See "[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator#promoting-a-user-from-the-enterprise-settings)."
|
||||
|
||||
## 2. Create a {% data variables.product.pat_generic %}
|
||||
|
||||
1. Sign in to your instance as the **built-in setup user** you created in the previous section.
|
||||
1. Create a {% data variables.product.pat_v1 %}. For instructions, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)."
|
||||
|
||||
* The token must have the **admin:enterprise** scope.
|
||||
* The token must have **no expiration**. If you specify an expiration date, SCIM will no longer function after the expiration date passes.
|
||||
|
||||
1. Store the token securely in a password manager until you need the token again later in the setup process. You'll need the token to configure SCIM on your IdP.
|
||||
|
||||
## 3. Enable SAML on your instance
|
||||
|
||||
> [!NOTE] Complete this section if either of the following situations applies:
|
||||
> * If you have **not already enabled SAML authentication**, you will need to do so before you can enable SCIM.
|
||||
> * If you already use SAML authentication and want to use a **partner IdP for both authentication and provisioning**, you must configure SAML using an application that supports automatic provisioning via SCIM.
|
||||
|
||||
1. Sign in to your instance as a user with access to the Management Console.
|
||||
1. Go to the "Authentication" section of the Management Console. For instructions, see "[AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso)."
|
||||
1. Select **SAML**.
|
||||
1. Configure the SAML settings according to your requirements and the IdP you're using.
|
||||
|
||||
* So the built-in setup user can continue to authenticate, ensure you select the following settings:
|
||||
* **Allow creation of accounts with built-in authentication**
|
||||
* **Disable administrator demotion/promotion**
|
||||
* If you're using a partner IdP, to find the information you need to configure the settings, follow the "Configure SAML" section of the relevant guide.
|
||||
* "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-entra-id#1-configure-saml)"
|
||||
* "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-pingfederate#1-configure-saml)"
|
||||
* "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-with-okta#1-configure-saml)"
|
||||
|
||||
1. Optionally, complete configuration of the SAML settings within the application in your IdP. Alternatively, you can leave this step until later.
|
||||
|
||||
## 4. Enable SCIM on your instance
|
||||
|
||||
1. Sign in to your instance as the **built-in setup user** you created earlier.
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.settings-tab %}
|
||||
{% data reusables.enterprise-accounts.security-tab %}
|
||||
1. Under "SCIM Configuration", select **Enable SCIM configuration**.
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
## Configuring user provisioning for {% data variables.product.prodname_emus %}
|
||||
|
||||
{% else %}
|
||||
|
||||
## 5. Configure your identity provider
|
||||
|
||||
{% endif %}
|
||||
|
||||
After completing the setup on {% data variables.product.prodname_dotcom %}, you can configure provisioning on your IdP. The instructions you should follow differ depending on whether you use a partner IdP's application for both authentication and provisioning.
|
||||
|
||||
* [Configuring provisioning if you use a partner IdP's application](#configuring-provisioning-if-you-use-a-partner-idps-application)
|
||||
* [Configuring provisioning for other identity management systems](#configuring-provisioning-for-other-identity-management-systems)
|
||||
|
||||
### Configuring provisioning if you use a partner IdP's application
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
To use a partner IdP's application both authentication and provisioning, review the partner's instructions for configuring provisioning in the links in the following table.
|
||||
|
||||
{% rowheaders %}
|
||||
|
||||
| IdP | SSO method | More information |
|
||||
|---|---|---|
|
||||
| Microsoft Entra ID (previously known as Azure AD) | OIDC | [Tutorial: Configure GitHub Enterprise Managed User (OIDC) for automatic user provisioning](https://docs.microsoft.com/azure/active-directory/saas-apps/github-enterprise-managed-user-oidc-provisioning-tutorial) on Microsoft Learn |
|
||||
| Entra ID | SAML | [Tutorial: Configure GitHub Enterprise Managed User for automatic user provisioning](https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/github-enterprise-managed-user-provisioning-tutorial) on Microsoft Learn |
|
||||
| Okta | SAML | "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta)" |
|
||||
| PingFederate | SAML | [Configure PingFederate for provisioning and SSO](https://docs.pingidentity.com/r/en-us/pingfederate-github-emu-connector/pingfederate_github_connector_configure_pingfederate_for_provisioning_and_sso) and [Managing channels](https://docs.pingidentity.com/r/en-us/pingfederate-112/help_saasmanagementtasklet_saasmanagementstate) in the PingFederate documentation |
|
||||
|
||||
{% endrowheaders %}
|
||||
|
||||
{% else %}
|
||||
|
||||
To use a partner IdP's application for both authentication and provisioning, review the instructions that are linked below. Complete the steps for enabling SCIM, plus any SAML configuration that you haven't already performed.
|
||||
|
||||
* "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-entra-id)"
|
||||
* "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-pingfederate)"
|
||||
* "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-with-okta)"
|
||||
|
||||
{% endif %}
|
||||
|
||||
### Configuring provisioning for other identity management systems
|
||||
|
||||
If you don't use a partner IdP, or if you only use a partner IdP for authentication, you can manage the lifecycle of user accounts using {% data variables.product.company_short %}'s REST API endpoints for SCIM provisioning. These endpoints are in beta and subject to change. See "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-and-groups-with-scim-using-the-rest-api)."
|
||||
|
||||
{% ifversion emu-public-scim-schema %}
|
||||
|
||||
{% data reusables.emus.sign-in-as-setup-user %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: {% data reusables.enterprise-accounts.emu-password-reset-session %}
|
||||
|
||||
{% endnote %}
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.settings-tab %}
|
||||
{% data reusables.enterprise-accounts.security-tab %}
|
||||
1. Under "Open SCIM Configuration", select "Enable open SCIM configuration".
|
||||
1. Manage the lifecycle of your users by making calls to the REST API endpoints for SCIM provisioning. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-and-groups-with-scim-using-the-rest-api)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% ifversion scim-for-ghes-public-beta %}
|
||||
|
||||
## 6. Disable optional settings
|
||||
|
||||
After you have finished the configuration process, you can disable the following settings in the Management Console:
|
||||
|
||||
* **Allow creation of accounts with built-in authentication**: Disable this setting if you want all users to be provisioned from your IdP.
|
||||
* **Disable administrator demotion/promotion**: Disable this setting if you want to be able to grant the enterprise owner role via SCIM.
|
||||
|
||||
{% endif %}
|
||||
|
||||
## {% ifversion ghec %}Assigning{% else %}7. Assign{% endif %} users and groups
|
||||
|
||||
{% data reusables.enterprise-managed.assigning-users %}
|
||||
|
||||
{% data reusables.enterprise-managed.assigning-roles %}
|
||||
|
||||
Entra ID does not support provisioning nested groups. For more information, see [How Application Provisioning works in Microsoft Entra ID](https://learn.microsoft.com/entra/identity/app-provisioning/how-provisioning-works#assignment-based-scoping) on Microsoft Learn.
|
||||
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Configuring {% ifversion ghec %}SCIM{% else %}authentication and{% endif %} provisioning with Okta
|
||||
shortTitle: Set up Okta
|
||||
intro: 'Learn how to configure Okta to communicate with your enterprise using System for Cross-domain Identity Management (SCIM).'
|
||||
product: '{% data reusables.gated-features.emus %}'
|
||||
permissions: '{% ifversion ghes %}Site administrators{% else %}People{% endif %} with admin access to the IdP'
|
||||
allowTitleToDifferFromFilename: true
|
||||
versions:
|
||||
ghec: '*'
|
||||
feature: scim-for-ghes-public-beta
|
||||
redirect_from:
|
||||
- /early-access/github/articles/configuring-provisioning-for-managed-users-with-okta
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-with-okta
|
||||
- /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-with-okta
|
||||
type: tutorial
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- SSO
|
||||
---
|
||||
|
||||
{% data reusables.scim.ghes-beta-note %}
|
||||
|
||||
## About provisioning with Okta
|
||||
|
||||
If you use Okta as an IdP, you can use Okta's application to provision user accounts, manage enterprise membership, and manage team memberships for organizations in your enterprise. Okta is a partner IdP, so you can simplify your authentication and provisioning configuration by using the Okta application {% ifversion ghec %}for {% data variables.product.prodname_emus %}. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users#about-authentication-and-user-provisioning)."{% else %}to manage both SAML single-sign on and SCIM provisioning on {% data variables.product.prodname_ghe_server %}.{% endif %}
|
||||
|
||||
Alternatively, if you only intend to use Okta for SAML authentication and you want to use a different IdP for provisioning, you can integrate with {% data variables.product.prodname_dotcom %}'s REST API for SCIM. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-with-scim-using-the-rest-api)."
|
||||
|
||||
## Supported features
|
||||
|
||||
{% ifversion ghec %}{% data variables.product.prodname_emus %}{% else %}{% data variables.product.prodname_ghe_server %}{% endif %} supports the following provisioning features for Okta.
|
||||
|
||||
| Feature | Description |
|
||||
| --- | --- |
|
||||
| Push New Users | Users that are assigned to {% ifversion ghec %}the {% data variables.product.prodname_emu_idp_application %}{% else %}{% data variables.product.company_short %}'s{% endif %} application in Okta are automatically created in the enterprise on {% data variables.product.product_name %}. |
|
||||
| Push Profile Update | Updates made to the user's profile in Okta will be pushed to {% data variables.product.product_name %}. |
|
||||
| Push Groups | Groups in Okta that are assigned to the {% ifversion ghec %}the {% data variables.product.prodname_emu_idp_application %}{% else %}{% data variables.product.company_short %}'s{% endif %} application as Push Groups are automatically created in the enterprise on {% data variables.product.product_name %}. |
|
||||
| Push User Deactivation | Unassigning the user from {% ifversion ghec %}the {% data variables.product.prodname_emu_idp_application %}{% else %}{% data variables.product.company_short %}'s{% endif %} application in Okta will disable the user on {% data variables.product.product_name %}. The user will not be able to sign in, but the user's information is maintained. |
|
||||
| Reactivate Users | Users in Okta whose Okta accounts are reactivated and who are assigned back to {% ifversion ghec %}the {% data variables.product.prodname_emu_idp_application %}{% else %}{% data variables.product.company_short %}'s{% endif %} application on Okta will be enabled. |
|
||||
|
||||
{% ifversion ghec %}
|
||||
{% note %}
|
||||
|
||||
**Note:** {% data variables.product.prodname_emus %} does not support modifications to usernames.
|
||||
|
||||
{% endnote %}
|
||||
{% endif %}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
{% ifversion ghes %}
|
||||
The general prerequisites for using SCIM on {% data variables.product.product_name %} apply. See the "Prerequisites" section in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#prerequisites)."
|
||||
|
||||
In addition:
|
||||
|
||||
* To configure SCIM, you must have completed **steps 1 to 4** in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
* You will need the {% data variables.product.pat_v1 %} created for the setup user to authenticate requests from Okta.
|
||||
{% else %}
|
||||
* {% data reusables.scim.use-pat-from-setup-user %}
|
||||
{% endif %}
|
||||
* You must use Okta's application for both authentication and provisioning.
|
||||
* {% data reusables.scim.your-okta-product-must-support-scim %}
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
## 1. Set your enterprise name
|
||||
|
||||
After your {% data variables.enterprise.prodname_emu_enterprise %} has been created, you can begin to configure provisioning by setting your enterprise name in Okta.
|
||||
|
||||
1. Navigate to your {% data variables.product.prodname_emu_idp_application %} application on Okta.
|
||||
1. Click the **Sign On** tab.
|
||||
1. To make changes, click **Edit**.
|
||||
1. Under "Advanced Sign-on Settings", in the "Enterprise Name" text box, type your enterprise name. For example, if you access your enterprise at `https://github.com/enterprises/octoinc`, your enterprise name would be "octoinc".
|
||||
1. To save your enterprise name, click **Save**.
|
||||
|
||||
{% else %}
|
||||
|
||||
## 1. Configure SAML
|
||||
|
||||
During the public beta of SCIM on {% data variables.product.prodname_ghe_server %}, you will use the **GitHub AE** application in Okta to configure SAML authentication and SCIM provisioning. Do **not** use the "{% data variables.product.prodname_ghe_server %}" application, which is incompatible with {% data variables.product.prodname_dotcom %}'s latest SCIM API endpoints.
|
||||
|
||||
Before starting this section, ensure you have followed steps **1 and 2** in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
|
||||
### In Okta
|
||||
|
||||
1. Go to the [GitHub AE](https://www.okta.com/integrations/github-ae/) application in Okta.
|
||||
1. Click **Add integration**.
|
||||
1. In the general settings, for the base URL, enter your {% data variables.product.prodname_ghe_server %} host URL (`https://HOSTNAME.com`).
|
||||
1. Click the **Sign On** tab.
|
||||
1. Ensure the "Credential Details" match the following.
|
||||
|
||||
* "Application username format": Okta username
|
||||
* "Update application username on": Create and update
|
||||
* "Password reveal": Deselected
|
||||
1. In the "SAML Signing Certificates" section, download your certificate by selecting **Actions**, then clicking **Download certificate**.
|
||||
1. On the right side of the page, click **View SAML setup instructions**.
|
||||
1. Make a note of the "Sign on URL" and the "Issuer" URL.
|
||||
|
||||
### On {% data variables.product.product_name %}
|
||||
|
||||
1. Sign in to {% data variables.location.product_location %} as a user with access to the Management Console.
|
||||
1. Configure SAML using the information you have gathered. See "[AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
## 2. Configure SCIM
|
||||
|
||||
After {% ifversion ghec %}setting your enterprise name{% else %}configuring your SAML settings{% endif %}, you can proceed to configure provisioning settings.
|
||||
|
||||
{% ifversion ghec %}
|
||||
To configure provisioning, the setup user {% ifversion ghec %}with the **@<em>SHORT-CODE</em>_admin** username {% endif %}will need to provide a {% data variables.product.pat_v1 %} with the **admin:enterprise** scope. See "[AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users#create-a-personal-access-token)."
|
||||
{% else %}
|
||||
Before starting this section, ensure you have followed steps **1 to 4** in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
{% endif %}
|
||||
|
||||
1. Navigate to your {% data variables.product.prodname_emu_idp_application %} application on Okta.
|
||||
1. Click the **Provisioning** tab.
|
||||
1. In the settings menu, click **Integration**.
|
||||
1. To make changes, click **Edit**.
|
||||
1. Click **Configure API integration**.
|
||||
1. In the "API Token" field, enter the {% data variables.product.pat_v1 %} with the **admin:enterprise** scope belonging to the setup user.
|
||||
|
||||
{% data reusables.scim.import-groups-unsupported %}
|
||||
|
||||
1. Click **Test API Credentials**. If the test is successful, a verification message will appear at the top of the screen.
|
||||
1. To save the token, click **Save**.
|
||||
1. In the settings menu, click **To App**.
|
||||
1. To the right of "Provisioning to App", to allow changes to be made, click **Edit**.
|
||||
1. Select **Enable** to the right of **Create Users**, **Update User Attributes**, and **Deactivate Users**.
|
||||
1. To finish configuring provisioning, click **Save**.
|
||||
|
||||
When you have finished configuring SCIM, you may want to disable some SAML settings you enabled for the configuration process. See "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#6-disable-optional-settings)."
|
||||
|
||||
## How do I assign users and groups?
|
||||
|
||||
{% data reusables.enterprise-managed.assigning-users %}
|
||||
|
||||
{% data reusables.scim.emu-scim-rate-limit %}
|
||||
|
||||
You can also automatically manage organization membership by adding groups to the "Push Groups" tab in Okta. When the group is provisioned successfully, it will be available to connect to teams in the enterprise's organizations. For more information about managing teams, see "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups)."
|
||||
|
||||
{% data reusables.enterprise-managed.assigning-roles %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** You can only set the "Roles" attribute for an individual user, not a group. If you want to set roles for everyone in a group that is assigned to the application in Okta, you must use the "Roles" attribute for each group member, individually.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
## How do I deprovision users and groups?
|
||||
|
||||
To remove a user or group from {% data variables.product.product_name %}, remove the user or group from both the "Assignments" tab and the "Push groups" tab in Okta. For users, make sure the user is removed from all groups in the "Push Groups" tab.
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: 'Provisioning accounts{% ifversion ghec %} for Enterprise Managed Users{% else %} with SCIM{% endif %}'
|
||||
shortTitle: 'Provision{% ifversion ghec %} managed user accounts{% else %} accounts with SCIM{% endif %}'
|
||||
product: '{% data reusables.gated-features.emus %}'
|
||||
intro: 'Learn how to provision accounts and manage organization and team membership for users{% ifversion ghec %} of your {% data variables.enterprise.prodname_emu_enterprise %}{% elsif ghes %} on {% data variables.location.product_location %}{% endif %}.'
|
||||
versions:
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
topics:
|
||||
- Enterprise
|
||||
- Accounts
|
||||
- Authentication
|
||||
children:
|
||||
- /user-provisioning-with-scim-on-ghes
|
||||
- /configuring-scim-provisioning-for-users
|
||||
- /configuring-authentication-and-provisioning-with-entra-id
|
||||
- /configuring-authentication-and-provisioning-with-pingfederate
|
||||
- /configuring-scim-provisioning-with-okta
|
||||
- /provisioning-users-and-groups-with-scim-using-the-rest-api
|
||||
- /managing-team-memberships-with-identity-provider-groups
|
||||
- /troubleshooting-team-membership-with-identity-provider-groups
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users
|
||||
- /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users
|
||||
---
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Managing team memberships with identity provider groups
|
||||
shortTitle: Manage teams with your IdP
|
||||
intro: 'You can manage team and organization membership on {% data variables.product.product_name %} through your identity provider (IdP) by connecting IdP groups with teams within your {% data variables.enterprise.prodname_emu_enterprise %}.'
|
||||
intro: 'Connect IdP groups with teams on {% data variables.product.prodname_dotcom %} to manage team and organization membership through your identity provider.'
|
||||
product: '{% data reusables.gated-features.emus %}'
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/managing-team-memberships-with-identity-provider-groups
|
||||
@@ -10,8 +10,10 @@ redirect_from:
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/managing-team-memberships-with-identity-provider-groups
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups
|
||||
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/managing-team-memberships-with-identity-provider-groups
|
||||
- /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/managing-team-memberships-with-identity-provider-groups
|
||||
versions:
|
||||
ghec: '*'
|
||||
feature: scim-for-ghes-public-beta
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
@@ -20,33 +22,35 @@ topics:
|
||||
- Teams
|
||||
---
|
||||
|
||||
## About team management with {% data variables.product.prodname_emus %}
|
||||
{% data reusables.scim.ghes-beta-note %}
|
||||
|
||||
## About team management with {% ifversion ghec %}{% data variables.product.prodname_emus %}{% else %}SCIM{% endif %}
|
||||
|
||||
{% data reusables.emus.about-team-management-with-idp %} When you connect a team in one of your enterprise's organizations to an IdP group, changes to membership from the IdP group are reflected in your enterprise automatically, reducing the need for manual updates and custom scripts.
|
||||
|
||||
When a change to an IdP group or a new team connection results in a {% data variables.enterprise.prodname_managed_user %} joining a team in an organization they were not already a member of, the {% data variables.enterprise.prodname_managed_user %} will automatically be added to the organization. When you disconnect a group from a team, users who became members of the organization via team membership are removed from the organization if they are not assigned membership in the organization by any other means.
|
||||
When a change to an IdP group or a new team connection results in a user joining a team in an organization they were not already a member of, the user will automatically be added to the organization. When you disconnect a group from a team, users who became members of the organization via team membership are removed from the organization if they are not assigned membership in the organization by any other means.
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** Organization owners can also add {% data variables.enterprise.prodname_managed_users %} to organizations manually, as long as the accounts have already been provisioned via SCIM.
|
||||
**Note:** Organization owners can also add users to organizations manually, as long as the accounts have already been provisioned via SCIM.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
When group membership changes on your IdP, your IdP sends a SCIM request with the changes to {% data variables.product.prodname_dotcom_the_website %} according to the schedule determined by your IdP, so change may not be immediate. Any requests that change team or organization membership will register in the audit log as changes made by the account used to configure user provisioning.
|
||||
When group membership changes on your IdP, your IdP sends a SCIM request with the changes to {% data variables.product.prodname_dotcom %} according to the schedule determined by your IdP, so change may not be immediate. Any requests that change team or organization membership will register in the audit log as changes made by the account used to configure user provisioning.
|
||||
|
||||
{% data variables.product.prodname_dotcom %} also runs a reconciliation job once per day, which synchronizes team membership with IdP group membership that is stored on {% data variables.product.prodname_dotcom %}, based on information previously sent from the IdP via SCIM. If this job finds that a user is a member of an IdP group in the enterprise, but they are not a member of the mapped team or its organization, the job will attempt to add the user to the organization and team.
|
||||
|
||||
Teams connected to IdP groups cannot be parents of other teams nor a child of another team. If the team you want to connect to an IdP group is a parent or child team, we recommend creating a new team or removing the nested relationships that make your team a parent team.
|
||||
|
||||
To manage repository access for any team in your enterprise, including teams connected to an IdP group, you must make changes on {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository)".
|
||||
To manage repository access for any team in your enterprise, including teams connected to an IdP group, you must make changes on {% data variables.product.prodname_dotcom %}. For more information, see "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository)".
|
||||
|
||||
## Requirements for connecting IdP groups with teams
|
||||
|
||||
Before you can connect an IdP group with a team on {% data variables.product.prodname_dotcom %}, you must assign the group to the {% data variables.product.prodname_emu_idp_application %} application in your IdP. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users)."
|
||||
Before you can connect an IdP group with a team on {% data variables.product.prodname_dotcom %}, you must assign the group to the {% ifversion ghec %}{% data variables.product.prodname_emu_idp_application %}{% else %}relevant{% endif %} application in your IdP. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users)."
|
||||
|
||||
You can connect a team in your enterprise to one IdP group. You can assign the same IdP group to multiple teams in your enterprise.
|
||||
|
||||
If you are connecting an existing team to an IdP group, you must first remove any members that were added manually. After you connect a team in your enterprise to an IdP group, your IdP administrator must make team membership changes through the identity provider. You cannot manage team membership on {% data variables.product.prodname_dotcom_the_website %}.
|
||||
If you are connecting an existing team to an IdP group, you must first remove any members that were added manually. After you connect a team in your enterprise to an IdP group, your IdP administrator must make team membership changes through the identity provider. You cannot manage team membership directly on {% data variables.product.prodname_dotcom %}.
|
||||
|
||||
If you use Microsoft Entra ID (previously known as Azure AD) as your IdP, you can only connect a team to a security group. Nested group memberships and Microsoft 365 groups are not supported.
|
||||
|
||||
@@ -65,11 +69,11 @@ Any member of an organization can create a new team and connect the team to an I
|
||||
|
||||
## Managing the connection between an existing team and an IdP group
|
||||
|
||||
Organization owners can manage the existing connection between an IdP group and a team. If your enterprise does not use {% data variables.enterprise.prodname_managed_users %}, team maintainers can also manage the connection.
|
||||
Organization owners {% ifversion ghes %}and team maintainers {% endif %}can manage the existing connection between an IdP group and a team.{% ifversion ghec %} If your enterprise does not use {% data variables.enterprise.prodname_managed_users %}, team maintainers can also manage the connection.{% endif %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: Before you connect an existing team on {% data variables.product.prodname_dotcom_the_website %} to an IdP group for the first time, all members of the team on {% data variables.product.prodname_dotcom_the_website %} must first be removed. For more information, see "[AUTOTITLE](/organizations/organizing-members-into-teams/removing-organization-members-from-a-team)."
|
||||
**Note**: Before you connect an existing team on {% data variables.product.prodname_dotcom %} to an IdP group for the first time, all members of the team on {% data variables.product.prodname_dotcom %} must first be removed. For more information, see "[AUTOTITLE](/organizations/organizing-members-into-teams/removing-organization-members-from-a-team)."
|
||||
|
||||
{% endnote %}
|
||||
|
||||
@@ -101,7 +105,7 @@ If a team cannot sync with the group on your IdP, the team will display an error
|
||||
|
||||
The way a member is added to an organization owned by your enterprise determines how they must be removed from an organization.
|
||||
|
||||
* **If a member was added to an organization manually, you must remove them manually.** Unassigning them from the {% data variables.product.prodname_emu_idp_application %} application on your IdP will suspend the user but not remove them from the organization.
|
||||
* **If a member was added to an organization manually, you must remove them manually.** Unassigning them from the {% ifversion ghec %}{% data variables.product.prodname_emu_idp_application %}{% else %}relevant{% endif %} application on your IdP will suspend the user but not remove them from the organization.
|
||||
* **If a user became an organization member because they were added to IdP groups, remove them from _all_ of the mapped IdP groups** associated with the organization.
|
||||
|
||||
To discover how a member was added to an organization, you can filter the member list by type. See "[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#filtering-by-member-type-in-an-enterprise-with-managed-users)."
|
||||
To discover how a member was added to an organization, you can filter the member list by type. See {% ifversion ghec %}"[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#filtering-by-member-type-in-an-enterprise-with-managed-users)."{% else %}"[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#filtering-by-member-type)."{% endif %}
|
||||
@@ -1,14 +1,16 @@
|
||||
---
|
||||
title: Provisioning users and groups with SCIM using the REST API
|
||||
shortTitle: SCIM using REST API
|
||||
intro: 'You can manage the lifecycle of your enterprise''s user accounts on {% data variables.location.product_location %} from your identity provider (IdP) using {% data variables.product.company_short %}''s REST API for System for Cross-domain Identity Management (SCIM).'
|
||||
intro: 'Manage the lifecycle of user accounts from your identity provider using {% data variables.product.company_short %}''s REST API for System for Cross-domain Identity Management (SCIM).'
|
||||
product: '{% data reusables.gated-features.emus %}'
|
||||
versions:
|
||||
feature: emu-public-scim-schema
|
||||
ghec: '*'
|
||||
feature: scim-for-ghes-public-beta
|
||||
type: tutorial
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-with-scim-using-the-rest-api
|
||||
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-and-groups-with-scim-using-the-rest-api
|
||||
- /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-and-groups-with-scim-using-the-rest-api
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
@@ -16,6 +18,8 @@ topics:
|
||||
- SSO
|
||||
---
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Notes**:
|
||||
@@ -25,6 +29,14 @@ topics:
|
||||
|
||||
{% endnote %}
|
||||
|
||||
{% else %}
|
||||
|
||||
{% data reusables.scim.ghes-beta-note %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
## About IAM for {% data variables.product.prodname_emus %}
|
||||
|
||||
If your enterprise on {% data variables.product.prodname_dotcom %} is created for {% data variables.product.prodname_emus %}, you must configure an external identity management system to provision and maintain user accounts. Your identity management system must offer the following functionality:
|
||||
@@ -34,6 +46,17 @@ If your enterprise on {% data variables.product.prodname_dotcom %} is created fo
|
||||
* OpenID Connect (OIDC), which is only supported if you use Microsoft Entra ID (previously known as Azure AD)
|
||||
* User lifecycle management with System for Cross-domain Identity Management (SCIM)
|
||||
|
||||
{% else %}
|
||||
|
||||
## About SCIM provisioning on {% data variables.product.product_name %}
|
||||
|
||||
To provision and maintain user accounts using SCIM, your identity management system must offer the following functionality:
|
||||
|
||||
* Single sign-on authentication implementing Security Assertion Markup Language (SAML) 2.0
|
||||
* User lifecycle management with System for Cross-domain Identity Management (SCIM)
|
||||
|
||||
{% endif %}
|
||||
|
||||
When you configure authentication and provisioning for your enterprise, you can either use a partner IdP, or you can use another combination of identity management systems.
|
||||
|
||||
* [Using a partner identity provider](#using-a-partner-identity-provider)
|
||||
@@ -41,9 +64,7 @@ When you configure authentication and provisioning for your enterprise, you can
|
||||
|
||||
### Using a partner identity provider
|
||||
|
||||
Each partner IdP provides a "paved-path" application, which implements both SSO and user lifecycle management. To simplify your configuration of {% data variables.product.prodname_emus %}, {% data variables.product.company_short %} recommends that you use a partner IdP's application for both authentication and provisioning. For more information and a list of partner IdPs, see "[AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users#identity-management-systems)."
|
||||
|
||||
When you use a single partner IdP for both authentication and provisioning, {% data variables.product.company_short %} provides support for the application on the partner IdP, as well as the IdPs' integration with {% data variables.product.product_name %}.
|
||||
Each partner IdP provides a "paved-path" application, which implements both SSO and user lifecycle management. To simplify configuration, {% data variables.product.company_short %} recommends that you use a partner IdP's application for both authentication and provisioning. For more information and a list of partner IdPs, see {% ifversion ghec %}"[AUTOTITLE](/admin/identity-and-access-management/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 %}
|
||||
|
||||
For more information about configuring SCIM provisioning using a partner IdP, see "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users)."
|
||||
|
||||
@@ -51,15 +72,24 @@ For more information about configuring SCIM provisioning using a partner IdP, se
|
||||
|
||||
If you cannot use a partner IdP for both authentication and provisioning due to migration overhead, licensing costs, or organizational inertia, you can use another identity management system or combination of systems. The systems must provide authentication using SAML and user lifecycle management using SCIM, and must adhere to {% data variables.product.company_short %}'s integration guidelines.
|
||||
|
||||
{% data variables.product.company_short %} has not tested integration with every identity management system. While integration with {% data variables.product.prodname_emus %} may be possible, {% data variables.product.company_short %}'s support team may not be able to assist you with issues related to these systems. If you need help with an identity management system that's not a partner IdP, or if you use a partner IdP only for SAML authentication, you must consult the system's documentation, support team, or other resources.
|
||||
{% data variables.product.company_short %} has not tested integration with every identity management system. While integration with {% ifversion ghec %}{% data variables.product.prodname_emus %}{% else %}{% data variables.product.product_name %}{% endif %} may be possible, {% data variables.product.company_short %}'s support team may not be able to assist you with issues related to these systems. If you need help with an identity management system that's not a partner IdP, or if you use a partner IdP only for SAML authentication, you must consult the system's documentation, support team, or other resources.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
{%- ifversion ghec %}
|
||||
* {% data reusables.enterprise-managed.emu-prerequisite %}
|
||||
* {% data reusables.scim.emu-prerequisite-authentication %}
|
||||
* {% data reusables.scim.scim-standard-prerequisite %}
|
||||
* You must enable an open SCIM configuration for your enterprise. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users#configuring-provisioning-for-other-identity-management-systems)."
|
||||
* To authenticate requests to the REST API endpoints for SCIM, you must use a {% data variables.product.pat_v1 %} associated with your enterprise's setup user. The token requires the **admin:enterprise** scope. {% data variables.product.company_short %} recommends that you do not configure an expiration date for the token. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users#creating-a-personal-access-token)."
|
||||
* To authenticate requests to the REST API endpoints for SCIM, you must use a {% data variables.product.pat_v1 %} associated with your enterprise's setup user. The token requires the **admin:enterprise** scope. {% data variables.product.company_short %} recommends that you do not configure an expiration date for the token. See "[AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users#create-a-personal-access-token)."
|
||||
{%- else %}
|
||||
To implement SCIM using the REST API, the general prerequisites for using SCIM on {% data variables.product.product_name %} apply. See the "Prerequisites" section in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#prerequisites)."
|
||||
|
||||
In addition, the following prerequisites apply:
|
||||
|
||||
* You must have completed steps 1 to 3 in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
* You must use the {% data variables.product.pat_v1 %} created for the built-in setup user to authenticate requests to the REST API.
|
||||
{%- endif %}
|
||||
{% data reusables.scim.scim-standard-prerequisite %}
|
||||
* The user records for the systems that you use for authentication and provisioning must share a unique identifier and satisfy {% data variables.product.company_short %}'s matching criteria. For more information, see "[AUTOTITLE](/rest/enterprise-admin/scim#mapping-of-saml-and-scim-data)" in the REST API documentation.
|
||||
|
||||
## Best practices for SCIM provisioning with {% data variables.product.prodname_dotcom %}'s REST API
|
||||
@@ -69,8 +99,8 @@ When you configure your identity management system to provision users or groups
|
||||
* [Ensure your identity management system is the only source of write operations](#ensure-your-identity-management-system-is-the-only-source-of-write-operations)
|
||||
* [Send valid requests to REST API endpoints](#send-valid-requests-to-rest-api-endpoints)
|
||||
* [Provision users before you provision groups](#provision-users-before-you-provision-groups)
|
||||
* [Validate access for groups on {% data variables.product.product_name %}](#validate-access-for-groups-on-github-enterprise-cloud)
|
||||
* [Understand rate limits for {% data variables.product.product_name %}](#understand-rate-limits-for-github-enterprise-cloud)
|
||||
* [Validate access for groups on {% data variables.product.prodname_dotcom %}](#validate-access-for-groups-on-github)
|
||||
* [Understand rate limits on {% data variables.product.prodname_dotcom %}](#understand-rate-limits-on-github)
|
||||
* [Configure audit log streaming](#configure-audit-log-streaming)
|
||||
|
||||
### Ensure your identity management system is the only source of write operations
|
||||
@@ -103,15 +133,21 @@ To manage team membership with groups on your identity management system, you mu
|
||||
1. Update the membership of the group on your identity management system.
|
||||
1. Create a team on {% data variables.product.product_name %} that's mapped to the group on your identity management system.
|
||||
|
||||
### Validate access for groups on {% data variables.product.product_name %}
|
||||
### Validate access for groups on {% data variables.product.prodname_dotcom %}
|
||||
|
||||
If you manage access using groups on your identity management system, you can validate that users get the access you intend. You can use the REST API to compare your system's group memberships with {% data variables.product.prodname_dotcom %}'s understanding of those groups. For more information, see "[AUTOTITLE](/rest/teams/external-groups#about-external-groups)" and "[AUTOTITLE](/rest/teams/teams#get-a-team-by-name)" in the REST API documentation.
|
||||
|
||||
### Understand rate limits for {% data variables.product.product_name %}
|
||||
### Understand rate limits on {% data variables.product.prodname_dotcom %}
|
||||
|
||||
To ensure the availability and reliability of the platform, {% data variables.product.company_short %} implements rate limits. For more information, see "[AUTOTITLE](/rest/using-the-rest-api/rate-limits-for-the-rest-api)."
|
||||
{% ifversion ghec %}
|
||||
To ensure the availability and reliability of the platform, {% data variables.product.company_short %} implements rate limits.
|
||||
|
||||
Without considering rate limits, large enterprises onboarding with {% data variables.product.prodname_emus %} for the first time are likely to exceed the limits. {% data reusables.scim.emu-scim-rate-limit-details %}
|
||||
{% else %}
|
||||
If a site administrator has enabled rate limits on your instance, you may encounter errors when you provision users for the first time. You can review your IdP logs to confirm if attempted SCIM provisioning or push operations failed due to a rate limit error. The response to a failed provisioning attempt will depend on the IdP.
|
||||
{% endif %}
|
||||
|
||||
For more information, see "[AUTOTITLE](/rest/using-the-rest-api/rate-limits-for-the-rest-api)."
|
||||
|
||||
### Configure audit log streaming
|
||||
|
||||
@@ -130,16 +166,16 @@ Before a person with an identity on your identity management system can sign in
|
||||
|
||||
| Action | Method | Endpoint and more information | Events in the audit log |
|
||||
| :- | :- | :- | :- |
|
||||
| List all provisioned users for your enterprise, which includes all users who are soft-deprovisioned by setting `active` to `false`. | `GET` | [`/scim/v2/enterprises/{enterprise}/Users`](/rest/enterprise-admin/scim#list-scim-provisioned-identities-for-an-enterprise) | N/A |
|
||||
| Create a user. The API's response includes an `id` field for uniquely identifying the user. | `POST` | [`/scim/v2/enterprises/{enterprise}/Users`](/rest/enterprise-admin/scim#provision-a-scim-enterprise-user) | <ul><li>`external_identity.provision`</li><li>`user.create`</li><li>If request adds the `enterprise_owner` role, `business.add_admin`</li><li>If request adds the `billing_manager` role, `business.add_billing_manager`</li></ul> |
|
||||
| Retrieve an existing user in your enterprise using the `id` field from the `POST` request that you sent to create the user. | `GET` | [`/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}`](/rest/enterprise-admin/scim#get-scim-provisioning-information-for-an-enterprise-user) | N/A |
|
||||
| Update all of an existing user's attributes using the `id` field from the `POST` request that you sent to create the user. Update `active` to `false` to soft-deprovision the user, or `true` to reactivate the user. {% data reusables.scim.public-scim-more-info-about-deprovisioning-and-reactivating %} | `PUT` | [`/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}`](/rest/enterprise-admin/scim#set-scim-information-for-a-provisioned-enterprise-user) | {% data reusables.scim.public-scim-put-or-patch-user-audit-log-events %} |
|
||||
| Update an individual attribute for an existing user using the `id` field from the `POST` request that you sent to create the user. Update `active` to `false` to soft-deprovision the user, or `true` to reactivate the user. {% data reusables.scim.public-scim-more-info-about-deprovisioning-and-reactivating %} | `PATCH` | [`/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}`](/rest/enterprise-admin/scim#update-an-attribute-for-a-scim-enterprise-user) | {% data reusables.scim.public-scim-put-or-patch-user-audit-log-events %} |
|
||||
| To completely delete an existing user, you can hard-deprovision the user. After hard-deprovisioning, you cannot reactivate the user, and you must provision the user as a new user. For more information, see "[Hard-deprovisioning users with the REST API](#hard-deprovisioning-users-with-the-rest-api)." | `DELETE` | [`/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}`](/rest/enterprise-admin/scim#delete-a-scim-user-from-an-enterprise) | <ul><li>`external_identity.deprovision`</li><li>`user.remove_email`</li></ul> |
|
||||
| List all provisioned users for your enterprise, which includes all users who are soft-deprovisioned by setting `active` to `false`. | `GET` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users`](/rest/enterprise-admin/scim#list-scim-provisioned-identities-for-an-enterprise) | N/A |
|
||||
| Create a user. The API's response includes an `id` field for uniquely identifying the user. | `POST` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users`](/rest/enterprise-admin/scim#provision-a-scim-enterprise-user) | <ul><li>`external_identity.provision`</li><li>`user.create`</li><li>If request adds the `enterprise_owner` role, `business.add_admin`</li><li>If request adds the `billing_manager` role, `business.add_billing_manager`</li>{% ifversion ghes %}<li>If request succeeds, `external_identity.scim_api_success`</li><li>If request fails, `external_identity.scim_api_failure`</li>{% endif %}</ul> |
|
||||
| Retrieve an existing user in your enterprise using the `id` field from the `POST` request that you sent to create the user. | `GET` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`](/rest/enterprise-admin/scim#get-scim-provisioning-information-for-an-enterprise-user) | N/A |
|
||||
| Update all of an existing user's attributes using the `id` field from the `POST` request that you sent to create the user. Update `active` to `false` to soft-deprovision the user, or `true` to reactivate the user. {% data reusables.scim.public-scim-more-info-about-deprovisioning-and-reactivating %} | `PUT` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`](/rest/enterprise-admin/scim#set-scim-information-for-a-provisioned-enterprise-user) | {% data reusables.scim.public-scim-put-or-patch-user-audit-log-events %} |
|
||||
| Update an individual attribute for an existing user using the `id` field from the `POST` request that you sent to create the user. Update `active` to `false` to soft-deprovision the user, or `true` to reactivate the user. {% data reusables.scim.public-scim-more-info-about-deprovisioning-and-reactivating %} | `PATCH` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`](/rest/enterprise-admin/scim#update-an-attribute-for-a-scim-enterprise-user) | {% data reusables.scim.public-scim-put-or-patch-user-audit-log-events %} |
|
||||
| To completely delete an existing user, you can hard-deprovision the user. After hard-deprovisioning, you cannot reactivate the user, and you must provision the user as a new user. For more information, see "[Hard-deprovisioning users with the REST API](#hard-deprovisioning-users-with-the-rest-api)." | `DELETE` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`](/rest/enterprise-admin/scim#delete-a-scim-user-from-an-enterprise) | <ul><li>`external_identity.deprovision`</li><li>`user.remove_email`</li>{% ifversion ghes %}<li>If request succeeds, `external_identity.scim_api_success`</li><li>If request fails, `external_identity.scim_api_failure`</li>{% endif %}</ul> |
|
||||
|
||||
## Soft-deprovisioning users with the REST API
|
||||
|
||||
To prevent a user from signing in to access your enterprise, you can soft-deprovision the user by sending a `PUT` or `PATCH` request to update a user's `active` field to `false` to `/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}`. When you soft-deprovision a user, {% data variables.product.product_name %} obfuscates the user record's `login` and `email` fields, and the user is suspended.
|
||||
To prevent a user from signing in to access your enterprise, you can soft-deprovision the user by sending a `PUT` or `PATCH` request to update a user's `active` field to `false` to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`. When you soft-deprovision a user, {% data variables.product.product_name %} obfuscates the user record's `login` and `email` fields, and the user is suspended.
|
||||
|
||||
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:
|
||||
|
||||
@@ -147,12 +183,16 @@ When you soft-deprovision a user, the `external_identity.update` event does not
|
||||
* `user.remove_email`
|
||||
* `user.rename`
|
||||
* `external_identity.deprovision`
|
||||
{%- ifversion ghes %}
|
||||
* If the request succeeds, `external_identity.scim_api_success`
|
||||
* If the request fails, `external_identity.scim_api_failure`
|
||||
{%- endif %}
|
||||
|
||||
You can view all suspended users for your enterprise. For more information, see "[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-suspended-members-in-an-enterprise-with-managed-users)."
|
||||
You can view all suspended users for your enterprise. For more information, see "[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-suspended-members).
|
||||
|
||||
## Reactivating users with the REST API
|
||||
|
||||
To allow a soft-deprovisioned user to sign in to access your enterprise, unsuspend the user by sending a `PUT` or `PATCH` request to `/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}` that updates the user's `active` field to `true`.
|
||||
To allow a soft-deprovisioned user to sign in to access your enterprise, unsuspend the user by sending a `PUT` or `PATCH` request to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}` that updates the user's `active` field to `true`.
|
||||
|
||||
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:
|
||||
|
||||
@@ -160,10 +200,14 @@ When you reactivate a user, the `external_identity.update` event does not appear
|
||||
* `user.remove_email`
|
||||
* `user.rename`
|
||||
* `external_identity.provision`
|
||||
{%- ifversion ghes %}
|
||||
* If the request succeeds, `external_identity.scim_api_success`
|
||||
* If the request fails, `external_identity.scim_api_failure`
|
||||
{%- endif %}
|
||||
|
||||
## Hard-deprovisioning users with the REST API
|
||||
|
||||
To completely delete a user, you can hard-deprovision the user by sending a `DELETE` request to `/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}`. Your enterprise will retain any resources and comments created by the user.
|
||||
To completely delete a user, you can hard-deprovision the user by sending a `DELETE` request to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`. Your enterprise will retain any resources and comments created by the user.
|
||||
|
||||
When you hard-deprovision a user, the following events occur:
|
||||
|
||||
@@ -178,7 +222,7 @@ To reprovision the user, you must use the `POST` method to create a new user. Th
|
||||
|
||||
To control access to repositories in your enterprise, you can use groups on your identity management system to control organization and team membership for users in your enterprise. You can read about the associated API endpoints in the REST API documentation and see code examples, and you can review audit log events associated with each request.
|
||||
|
||||
While your enterprise doesn't require an available license to provision a new user account, if you provision a group that results in the addition of users to an organization, you must have available licenses for those users. If your enterprise only uses {% data variables.visual_studio.prodname_vss_ghe %}, the associated user must be assigned to a subscriber. For more information, see "[AUTOTITLE](/billing/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/about-visual-studio-subscriptions-with-github-enterprise#about-licenses-for-visual-studio-subscriptions-with-github-enterprise)."
|
||||
While your enterprise doesn't require an available license to provision a new user account, if you provision a group that results in the addition of users to an organization, you must have available licenses for those users.{% ifversion ghec %} If your enterprise only uses {% data variables.visual_studio.prodname_vss_ghe %}, the associated user must be assigned to a subscriber. For more information, see "[AUTOTITLE](/billing/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/about-visual-studio-subscriptions-with-github-enterprise#about-licenses-for-visual-studio-subscriptions-with-github-enterprise)."{% endif %}
|
||||
|
||||
* For an overview of the supported attributes for groups, see "[SCIM](/rest/enterprise-admin/scim#supported-scim-group-attributes)" in the REST API documentation.
|
||||
* For an overview of audit log events related to groups, see "[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise#external_group)."
|
||||
@@ -186,16 +230,16 @@ While your enterprise doesn't require an available license to provision a new us
|
||||
|
||||
| Action | Method | Endpoint and more information | Related events in the audit log |
|
||||
| :- | :- | :- | :- |
|
||||
| List all groups defined for your enterprise. | `GET` | [`/scim/v2/enterprises/{enterprise}/Groups`](/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise) | N/A |
|
||||
| To define a new IdP group for your enterprise, create the group. The API's response includes an `id` field for uniquely identifying the group. | `POST` | [`/scim/v2/enterprises/{enterprise}/Groups`](/rest/enterprise-admin/scim#provision-a-scim-enterprise-group) | <ul><li>`external_group.provision`</li><li>`external_group.update_display_name`</li><li>If the request included a list of users, `external_group.add_member`</li></ul> |
|
||||
| Retrieve an existing group for your enterprise using the `id` from the `POST` request that you sent to create the group. | `GET` | [`/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}`](/rest/enterprise-admin/scim#get-scim-provisioning-information-for-an-enterprise-group) | N/A |
|
||||
| Update all of the attributes for an existing group. | `PUT` | [`/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}`](/rest/enterprise-admin/scim#set-scim-information-for-a-provisioned-enterprise-group) | {% data reusables.scim.public-scim-put-or-patch-group-audit-log-events %} |
|
||||
| Update an individual attribute for an existing group. | `PATCH` | [`/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}`](/rest/enterprise-admin/scim#update-an-attribute-for-a-scim-enterprise-group) | {% data reusables.scim.public-scim-put-or-patch-group-audit-log-events %} |
|
||||
| Completely delete an existing group. | `DELETE` | [`/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}`](/rest/enterprise-admin/scim#delete-a-scim-group-from-an-enterprise) | <ul><li>`external_group.delete`</li><li>If the request deletes a group linked to a team in an organization where the user has no other team membership, `org.remove_member`</li><li>If the request deletes a group linked to a team in an organization where the user has other team membership, `team.remove_member`</li></ul> |
|
||||
| List all groups defined for your enterprise. | `GET` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups`](/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise) | N/A |
|
||||
| To define a new IdP group for your enterprise, create the group. The API's response includes an `id` field for uniquely identifying the group. | `POST` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups`](/rest/enterprise-admin/scim#provision-a-scim-enterprise-group) | <ul><li>`external_group.provision`</li><li>`external_group.update_display_name`</li><li>If the request included a list of users, `external_group.add_member`</li>{% ifversion ghes %}<li>If request succeeds, `external_group.scim_api_success`</li><li>If request fails, `external_group.scim_api_failure`</li>{% endif %}</ul> |
|
||||
| Retrieve an existing group for your enterprise using the `id` from the `POST` request that you sent to create the group. | `GET` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups/{scim_group_id}`](/rest/enterprise-admin/scim#get-scim-provisioning-information-for-an-enterprise-group) | N/A |
|
||||
| Update all of the attributes for an existing group. | `PUT` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups/{scim_group_id}`](/rest/enterprise-admin/scim#set-scim-information-for-a-provisioned-enterprise-group) | {% data reusables.scim.public-scim-put-or-patch-group-audit-log-events %} |
|
||||
| Update an individual attribute for an existing group. | `PATCH` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups/{scim_group_id}`](/rest/enterprise-admin/scim#update-an-attribute-for-a-scim-enterprise-group) | {% data reusables.scim.public-scim-put-or-patch-group-audit-log-events %} |
|
||||
| Completely delete an existing group. | `DELETE` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups/{scim_group_id}`](/rest/enterprise-admin/scim#delete-a-scim-group-from-an-enterprise) | <ul><li>`external_group.delete`</li><li>If the request deletes a group linked to a team in an organization where the user has no other team membership, `org.remove_member`</li><li>If the request deletes a group linked to a team in an organization where the user has other team membership, `team.remove_member`</li>{% ifversion ghes %}<li>If request succeeds, `external_group.scim_api_success`</li><li>If request fails, `external_group.scim_api_failure`</li>{% endif %}</ul> |
|
||||
|
||||
### Additional audit log events for changes to IdP groups
|
||||
|
||||
If you update the members of an existing group using a `PUT` or `PATCH` request to `/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}`, {% data variables.product.product_name %} may add the user to the organization or remove the user from the organization depending on the user's current organization membership. If the user is already a member of at least one team in the organization, the user is a member of the organization. If the user is not a member of any teams in the organization, the user may also not already be a member of the organization.
|
||||
If you update the members of an existing group using a `PUT` or `PATCH` request to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups/{scim_group_id}`, {% data variables.product.product_name %} may add the user to the organization or remove the user from the organization depending on the user's current organization membership. If the user is already a member of at least one team in the organization, the user is a member of the organization. If the user is not a member of any teams in the organization, the user may also not already be a member of the organization.
|
||||
|
||||
If your request updates a group linked to a team in an organization where a user is not already a member, in addition to `external_group.update`, the following events appear in the audit log:
|
||||
|
||||
@@ -208,21 +252,25 @@ If your request updates a group linked to a team in an organization where a user
|
||||
* If the request removes the user from a group that's linked to a team in an organization, and the team is not the last team in the organization where the user is a member, `team.remove_member`
|
||||
* If the request removes a user from a group that's linked to the last team in an organization where the user is already a member, `org.remove_member`
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
## Migrating to a new SCIM provider
|
||||
|
||||
After you configure SCIM provisioning for your enterprise, you may need to migrate to a new SCIM provider. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/reconfiguring-iam-for-enterprise-managed-users/migrating-your-enterprise-to-a-new-identity-provider-or-tenant)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Troubleshooting SCIM provisioning
|
||||
|
||||
* If {% data variables.product.prodname_dotcom %} is rate-limiting your requests to the REST API, you can learn more in "[Understand rate limits for {% data variables.product.product_name %}](#understand-rate-limits-for-github-enterprise-cloud)."
|
||||
* If your requests to the REST API are rate-limited, you can learn more in "[Understand rate limits on {% data variables.product.prodname_dotcom %}](#understand-rate-limits-on-github)."
|
||||
|
||||
* If you enable audit log streaming and stream events for API requests, you can review any requests to the REST API endpoints for SCIM provisioning by filtering for events from the `EnterpriseUsersScim` or `EnterpriseGroupsScim` controllers.
|
||||
|
||||
* If a SCIM request fails and you're unable to determine the cause, check the status of your identity management system to ensure that services were available. Additionally, check {% data variables.product.company_short %}'s status page. For more information, see "[AUTOTITLE](/support/learning-about-github-support/about-github-support#about-github-status)."
|
||||
* If a SCIM request fails and you're unable to determine the cause, check the status of your identity management system to ensure that services were available.{% ifversion ghec %} Additionally, check {% data variables.product.company_short %}'s status page. For more information, see "[AUTOTITLE](/support/learning-about-github-support/about-github-support#about-github-status)."{% endif %}
|
||||
|
||||
* If a request to provision a user fails with a `400` error, and the error message in your identity management system's log indicates issues with account ownership or username formatting, review "[AUTOTITLE](/admin/identity-and-access-management/iam-configuration-reference/username-considerations-for-external-authentication)."
|
||||
|
||||
* After successful authentication, {% data variables.product.product_name %} links the user who authenticated to an identity provisioned by SCIM. The unique identifiers for authentication and provisioning must match. For more information, see "[AUTOTITLE](/rest/enterprise-admin/scim#mapping-of-saml-and-scim-data)." You can also view this mapping on {% data variables.location.product_location %}. See "[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise#viewing-and-revoking-a-linked-identity)."
|
||||
* After successful authentication, {% data variables.product.product_name %} links the user who authenticated to an identity provisioned by SCIM. The unique identifiers for authentication and provisioning must match. For more information, see "[AUTOTITLE](/rest/enterprise-admin/scim#mapping-of-saml-and-scim-data)."{% ifversion ghec %} You can also view this mapping on {% data variables.location.product_location %}. See "[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise#viewing-and-revoking-a-linked-identity)."{% endif %}
|
||||
|
||||
* If you manage access using groups on your identity management system, you can troubleshoot using the REST API or web UI for {% data variables.product.product_name %}.
|
||||
|
||||
@@ -5,6 +5,7 @@ intro: 'If you manage team membership using groups on your identity provider (Id
|
||||
product: '{% data reusables.gated-features.emus %}'
|
||||
versions:
|
||||
ghec: '*'
|
||||
feature: scim-for-ghes-public-beta
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
@@ -14,8 +15,11 @@ topics:
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/troubleshooting-team-membership-with-identity-provider-groups
|
||||
- /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/troubleshooting-team-membership-with-identity-provider-groups
|
||||
- /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/troubleshooting-team-membership-with-identity-provider-groups
|
||||
---
|
||||
|
||||
{% data reusables.scim.ghes-beta-note %}
|
||||
|
||||
## About management of team membership with IdP groups
|
||||
|
||||
{% data reusables.emus.about-team-management-with-idp %} You can review a list of teams that you've synchronized to IdP groups from your enterprise's settings. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups#viewing-idp-groups-group-membership-and-connected-teams)."
|
||||
@@ -34,6 +38,8 @@ If {% data variables.product.prodname_dotcom %} is unable to synchronize team me
|
||||
|
||||
If a team is unable to sync membership with a group on your IdP, you'll see a description of the problem under the team's name and membership count.
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
### Error: "Out of sync due to insufficient licenses"
|
||||
|
||||
If your enterprise does not have sufficient licenses and {% data variables.product.prodname_dotcom %} is unable to synchronize team membership with a group on your IdP, you'll see a message that reads "Out of sync due to insufficient licenses".
|
||||
@@ -49,6 +55,8 @@ The team may be missing members because your enterprise does not have sufficient
|
||||
* Deprovision users from your enterprise.
|
||||
* Purchase additional licenses to allow synchronization to complete. For more information, see "[AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing#about-changes-to-your-subscription)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
### Error: "Out of sync"
|
||||
|
||||
If synchronization of team membership with a group on your IdP fails due to a problem other than licensing, you'll see a message that reads "Out of sync".
|
||||
@@ -0,0 +1,168 @@
|
||||
---
|
||||
title: '{% ifversion scim-for-ghes-public-beta %}About{% else %}Configuring{% endif %} user provisioning with SCIM on GitHub Enterprise Server'
|
||||
shortTitle: '{% ifversion scim-for-ghes-public-beta %}About SCIM provisioning{% else %}Configure SCIM user provisioning{% endif %}'
|
||||
intro: '{% ifversion scim-for-ghes-public-beta %}Learn about{% else %}Get started with{% endif %} managing the lifecycle of user accounts with SCIM on {% data variables.location.product_location %}.'
|
||||
permissions: '{% ifversion scim-for-ghes-public-beta %}{% else %}Site administrators{% endif %}'
|
||||
versions:
|
||||
ghes: '*'
|
||||
allowTitleToDifferFromFilename: true
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
redirect_from:
|
||||
- /admin/authentication/configuring-user-provisioning-for-your-enterprise
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-user-provisioning-for-your-enterprise
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-for-your-enterprise
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise
|
||||
- /admin/managing-iam/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise
|
||||
---
|
||||
|
||||
{% data reusables.scim.ghes-beta-note %}
|
||||
|
||||
## About user provisioning for {% data variables.product.product_name %}
|
||||
|
||||
If you use SAML single sign-on (SSO) for {% data variables.location.product_location %}, you can configure SCIM to automatically create or suspend user accounts and grant access to your instance when you assign or unassign the application on your IdP. For more information about SCIM, see [System for Cross-domain Identity Management: Protocol (RFC 7644)](https://tools.ietf.org/html/rfc7644) on the IETF website.
|
||||
|
||||
If you do not configure user provisioning with SCIM, your IdP will not communicate with {% data variables.product.product_name %} automatically when you assign or unassign the application to a user. Without SCIM, {% data variables.product.product_name %} creates a user account using SAML Just-in-Time (JIT) provisioning the first time someone navigates to {% data variables.product.product_name %} and signs in by authenticating through your IdP.
|
||||
|
||||
To configure provisioning for your enterprise, you must enable provisioning on {% data variables.product.product_name %}, then {% ifversion scim-for-ghes-public-beta %}either {% endif %}install and configure a provisioning application on your IdP{% ifversion scim-for-ghes-public-beta %}, or configure SCIM provisioning manually using {% data variables.product.company_short %}'s REST API endpoints for SCIM{% endif %}.
|
||||
|
||||
## Supported identity providers
|
||||
|
||||
{% ifversion scim-for-ghes-public-beta %}
|
||||
|
||||
{% data reusables.enterprise_user_management.emu-paved-path-iam-integrations %}
|
||||
|
||||
### Partner identity providers
|
||||
|
||||
The following IdPs are partner IdPs. They offer an application that you can use to configure both SAML authentication and SCIM provisioning.
|
||||
|
||||
* Microsoft Entra ID
|
||||
* Okta
|
||||
* PingFederate (beta)
|
||||
|
||||
When you use a single partner IdP for both authentication and provisioning, {% data variables.product.company_short %} provides support for the application on the partner IdP and the IdP's integration with {% data variables.product.prodname_dotcom %}. Support for PingFederate is in beta.
|
||||
|
||||
### Other identity management systems
|
||||
|
||||
If you cannot use a single partner IdP for both authentication and provisioning, you can use another identity management system or combination of systems. The system must:
|
||||
|
||||
* Adhere to **{% data variables.product.company_short %}'s integration guidelines**
|
||||
* Provide **authentication using SAML**, adhering to SAML 2.0 specification
|
||||
* Provide **user lifecycle management using SCIM**, adhering to the SCIM 2.0 specification and communicating with {% data variables.product.company_short %}'s REST API (see "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-with-scim-using-the-rest-api)")
|
||||
|
||||
{% else %}
|
||||
|
||||
During the private beta, your account team will provide documentation for the configuration of SCIM for {% data variables.product.product_name %} on a supported IdP.
|
||||
|
||||
{% endif %}
|
||||
|
||||
## How will I manage user lifecycles with SCIM?
|
||||
|
||||
{% data reusables.enterprise_user_management.scim-manages-user-lifecycle %}
|
||||
|
||||
When SCIM is enabled, you will no longer be able to delete, suspend, or promote SCIM-provisioned users directly on {% data variables.product.product_name %}. You must manage these processes from your IdP.
|
||||
|
||||
## What will happen to existing users on my instance?
|
||||
|
||||
If you currently use SAML SSO, and you are enabling SCIM, you should be aware of what happens to existing users during SCIM provisioning.
|
||||
|
||||
* When SCIM is enabled, users with SAML-linked identities will **not be able to sign in** until their identities have been provisioned by SCIM.
|
||||
* When your instance receives a SCIM request, SCIM identities are matched to existing users by **comparing the `userName` SCIM field with the {% data variables.product.prodname_dotcom %} username**. If a user with a matching username doesn't exist, {% data variables.product.prodname_dotcom %} creates a new user.
|
||||
* If {% data variables.product.prodname_dotcom %} successfully identifies a user from the IdP, but account details such as email address, first name, or last name don't match, the instance **overwrites the details** with values from the IdP. Any email addresses other than the primary email provisioned by SCIM will also be deleted from the user account.
|
||||
|
||||
## What happens during SAML authentication?
|
||||
|
||||
After an IdP administrator grants a person access to {% data variables.location.product_location %}, the user can authenticate through the IdP to access {% data variables.product.product_name %} using SAML SSO.
|
||||
|
||||
* When a user authenticates through SAML, to associate a user with a SAML identity, {% data variables.product.prodname_dotcom %} compares a normalized `NameID` claim from the IdP (or another value you have configured) to the account's username. For details about normalization, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication#about-username-normalization)."
|
||||
* If there is no account with a matching username on the instance, the user will fail to sign in.
|
||||
* To make this match, {% data variables.product.product_name %} compares the SAML `NameId` claim from the IdP to the SCIM `userName` attribute for each user account provisioned by SCIM on the instance.
|
||||
* Additionally, for Entra ID, {% data variables.product.product_name %} compares the object identifier from the SAML request with an existing SCIM external ID.
|
||||
* If your environment does not use `NameID` to uniquely identify users, a site administrator can configure custom user attributes for the instance. {% data variables.product.product_name %} will respect this mapping when SCIM is configured. For more information about mapping user attributes, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso)."
|
||||
|
||||
{% ifversion scim-for-ghes-public-beta %}
|
||||
|
||||
## What happens if I disable SCIM?
|
||||
|
||||
SCIM will be disabled on your instance if any of the following things happens.
|
||||
|
||||
* The **Enable SCIM configuration** checkbox is unselected on the "Authentication security" page in the enterprise settings.
|
||||
* The **SAML** radio button is unselected in the "Authentication" section of the Management Console.
|
||||
* The SAML **Issuer** or **Single sign-on URL** field is updated in the "Authentication" section of the Management Console.
|
||||
|
||||
If SCIM is disabled on the instance:
|
||||
|
||||
* Requests to the SCIM API endpoints on your instance will no longer succeed.
|
||||
* SCIM-provisioned users will remain unchanged and will not be suspended.
|
||||
* Site administrators will be able to manage the lifecycle of SCIM-provisioned users, such as suspension and deletion, from the site admin dashboard.
|
||||
* Users will still be able to sign on via SAML, if enabled.
|
||||
* Users will be unlinked from their external identity record, and the record will be deleted.
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% ifversion scim-for-ghes-public-beta %}
|
||||
|
||||
## Getting started
|
||||
|
||||
To get started with SCIM, you will:
|
||||
|
||||
1. Complete initial setup, required regardless of which IdP you will use, in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users)."
|
||||
1. Configure settings in your IdP.
|
||||
* If you're using a partner IdP for authentication and provisioning, you'll follow a guide for your IdP.
|
||||
* Otherwise, you'll set up a SCIM integration with the REST API, as described in "[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api)."
|
||||
|
||||
{% else %}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* {% data reusables.saml.ghes-you-must-configure-saml-sso %}
|
||||
|
||||
* You must allow built-in authentication for users who don't have an account on your IdP. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider)."
|
||||
|
||||
* Your IdP must support making SCIM calls to a Service Provider (SP).
|
||||
|
||||
* You must have administrative access on your IdP to configure the application for user provisioning for {% data variables.product.product_name %}.
|
||||
|
||||
## Enabling user provisioning for your enterprise
|
||||
|
||||
To perform provisioning actions on your instance, you will create a built-in user account and promote the account to an enterprise owner.
|
||||
|
||||
After you enable SCIM on a {% data variables.product.product_name %} instance, all user accounts are suspended. The built-in user account will continue to perform provisioning actions. After you grant a user access to your instance from your IdP, the IdP will communicate with the instance using SCIM to unsuspend the user's account.
|
||||
|
||||
1. Create a built-in user account to perform provisioning actions on your instance. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider#inviting-users-outside-your-provider-to-authenticate-to-your-instance)."
|
||||
1. Promote the dedicated user account to an enterprise owner. For more information, see "[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise#adding-an-enterprise-administrator-to-your-enterprise-account)."
|
||||
1. Sign into your instance as the new enterprise owner.
|
||||
1. Create a {% data variables.product.pat_v1 %} with **admin:enterprise** scope. Do not specify an expiration date for the {% data variables.product.pat_v1 %}. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
|
||||
|
||||
{% warning %}
|
||||
|
||||
**Warning**: Ensure that you don't specify an expiration date for the {% data variables.product.pat_v1 %}. If you specify an expiration date, SCIM will no longer function after the expiration date passes.
|
||||
|
||||
{% endwarning %}
|
||||
{% note %}
|
||||
|
||||
**Note**: You'll need this {% data variables.product.pat_generic %} to test the SCIM configuration, and to configure the application for SCIM on your IdP. Store the token securely in a password manager until you need the token again later in these instructions.
|
||||
|
||||
{% endnote %}
|
||||
{% data reusables.enterprise_installation.ssh-into-instance %}
|
||||
1. To enable SCIM, run the commands provided to you by your account manager on {% data variables.contact.contact_enterprise_sales %}.
|
||||
{% data reusables.enterprise_site_admin_settings.wait-for-configuration-run %}
|
||||
1. To validate that SCIM is operational, run the following commands. Replace _PAT FROM STEP 3_ and _YOUR INSTANCE'S HOSTNAME_ with actual values.
|
||||
|
||||
```shell
|
||||
$ GHES_PAT="PAT FROM STEP 3"
|
||||
$ GHES_HOSTNAME="YOUR INSTANCE'S HOSTNAME"
|
||||
$ curl --location --request GET 'https://$GHES_HOSTNAME/api/v3/scim/v2/Users' \
|
||||
--header 'Content-Type: application/scim' \
|
||||
--header 'Authorization: Bearer $GHES_PAT'
|
||||
```
|
||||
|
||||
The command should return an empty array.
|
||||
1. Configure user provisioning in the application for {% data variables.product.product_name %} on your IdP. To request documentation for a supported IdP, contact your account manager on {% data variables.contact.contact_enterprise_sales %}. If your IdP is unsupported, you must create the application and configure SCIM manually.
|
||||
|
||||
{% endif %}
|
||||
@@ -79,7 +79,7 @@ If you don't already have single sign-on recovery codes for your enterprise, dow
|
||||
|
||||
After you disable authentication and provisioning, {% data variables.product.product_name %} will suspend all of the {% data variables.enterprise.prodname_managed_users %} for your enterprise. You can validate suspension of your enterprise's members using the web UI.
|
||||
|
||||
1. View the suspended members in your enterprise. For more information, see "[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-suspended-members-in-an-enterprise-with-managed-users)."
|
||||
1. View the suspended members in your enterprise. For more information, see "[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-suspended-members)."
|
||||
1. If all of your enterprise's members are not yet suspended, continue waiting, and review the logs on your SCIM provider.
|
||||
|
||||
* If you use Entra ID, suspension of your members can take up to 40 minutes. To expedite the process for an individual user, click the **Provision on Demand** button in the "Provisioning" tab of the application for {% data variables.product.prodname_emus %}.
|
||||
|
||||
@@ -26,7 +26,7 @@ topics:
|
||||
|
||||
After learning more about authentication and provisioning for each of these options, to determine which method is best for your enterprise, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/identifying-the-best-authentication-method-for-your-enterprise)."
|
||||
|
||||
{% elsif scim-for-ghes %}
|
||||
{% elsif ghes %}
|
||||
|
||||
Administrators who configure a {% data variables.product.product_name %} instance can use local accounts and built-in authentication on the instance. Alternatively, to centralize identity and access for an enterprise's web applications, administrators can configure an external authentication method. If you use SAML, you can optionally provision user accounts on the instance from your identity provider (IdP) using System for Cross-domain Identity Management (SCIM).
|
||||
|
||||
@@ -97,7 +97,7 @@ If you use [authentication through {% data variables.location.product_location %
|
||||
|
||||
Alternatively, if you use [{% data variables.product.prodname_emus %}](#authentication-with-enterprise-managed-users-and-federation), you must configure your IdP to provision user accounts within your enterprise on {% data variables.location.product_location %} using System for Cross-domain Identity Management (SCIM). For more information, see "[AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users)."
|
||||
|
||||
{% elsif scim-for-ghes %}
|
||||
{% elsif ghes %}
|
||||
|
||||
If you configure built-in authentication, CAS, LDAP, or SAML, {% data variables.product.product_name %} creates a user account when an authorized person signs into the instance, or "just in time" (JIT). Optionally, if you use SAML, you can provision user accounts from your identity provider (IdP) using SCIM. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise)."
|
||||
|
||||
|
||||
@@ -68,9 +68,9 @@ After you configure SAML, people who use {% data variables.location.product_loca
|
||||
|
||||
{% endif %}
|
||||
|
||||
For more information about the configuration of SAML SSO on {% data variables.product.product_name %}, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise)."{% ifversion ghec or scim-for-ghes %} To learn how to configure both authentication and {% ifversion ghes %}user {% endif %}provisioning for {% data variables.location.product_location %}, see the articles for individual IdPs in "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam)."{% endif %}
|
||||
For more information about the configuration of SAML SSO on {% data variables.product.product_name %}, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise)."
|
||||
|
||||
{% ifversion scim-for-ghes %}
|
||||
{% ifversion ghes %}
|
||||
|
||||
## About creation of user accounts
|
||||
|
||||
@@ -113,6 +113,4 @@ If your IdP supports encrypted assertions, you can configure encrypted assertion
|
||||
|
||||
* "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam)"
|
||||
* [SAML Wiki](https://wiki.oasis-open.org/security) on the OASIS website
|
||||
{%- ifversion scim-for-ghes %}
|
||||
* [System for Cross-domain Identity Management: Protocol (RFC 7644)](https://tools.ietf.org/html/rfc7644) on the IETF website
|
||||
{%- endif %}
|
||||
|
||||
@@ -24,6 +24,12 @@ shortTitle: Configure built-in authentication
|
||||
|
||||
By default, {% data variables.product.product_name %} uses built-in authentication. Each person creates a user account on {% data variables.location.product_location %} from an invitation or by signing up, and then authenticates with the credentials for the account to access your instance. Your {% data variables.product.product_name %} instance stores the authentication information for the account.
|
||||
|
||||
{% ifversion passkeys %}
|
||||
|
||||
By default, users can use passkeys for built-in authentication, but you can disable passkeys for your instance. See "[AUTOTITLE](/admin/managing-iam/using-built-in-authentication/disabling-passkeys-for-your-instance)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
You can prevent unauthenticated people from creating new user accounts on your instance. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-built-in-authentication/disabling-unauthenticated-sign-ups)."
|
||||
|
||||
{% data reusables.enterprise_user_management.alternatively-enable-external-authentication %}
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: Disabling passkeys for your instance
|
||||
intro: 'Learn how to disable passkeys for all users on your instance.'
|
||||
permissions: 'Site administrators'
|
||||
versions:
|
||||
ghes: '>=3.14'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
shortTitle: Disable passkeys
|
||||
---
|
||||
|
||||
Passkeys are enabled by default.
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.authentication %}
|
||||
1. In the "Passkeys" section, deselect **Enable passkeys**.
|
||||
{% data reusables.enterprise_management_console.save-settings %}
|
||||
|
||||
## Further reading
|
||||
|
||||
* "[AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys)"
|
||||
@@ -12,7 +12,7 @@ children:
|
||||
- /configuring-built-in-authentication
|
||||
- /inviting-people-to-use-your-instance
|
||||
- /disabling-unauthenticated-sign-ups
|
||||
- /disabling-passkeys-for-your-instance
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/using-built-in-authentication
|
||||
---
|
||||
|
||||
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
title: Configuring authentication and provisioning for your enterprise using Entra ID
|
||||
shortTitle: Configure with Entra ID
|
||||
intro: 'You can use a tenant in Microsoft Entra ID (previously known as Azure AD) as an identity provider (IdP) to centrally manage authentication and user provisioning for {% data variables.location.product_location %}.'
|
||||
permissions: 'Enterprise owners can configure authentication and provisioning for an enterprise on {% data variables.product.product_name %}.'
|
||||
versions:
|
||||
feature: scim-for-ghes
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /admin/identity-and-access-management/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-entra-id
|
||||
---
|
||||
|
||||
## About authentication and user provisioning with Entra ID
|
||||
|
||||
Entra ID is a service from Microsoft that allows you to centrally manage user accounts and access to web applications. For more information, see [What is Microsoft Entra ID?](https://learn.microsoft.com/entra/fundamentals/whatis) in the Microsoft Docs.
|
||||
|
||||
{% data reusables.saml.idp-saml-and-scim-explanation %}
|
||||
|
||||
{% data reusables.scim.ghes-beta-note %}
|
||||
|
||||
After you enable SAML SSO and SCIM for {% data variables.product.product_name %} using Entra ID, you can accomplish the following from your Entra ID tenant.
|
||||
|
||||
* Assign the {% data variables.product.product_name %} application on Entra ID to a user account to automatically create and grant access to a corresponding user account on {% data variables.product.product_name %}.
|
||||
* Unassign the {% data variables.product.product_name %} application to a user account on Entra ID to deactivate the corresponding user account on {% data variables.product.product_name %}.
|
||||
* Assign the {% data variables.product.product_name %} application to an IdP group on Entra ID to automatically create and grant access to user accounts on {% data variables.product.product_name %} for all members of the IdP group. In addition, the IdP group is available on {% data variables.product.product_name %} for connection to a team and its parent organization.
|
||||
* Unassign the {% data variables.product.product_name %} application from an IdP group to deactivate the {% data variables.product.product_name %} user accounts of all IdP users who had access only through that IdP group and remove the users from the parent organization. The IdP group will be disconnected from any teams on {% data variables.product.product_name %}.
|
||||
|
||||
For more information about managing identity and access for your enterprise on {% data variables.location.product_location %}, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam)."
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* To configure authentication and user provisioning for {% data variables.product.product_name %} using Entra ID, you must have an Entra ID account and tenant. For more information, see the [Entra ID website](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) and [Quickstart: Set up a tenant](https://learn.microsoft.com/entra/identity-platform/quickstart-create-new-tenant) in the Microsoft Docs.
|
||||
|
||||
{%- ifversion scim-for-ghes %}
|
||||
* {% data reusables.saml.ghes-you-must-configure-saml-sso %}
|
||||
{%- endif %}
|
||||
|
||||
* {% data reusables.saml.create-a-machine-user %}
|
||||
|
||||
## Configuring authentication and user provisioning with Entra ID
|
||||
|
||||
{% ifversion scim-for-ghes %}
|
||||
|
||||
1. Configure SAML SSO for {% data variables.location.product_location %}. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso)."
|
||||
1. Configure user provisioning with SCIM for your instance. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Managing enterprise owners
|
||||
|
||||
The steps to make a person an enterprise owner depend on whether you only use SAML or also use SCIM. For more information about enterprise owners, see "[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)."
|
||||
|
||||
If you configured provisioning, to grant the user enterprise ownership in {% data variables.product.product_name %}, assign the enterprise owner role to the user in Entra ID.
|
||||
|
||||
If you did not configure provisioning, to grant the user enterprise ownership in {% data variables.product.product_name %}, include the `administrator` attribute in the SAML assertion for the user account on the IdP, with the value of `true`. For more information about including the `administrator` attribute in the SAML claim from Entra ID, see [How to: customize claims issued in the SAML token for enterprise applications](https://docs.microsoft.com/azure/active-directory/develop/active-directory-saml-claims-customization) in the Microsoft Docs.
|
||||
@@ -1,119 +0,0 @@
|
||||
---
|
||||
title: Configuring user provisioning with SCIM for your enterprise
|
||||
shortTitle: Configure SCIM user provisioning
|
||||
intro: 'You can configure System for Cross-domain Identity Management (SCIM) for {% ifversion scim-for-ghes %}{% data variables.location.product_location %}{% endif %}, which automatically provisions user accounts when you assign the application for {% ifversion scim-for-ghes %}your instance{% endif %} to a user on your identity provider (IdP).'
|
||||
permissions: '{% ifversion scim-for-ghes %}Site administrators{% endif %} can configure user provisioning for {% ifversion scim-for-ghes %}a {% data variables.product.product_name %} instance{% endif %}.'
|
||||
versions:
|
||||
feature: scim-for-ghes
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
redirect_from:
|
||||
- /admin/authentication/configuring-user-provisioning-for-your-enterprise
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-user-provisioning-for-your-enterprise
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-for-your-enterprise
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise
|
||||
---
|
||||
|
||||
{% data reusables.scim.ghes-beta-note %}
|
||||
|
||||
## About user provisioning for {% data variables.product.product_name %}
|
||||
|
||||
{% ifversion scim-for-ghes %}If you use SAML single sign-on (SSO) for {% data variables.location.product_location %}, you{% endif %} can configure SCIM to automatically create or suspend user accounts and grant access{% ifversion scim-for-ghes %} to your instance{% endif %} when you assign or unassign the application on your IdP. For more information about SCIM, see [System for Cross-domain Identity Management: Protocol (RFC 7644)](https://tools.ietf.org/html/rfc7644) on the IETF website.
|
||||
|
||||
If you do not configure user provisioning with SCIM, your IdP will not communicate with {% data variables.product.product_name %} automatically when you assign or unassign the application to a user. Without SCIM, {% data variables.product.product_name %} creates a user account using SAML Just-in-Time (JIT) provisioning the first time someone navigates to {% data variables.product.product_name %} and signs in by authenticating through your IdP.
|
||||
|
||||
Configuring provisioning allows your IdP to communicate with {% data variables.location.product_location %} when you assign or unassign the application for {% data variables.product.product_name %} to a user on your IdP. When you assign the application, your IdP will prompt {% data variables.location.product_location %} to create an account and send an onboarding email to the user. When you unassign the application, your IdP will communicate with {% data variables.product.product_name %} to invalidate any SAML sessions and disable the member's account.
|
||||
|
||||
To configure provisioning for your enterprise, you must enable provisioning on {% data variables.product.product_name %}, then install and configure a provisioning application on your IdP.
|
||||
|
||||
{% ifversion scim-for-ghes %}
|
||||
|
||||
The provisioning application on your IdP communicates with {% data variables.product.product_name %} using the SCIM API. For more information, see "[AUTOTITLE](/rest/enterprise-admin/scim)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
## About identities and claims
|
||||
|
||||
After an IdP administrator grants a person access to {% data variables.location.product_location %}, the user can authenticate through the IdP to access {% data variables.product.product_name %} using SAML SSO.
|
||||
|
||||
During authentication, {% ifversion scim-for-ghes %}the instance{% endif %} attempts to associate the user with a SAML identity. By default, {% ifversion scim-for-ghes %}the instance{% endif %} compares the `NameID` claim from the IdP to the account's username. {% data variables.product.product_name %} normalizes the value of `NameID` for the comparison. For more information about username normalization, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication#about-username-normalization)."
|
||||
|
||||
If there is no existing account with a matching username on the instance, the user will fail to sign in.{% ifversion scim-for-ghes %} To make this match, {% data variables.product.product_name %} compares the SAML `NameId` claim from the IdP to the `username` claim for each user account provisioned by SCIM on the instance.{% endif %}
|
||||
|
||||
{% ifversion scim-for-ghes %}
|
||||
|
||||
During SAML authentication, some environments may use a value other than `NameID` as the unique identifying claim. If your environment does not use `NameID` to identify users, a site administrator can configure custom user attributes for the instance. {% data variables.product.product_name %} will respect this mapping when SCIM is configured. For more information about mapping user attributes, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
If {% data variables.product.product_name %} successfully identifies a user from the IdP, but account details such as email address, first name, or last name don't match, the instance overwrites the details with values from the IdP. Any email addresses other than the primary email provisioned by SCIM will also be deleted from the user account.
|
||||
|
||||
## Supported identity providers
|
||||
|
||||
{% ifversion ghes %}
|
||||
|
||||
During the private beta, your account team will provide documentation for the configuration of SCIM for {% data variables.product.product_name %} on a supported IdP.
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
{% ifversion scim-for-ghes %}
|
||||
|
||||
* {% data reusables.saml.ghes-you-must-configure-saml-sso %}
|
||||
|
||||
* You must allow built-in authentication for users who don't have an account on your IdP. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider)."
|
||||
|
||||
* Your IdP must support making SCIM calls to a Service Provider (SP).
|
||||
|
||||
{% endif %}
|
||||
|
||||
* You must have administrative access on your IdP to configure the application for user provisioning for {% data variables.product.product_name %}.
|
||||
|
||||
## Enabling user provisioning for your enterprise
|
||||
|
||||
{% ifversion scim-for-ghes %}
|
||||
|
||||
To perform provisioning actions on your instance, you will create a built-in user account and promote the account to an enterprise owner.
|
||||
|
||||
After you enable SCIM on a {% data variables.product.product_name %} instance, all user accounts are suspended. The built-in user account will continue to perform provisioning actions. After you grant a user access to your instance from your IdP, the IdP will communicate with the instance using SCIM to unsuspend the user's account.
|
||||
|
||||
{% endif %}
|
||||
|
||||
{%- ifversion scim-for-ghes %}
|
||||
1. Create a built-in user account to perform provisioning actions on your instance. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider#inviting-users-outside-your-provider-to-authenticate-to-your-instance)."
|
||||
1. Promote the dedicated user account to an enterprise owner. For more information, see "[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise#adding-an-enterprise-administrator-to-your-enterprise-account)."
|
||||
1. Sign into your instance as the new enterprise owner.
|
||||
1. Create a {% data variables.product.pat_v1 %} with **admin:enterprise** scope. Do not specify an expiration date for the {% data variables.product.pat_v1 %}. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
|
||||
|
||||
{% warning %}
|
||||
|
||||
**Warning**: Ensure that you don't specify an expiration date for the {% data variables.product.pat_v1 %}. If you specify an expiration date, SCIM will no longer function after the expiration date passes.
|
||||
|
||||
{% endwarning %}
|
||||
{% note %}
|
||||
|
||||
**Note**: You'll need this {% data variables.product.pat_generic %} to test the SCIM configuration, and to configure the application for SCIM on your IdP. Store the token securely in a password manager until you need the token again later in these instructions.
|
||||
|
||||
{% endnote %}
|
||||
{% data reusables.enterprise_installation.ssh-into-instance %}
|
||||
1. To enable SCIM, run the commands provided to you by your account manager on {% data variables.contact.contact_enterprise_sales %}.
|
||||
{% data reusables.enterprise_site_admin_settings.wait-for-configuration-run %}
|
||||
1. To validate that SCIM is operational, run the following commands. Replace _PAT FROM STEP 3_ and _YOUR INSTANCE'S HOSTNAME_ with actual values.
|
||||
|
||||
```shell
|
||||
$ GHES_PAT="PAT FROM STEP 3"
|
||||
$ GHES_HOSTNAME="YOUR INSTANCE'S HOSTNAME"
|
||||
$ curl --location --request GET 'https://$GHES_HOSTNAME/api/v3/scim/v2/Users' \
|
||||
--header 'Content-Type: application/scim' \
|
||||
--header 'Authorization: Bearer $GHES_PAT'
|
||||
```
|
||||
|
||||
The command should return an empty array.
|
||||
{%- endif %}
|
||||
1. Configure user provisioning in the application for {% data variables.product.product_name %} on your IdP.{% ifversion scim-for-ghes %} To request documentation for a supported IdP, contact your account manager on {% data variables.contact.contact_enterprise_sales %}. If your IdP is unsupported, you must create the application and configure SCIM manually.{% endif %}
|
||||
@@ -20,11 +20,9 @@ redirect_from:
|
||||
children:
|
||||
- /deciding-whether-to-configure-saml-for-your-enterprise-or-your-organizations
|
||||
- /configuring-saml-single-sign-on-for-your-enterprise
|
||||
- /configuring-user-provisioning-with-scim-for-your-enterprise
|
||||
- /managing-team-synchronization-for-organizations-in-your-enterprise
|
||||
- /configuring-saml-single-sign-on-for-your-enterprise-using-okta
|
||||
- /disabling-saml-single-sign-on-for-your-enterprise
|
||||
- /configuring-authentication-and-provisioning-for-your-enterprise-using-entra-id
|
||||
- /enabling-encrypted-assertions
|
||||
- /updating-a-users-saml-nameid
|
||||
- /switching-your-saml-configuration-from-an-organization-to-an-enterprise-account
|
||||
|
||||
Reference in New Issue
Block a user