Rename admin/github-actions/ directory (#51109)
This commit is contained in:
Sunbrye Ly
@@ -0,0 +1,65 @@
|
||||
---
|
||||
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.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Configuring SAML single sign-on for your enterprise using Okta
|
||||
intro: 'You can use Security Assertion Markup Language (SAML) single sign-on (SSO) with Okta to automatically manage access to your enterprise account on {% data variables.product.product_name %}.'
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-single-sign-on-for-your-enterprise-account-using-okta
|
||||
- /github/setting-up-and-managing-your-enterprise-account/configuring-saml-single-sign-on-for-your-enterprise-account-using-okta
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise-account-using-okta
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/configuring-saml-single-sign-on-for-your-enterprise-account-using-okta
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise-using-okta
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise-using-okta
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise-using-okta
|
||||
versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Authentication
|
||||
- Enterprise
|
||||
type: how_to
|
||||
shortTitle: Configure SAML SSO with Okta
|
||||
---
|
||||
|
||||
{% data reusables.enterprise-accounts.emu-saml-note %}
|
||||
|
||||
## About SAML with Okta
|
||||
|
||||
You can control access to your enterprise account in {% data variables.product.product_name %} and other web applications from one central interface by configuring the enterprise account to use SAML SSO with Okta, an Identity Provider (IdP).
|
||||
|
||||
SAML SSO controls and secures access to enterprise account resources like organizations, repositories, issues, and pull requests. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise)."
|
||||
|
||||
{% data reusables.saml.no-scim-for-enterprises %}
|
||||
|
||||
{% data reusables.saml.switching-from-org-to-enterprise %} For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account)."
|
||||
|
||||
Alternatively, you can also configure SAML SSO using Okta for an organization that uses {% data variables.product.prodname_ghe_cloud %}. For more information, see "[AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/configuring-saml-single-sign-on-and-scim-using-okta)."
|
||||
|
||||
## Adding the {% data variables.product.prodname_ghe_cloud %} application in Okta
|
||||
|
||||
{% data reusables.saml.okta-sign-into-your-account %}
|
||||
1. Navigate to the [{% data variables.product.prodname_ghe_cloud %} - Enterprise Accounts](https://www.okta.com/integrations/github-enterprise-cloud-enterprise-accounts) application in the Okta Integration Network and click **Add Integration**.
|
||||
{% data reusables.saml.okta-dashboard-click-applications %}
|
||||
1. Optionally, to the right of "Application label", type a descriptive name for the application.
|
||||
1. To the right of "{% data variables.product.prodname_dotcom %} Enterprises", type the name of your enterprise account. For example, if your enterprise account's URL is `https://github.com/enterprises/octo-corp`, type `octo-corp`.
|
||||
1. Click **Done**.
|
||||
|
||||
## Enabling and testing SAML SSO
|
||||
|
||||
{% data reusables.saml.okta-sign-into-your-account %}
|
||||
{% data reusables.saml.okta-dashboard-click-applications %}
|
||||
{% data reusables.saml.click-enterprise-account-application %}
|
||||
{% data reusables.saml.assign-yourself-to-okta %}
|
||||
{% data reusables.saml.okta-sign-on-tab %}
|
||||
1. To the right of Settings, click **Edit**.
|
||||
1. Under "Configured SAML Attributes", to the right of "groups", use the drop-down menu and select **Matches regex**.
|
||||
1. To the right of the drop-down menu, type `.*.*`.
|
||||
1. Click **Save**.
|
||||
{% data reusables.saml.okta-view-setup-instructions %}
|
||||
1. Enable SAML for your enterprise account using the information in the setup instructions. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise)."
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: Configuring SAML single sign-on for your enterprise
|
||||
shortTitle: Configure SAML SSO
|
||||
intro: 'You can control and secure access to {% ifversion ghec %}resources like repositories, issues, and pull requests within your enterprise''s organizations{% elsif ghes %}{% data variables.location.product_location %}{% endif %} by {% ifversion ghec %}enforcing{% elsif ghes %}configuring{% endif %} SAML single sign-on (SSO) through your identity provider (IdP).'
|
||||
permissions: '{% ifversion ghes %}Site administrators{% elsif ghec %}Enterprise owners{% endif %} can configure SAML SSO for {% ifversion ghec %}an enterprise on {% data variables.product.product_name %}{% elsif ghes %}a {% data variables.product.product_name %} instance{% endif %}.'
|
||||
versions:
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
redirect_from:
|
||||
- /admin/authentication/configuring-saml-single-sign-on-for-your-enterprise
|
||||
- /github/setting-up-and-managing-your-enterprise/enabling-saml-single-sign-on-for-organizations-in-your-enterprise-account
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/enabling-saml-single-sign-on-for-organizations-in-your-enterprise-account
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/enforcing-saml-single-sign-on-for-organizations-in-your-enterprise-account
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise
|
||||
---
|
||||
|
||||
{% data reusables.enterprise-accounts.emu-saml-note %}
|
||||
|
||||
## About SAML SSO
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
{% data reusables.saml.dotcom-saml-explanation %}
|
||||
|
||||
{% data reusables.saml.saml-accounts %}
|
||||
|
||||
For more information, see "[AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on)."
|
||||
|
||||
{% data reusables.saml.about-saml-enterprise-accounts %}
|
||||
|
||||
{% data reusables.saml.about-saml-access-enterprise-account %} For more information, see "[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise)."
|
||||
|
||||
{% data reusables.saml.no-scim-for-enterprises %}
|
||||
|
||||
{% data reusables.saml.saml-disabled-linked-identities-removed %}
|
||||
|
||||
{% data reusables.apps.reauthorize-apps-saml %}
|
||||
|
||||
{% elsif ghes %}
|
||||
|
||||
SAML SSO allows you to centrally control and secure access to {% data variables.location.product_location %} from your SAML IdP. When an unauthenticated user visits {% data variables.location.product_location %} in a browser, {% data variables.product.product_name %} will redirect the user to your SAML IdP to authenticate. After the user successfully authenticates with an account on the IdP, the IdP redirects the user back to {% data variables.location.product_location %}. {% data variables.product.product_name %} validates the response from your IdP, then grants access to the user.
|
||||
|
||||
After a user successfully authenticates on your IdP, the user's SAML session for {% data variables.location.product_location %} is active in the browser for 24 hours. After 24 hours, the user must authenticate again with your IdP.
|
||||
|
||||
{% data reusables.saml.saml-ghes-account-revocation %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Supported identity providers
|
||||
|
||||
{% data reusables.saml.saml-supported-idps %}
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
For more information about connecting Microsoft Entra ID (previously known as Azure AD) to your enterprise, see [Tutorial: Microsoft Entra SSO integration with GitHub Enterprise Cloud - Enterprise Account](https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-enterprise-cloud-enterprise-account-tutorial) in Microsoft Docs.
|
||||
|
||||
{% elsif ghes %}
|
||||
|
||||
For more information about connecting Entra ID to your enterprise, see [Tutorial: Microsoft Entra SSO integration with GitHub Enterprise Server](https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-ae-tutorial) in Microsoft Docs.
|
||||
|
||||
## Username considerations with SAML
|
||||
|
||||
{% data reusables.enterprise_user_management.consider-usernames-for-external-authentication %} For more information, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
## Enforcing SAML single-sign on for organizations in your enterprise account
|
||||
|
||||
When you enforce SAML SSO for your enterprise, the enterprise configuration will override any existing organization-level SAML configurations. {% data reusables.saml.switching-from-org-to-enterprise %} For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account)."
|
||||
|
||||
When you enforce SAML SSO for an organization, {% data variables.product.company_short %} removes any members of the organization that have not authenticated successfully with your SAML IdP. When you require SAML SSO for your enterprise, {% data variables.product.company_short %} does not remove members of the enterprise that have not authenticated successfully with your SAML IdP. The next time a member accesses the enterprise's resources, the member must authenticate with your SAML IdP.
|
||||
|
||||
For more detailed information about how to enable SAML using Okta, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise-using-okta)."
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.settings-tab %}
|
||||
{% data reusables.enterprise-accounts.security-tab %}
|
||||
1. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %}
|
||||
1. Under "SAML single sign-on", select **Require SAML authentication**.
|
||||
1. In the **Sign on URL** field, type the HTTPS endpoint of your IdP for single sign-on requests. This value is available in your IdP configuration.
|
||||
1. Optionally, in the **Issuer** field, type your SAML issuer URL to verify the authenticity of sent messages.
|
||||
1. Under **Public Certificate**, paste a certificate to verify SAML responses. This is the public key corresponding to the private key used to sign SAML responses.
|
||||
|
||||
To find the certificate, refer to the documentation for your IdP. Some IdPs call this an X.509 certificate.
|
||||
|
||||
{% data reusables.saml.edit-signature-and-digest-methods %}
|
||||
1. Before enabling SAML SSO for your enterprise, to ensure that the information you've entered is correct, click **Test SAML configuration** . {% data reusables.saml.test-must-succeed %}
|
||||
1. Click **Save**.
|
||||
{% data reusables.enterprise-accounts.download-recovery-codes %}
|
||||
|
||||
{% elsif ghes %}
|
||||
|
||||
## Configuring SAML SSO
|
||||
|
||||
You can enable or disable SAML authentication for {% data variables.location.product_location %}, or you can edit an existing configuration. You can view and edit authentication settings for {% data variables.product.product_name %} in the {% data variables.enterprise.management_console %}. For more information, see "[AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console)."
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: {% data reusables.enterprise.test-in-staging %}
|
||||
|
||||
{% endnote %}
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.authentication %}
|
||||
1. Under "Authentication", select **SAML**.
|
||||
1. {% data reusables.enterprise_user_management.built-in-authentication-option %}
|
||||
1. Optionally, to enable unsolicited response SSO, select **IdP initiated SSO**. By default, {% data variables.product.prodname_ghe_server %} will reply to an unsolicited Identity Provider (IdP) initiated request with an `AuthnRequest` back to the IdP.
|
||||
|
||||
{% tip %}
|
||||
|
||||
**Note**: We recommend keeping this value **unselected**. You should enable this feature **only** in the rare instance that your SAML implementation does not support service provider initiated SSO, and when advised by {% data variables.contact.enterprise_support %}.
|
||||
|
||||
{% endtip %}
|
||||
|
||||
1. Optionally, if you do not want your SAML provider to determine administrator rights for users on {% data variables.location.product_location %}, select **Disable administrator demotion/promotion**
|
||||
{%- ifversion ghes %}
|
||||
1. Optionally, to allow {% data variables.location.product_location %} to receive encrypted assertions from your SAML IdP, select **Require encrypted assertions**.
|
||||
|
||||
You must ensure that your IdP supports encrypted assertions and that the encryption and key transport methods in the management console match the values configured on your IdP. You must also provide {% data variables.location.product_location %}'s public certificate to your IdP. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/enabling-encrypted-assertions)."
|
||||
{%- endif %}
|
||||
1. Under "Single sign-on URL," type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. This value is provided by your IdP configuration. If the host is only available from your internal network, you may need to [configure {% data variables.location.product_location %} to use internal nameservers](/admin/configuration/configuring-network-settings/configuring-dns-nameservers).
|
||||
1. Optionally, in the **Issuer** field, type your SAML issuer's name. This verifies the authenticity of messages sent to {% data variables.location.product_location %}.
|
||||
1. Select the **Signature Method** and **Digest Method** dropdown menus, then click the hashing algorithm used by your SAML issuer to verify the integrity of the requests from {% data variables.location.product_location %}.
|
||||
1. Select the **Name Identifier Format** dropdown menu, then click a format.
|
||||
1. Under "Verification certificate," click **Choose File**, then choose a certificate to validate SAML responses from the IdP.
|
||||
1. Under "User attributes", modify the SAML attribute names to match your IdP if needed, or accept the default names.
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% ifversion ghec or ghes %}
|
||||
|
||||
## Further reading
|
||||
|
||||
{%- ifversion ghec %}
|
||||
* "[AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization)"
|
||||
{%- endif %}
|
||||
{%- ifversion ghes %}
|
||||
* "[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator)"
|
||||
{%- endif %}
|
||||
|
||||
{% endif %}
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
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 %}
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Deciding whether to configure SAML for your enterprise or your organizations
|
||||
shortTitle: Enterprise or organization
|
||||
intro: 'You can configure SAML for your enterprise account, with the same configuration applying to all of its organizations, or you can create separate configurations for individual organizations.'
|
||||
versions:
|
||||
ghec: '*'
|
||||
type: overview
|
||||
topics:
|
||||
- Accounts
|
||||
- Access management
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/deciding-whether-to-configure-saml-for-your-enterprise-or-your-organizations
|
||||
---
|
||||
|
||||
{% data reusables.enterprise.ghec-authentication-options %} For more information, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise)."
|
||||
|
||||
If you decide to use SAML instead of {% data variables.product.prodname_emus %}, you must choose whether to configure SAML at the enterprise level or the organization level.
|
||||
|
||||
If some groups within your enterprise must use different SAML authentication providers to grant access to your resources on {% data variables.location.product_location %}, configure SAML for individual organizations. You can implement SAML for your organizations over time by allowing users to gradually authenticate using SAML, or you can require SAML authentication by a certain date. Organization members who do not authenticate using SAML by this date will be removed. For more information about organization-level SAML, see "[AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on)."
|
||||
|
||||
If you configure SAML at the organization level, members are not required to authenticate via SAML to access internal repositories. For more information about internal repositories, see "[AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-internal-repositories)."
|
||||
|
||||
If you need to protect internal repositories or enforce a consistent authentication experience for every organization in your enterprise, you can configure SAML authentication for your enterprise account instead. The SAML configuration for your enterprise overrides any SAML configuration for individual organizations, and organizations cannot override the enterprise configuration. After you configure SAML for your enterprise, organization members must authenticate with SAML before accessing organization resources, including internal repositories.
|
||||
|
||||
SCIM is not available for enterprise accounts without {% data variables.product.prodname_emus %}, and team synchronization is only available for SAML at the enterprise level if you use Microsoft Entra ID (previously known as Azure AD) as an IdP. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise)."
|
||||
|
||||
Regardless of the SAML implementation you choose, you cannot add external collaborators to organizations or teams. You can only add external collaborators to individual repositories.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Disabling SAML single sign-on for your enterprise
|
||||
intro: You can disable SAML single sign-on (SSO) for your enterprise account.
|
||||
versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Authentication
|
||||
- Enterprise
|
||||
type: how_to
|
||||
shortTitle: Disable SAML SSO
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/disabling-saml-single-sign-on-for-your-enterprise
|
||||
---
|
||||
|
||||
## About disabled SAML SSO for your enterprise
|
||||
|
||||
After you disable SAML SSO for your enterprise, the following effects apply:
|
||||
|
||||
* All external identities for your enterprise will be removed. For more information, see - 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)."
|
||||
* Any SAML settings configured for individual organizations within the enterprise will take effect. For more information, see "[AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization)."
|
||||
|
||||
## Disabling SAML
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** If you're unable to access the enterprise because your IdP is unavailable, you can use a recovery code to bypass SSO. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable)."
|
||||
|
||||
{% endnote %}
|
||||
|
||||
{% data reusables.enterprise-accounts.settings-tab %}
|
||||
{% data reusables.enterprise-accounts.security-tab %}
|
||||
1. Under "SAML single sign-on", deselect **Require SAML authentication**.
|
||||
1. Click **Save**.
|
||||
|
||||
## Further reading
|
||||
|
||||
* "[AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/disabling-authentication-for-enterprise-managed-users)"
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Enabling encrypted assertions
|
||||
shortTitle: Enable encrypted assertions
|
||||
intro: 'You can improve {% data variables.location.product_location %}''s security with SAML single sign-on (SSO) by encrypting the messages that your SAML identity provider (IdP) sends.'
|
||||
permissions: 'Site administrators can configure encrypted assertions for a {% data variables.product.product_name %} instance.'
|
||||
versions:
|
||||
ghes: '> 3.3'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- Security
|
||||
- SSO
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/enabling-encrypted-assertions
|
||||
---
|
||||
|
||||
## About encrypted assertions
|
||||
|
||||
If your IdP support encryption of assertions, you can configure encrypted assertions on {% data variables.product.product_name %} for increased security during the authentication process.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To enable encrypted assertions for authentication to {% data variables.product.product_name %}, you must configure SAML authentication, and your IdP must support encrypted assertions.
|
||||
|
||||
## Enabling encrypted assertions
|
||||
|
||||
To enable encrypted assertions, you must provide {% data variables.location.product_location %}'s public certificate to your IdP, and configure encryption settings that match your IdP.
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: {% data reusables.enterprise.test-in-staging %}
|
||||
|
||||
{% endnote %}
|
||||
|
||||
1. Optionally, enable SAML debugging. SAML debugging records verbose entries in {% data variables.product.product_name %}'s authentication log, and may help you troubleshoot failed authentication attempts. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication#configuring-saml-debugging)."
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.authentication %}
|
||||
1. Select **Require encrypted assertions**.
|
||||
1. To the right of "Encryption Certificate", to save a copy of {% data variables.location.product_location %}'s public certificate on your local machine, click **Download**.
|
||||
1. Sign into your SAML IdP as an administrator.
|
||||
1. In the application for {% data variables.location.product_location %}, enable encrypted assertions.
|
||||
* Note the encryption method and key transport method.
|
||||
* Provide the public certificate you downloaded in step 7.
|
||||
1. Return to the management console on {% data variables.location.product_location %}.
|
||||
1. To the right of "Encryption Method", select the encryption method for your IdP from step 9.
|
||||
1. To the right of "Key Transport Method", select the key transport method for your IdP from step 9.
|
||||
1. Click **Save settings**.
|
||||
{% data reusables.enterprise_site_admin_settings.wait-for-configuration-run %}
|
||||
|
||||
If you enabled SAML debugging to test authentication with encrypted assertions, disable SAML debugging when you're done testing. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication#configuring-saml-debugging)."
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Using SAML for enterprise IAM
|
||||
shortTitle: SAML for enterprise IAM
|
||||
intro: 'You can centrally manage {% ifversion ghes %}accounts and {% endif %}access to {% ifversion ghes %}{% data variables.location.product_location %}{% elsif ghec %}your enterprise''s resources{% endif %} with SAML single sign-on (SSO){% ifversion ghec %} and System for Cross-domain Identity Management (SCIM){% endif %}.'
|
||||
versions:
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider
|
||||
- /enterprise/admin/articles/configuring-saml-authentication
|
||||
- /enterprise/admin/articles/about-saml-authentication
|
||||
- /enterprise/admin/user-management/using-saml
|
||||
- /enterprise/admin/authentication/using-saml
|
||||
- /admin/authentication/using-saml
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-saml
|
||||
- /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-saml
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam
|
||||
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
|
||||
- /troubleshooting-saml-authentication
|
||||
---
|
||||
|
||||
{% data reusables.enterprise-accounts.emu-saml-note %}
|
||||
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: Managing team synchronization for organizations in your enterprise
|
||||
intro: 'You can enable team synchronization between Microsoft Entra ID (previously known as Azure AD) and {% data variables.product.product_name %} to allow organizations owned by your enterprise account to manage team membership through IdP groups.'
|
||||
permissions: Enterprise owners can manage team synchronization for an enterprise account.
|
||||
versions:
|
||||
ghec: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Enterprise
|
||||
- SSO
|
||||
- Teams
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-team-synchronization-for-organizations-in-your-enterprise-account
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/managing-team-synchronization-for-organizations-in-your-enterprise-account
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise/managing-team-synchronization-for-organizations-in-your-enterprise
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/managing-team-synchronization-for-organizations-in-your-enterprise
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise
|
||||
shortTitle: Manage team synchronization
|
||||
---
|
||||
|
||||
{% data reusables.enterprise-accounts.emu-scim-note %}
|
||||
|
||||
## About team synchronization for enterprise accounts
|
||||
|
||||
If you use SAML at the enterprise level with Entra ID as your IdP, you can enable team synchronization for your enterprise account to allow organization owners and team maintainers to synchronize teams in the organizations owned by your enterprise accounts with IdP groups.
|
||||
|
||||
{% data reusables.identity-and-permissions.about-team-sync %}
|
||||
|
||||
{% ifversion team-sync-manage-org-invites %}
|
||||
{% data reusables.identity-and-permissions.team-sync-org-invites %}
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.identity-and-permissions.sync-team-with-idp-group %}
|
||||
|
||||
{% data reusables.identity-and-permissions.team-sync-disable %}
|
||||
|
||||
You can also configure and manage team synchronization for an individual organization. For more information, see "[AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization)."
|
||||
|
||||
{% data reusables.identity-and-permissions.team-sync-usage-limits %}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* You must use an Entra ID commercial tenant, not Gov Cloud.
|
||||
* You or your Entra ID administrator must be a Global administrator or a Privileged Role administrator in Entra ID.
|
||||
* You must enforce SAML single sign-on for organizations in your enterprise account with your supported IdP. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise)."
|
||||
* You must authenticate to your enterprise account using SAML SSO and the supported IdP. For more information, see "[AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on)."
|
||||
|
||||
## Managing team synchronization for Entra ID
|
||||
|
||||
{% data reusables.identity-and-permissions.team-sync-azure-permissions %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.settings-tab %}
|
||||
{% data reusables.enterprise-accounts.security-tab %}
|
||||
{% data reusables.identity-and-permissions.team-sync-confirm-saml %}
|
||||
{% data reusables.identity-and-permissions.enable-team-sync-azure %}
|
||||
{% data reusables.identity-and-permissions.team-sync-confirm %}
|
||||
1. Review the details for the IdP tenant you want to connect to your enterprise account, then click **Approve**.
|
||||
1. To disable team synchronization, under "Team synchronization", click **Disable team synchronization**.
|
||||
|
||||
{% ifversion team-sync-manage-org-invites %}
|
||||
|
||||
## Managing whether team synchronization can re-invite non-members to organizations
|
||||
|
||||
{% data reusables.saml.team-sync-pending-invites %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.settings-tab %}
|
||||
{% data reusables.enterprise-accounts.security-tab %}
|
||||
1. Under "Team synchronization", select or deselect **Do not allow Team Sync to re-invite past members to organizations that were removed by an organization owner.**
|
||||
{% endif %}
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: Switching your SAML configuration from an organization to an enterprise account
|
||||
intro: Learn special considerations and best practices for replacing an organization-level SAML configuration with an enterprise-level SAML configuration.
|
||||
permissions: Enterprise owners can configure SAML single sign-on for an enterprise account.
|
||||
versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Organizations
|
||||
type: how_to
|
||||
shortTitle: From organization to enterprise
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account
|
||||
---
|
||||
|
||||
## About SAML single sign-on for enterprise accounts
|
||||
|
||||
{% data reusables.saml.dotcom-saml-explanation %} {% data reusables.saml.about-saml-enterprise-accounts %}
|
||||
|
||||
{% data reusables.saml.switching-from-org-to-enterprise %}
|
||||
|
||||
When you configure SAML SSO at the organization level, each organization must be configured with a unique SSO tenant in your IdP, which means that your members will be associated with a unique SAML identity record for each organization they have successfully authenticated with. If you configure SAML SSO for your enterprise account instead, each enterprise member will have one SAML identity that is used for all organizations owned by the enterprise account.
|
||||
|
||||
After you configure SAML SSO for your enterprise account, the new configuration will override any existing SAML SSO configurations for organizations owned by the enterprise account. Any team synchronization settings you have configured will also be removed from these organizations. If you intend to re-enable team synchronization, before enabling SAML SSO for your enterprise, take note of the current team sync configuration in the affected organizations. For more information, see "[AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization)."
|
||||
|
||||
Enterprise members will not be notified when an enterprise owner enables SAML for the enterprise account. If SAML SSO was previously enforced at the organization level, members should not see a major difference when navigating directly to organization resources. The members will continue to be prompted to authenticate via SAML. If members navigate to organization resources via their IdP dashboard, they will need to click the new tile for the enterprise-level app, instead of the old tile for the organization-level app. The members will then be able to choose the organization to navigate to.
|
||||
|
||||
Any {% data variables.product.pat_generic %}s, SSH keys, {% data variables.product.prodname_oauth_apps %}, and {% data variables.product.prodname_github_apps %} that were previously authorized for the organization will continue to be authorized for the organization. However, members will need to authorize any PATs, SSH keys, {% data variables.product.prodname_oauth_apps %}, and {% data variables.product.prodname_github_apps %} that were never authorized for use with SAML SSO for the organization.
|
||||
|
||||
SCIM provisioning is not currently supported when SAML SSO is configured for an enterprise account. If you are currently using SCIM for an organization owned by your enterprise account, you will lose this functionality when switching to an enterprise-level configuration.
|
||||
|
||||
You are not required to remove any organization-level SAML configurations before configuring SAML SSO for your enterprise account, but you may want to consider doing so. If SAML is ever disabled for the enterprise account in the future, any remaining organization-level SAML configurations will take effect. Removing the organization-level configurations can prevent unexpected issues in the future.
|
||||
|
||||
For more information about the decision to implement SAML SSO at the organization or enterprise level, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#considerations-for-enabling-saml-for-an-enterprise-or-organization)."
|
||||
|
||||
## Switching your SAML configuration from an organization to an enterprise account
|
||||
|
||||
1. Enforce SAML SSO for your enterprise account, making sure all organization members are assigned or given access to the IdP app being used for the enterprise account. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise)."
|
||||
1. If you kept any organization-level SAML configurations in place, to prevent confusion, consider hiding the tile for the organization-level apps in your IdP.
|
||||
1. Advise your enterprise members about the change.
|
||||
* Members will no longer be able to access their organizations by clicking the SAML app for the organization in the IdP dashboard. They will need to use the new app configured for the enterprise account.
|
||||
* Members will need to authorize any PATs or SSH keys that were not previously authorized for use with SAML SSO for their organization. For more information, see "[AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)" and "[AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on)."
|
||||
* Members may need to reauthorize {% data variables.product.prodname_oauth_apps %} that were previously authorized for the organization. For more information, see "[AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on#about-oauth-apps-github-apps-and-saml-sso)."
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Troubleshooting SAML authentication
|
||||
shortTitle: Troubleshoot SAML SSO
|
||||
intro: 'If you use SAML single sign-on (SSO) and people are unable to authenticate to access {% data variables.location.product_location %}, you can troubleshoot the problem.'
|
||||
versions:
|
||||
ghes: '*'
|
||||
ghec: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- Security
|
||||
- SSO
|
||||
- Troubleshooting
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication
|
||||
---
|
||||
|
||||
{% ifversion ghes %}
|
||||
|
||||
## About problems with SAML authentication
|
||||
|
||||
{% data variables.product.product_name %} logs error messages for failed SAML authentication in the {% ifversion opentelemetry-and-otel-log-migration-phase-1 %}systemd journal logs{% endif %} {% ifversion opentelemetry-and-otel-log-migration-phase-1 %}for the `github-unicorn` container{% endif %}. You can review responses in {% ifversion opentelemetry-and-otel-log-migration-phase-1 %}this log{% endif %}, and you can also configure more verbose logging.
|
||||
|
||||
For more information about SAML response requirements, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference#saml-response-requirements)."
|
||||
|
||||
## Configuring SAML debugging
|
||||
|
||||
You can configure {% data variables.product.product_name %} to write verbose debug logs for every SAML authentication attempt. You may be able to troubleshoot failed authentication attempts with this extra output.
|
||||
|
||||
{% warning %}
|
||||
|
||||
**Warnings**:
|
||||
|
||||
* Only enable SAML debugging temporarily, and disable debugging immediately after you finish troubleshooting. If you leave debugging enabled, the size of the {% ifversion opentelemetry-and-otel-log-migration-phase-1 %}logs{% endif %} increases much faster than usual, which can negatively impact the performance of {% data variables.product.product_name %}.
|
||||
* Test new authentication settings for {% data variables.location.product_location %} in a staging environment before you apply the settings in your production environment. For more information, see "[AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance)."
|
||||
|
||||
{% endwarning %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.options-tab %}
|
||||
1. Under "SAML debugging", select the drop-down and click **Enabled**.
|
||||
1. Attempt to sign into {% data variables.location.product_location %} through your SAML IdP.
|
||||
1. Review the debug output in {% ifversion opentelemetry-and-otel-log-migration-phase-1 %}the systemd journal for `github-unicorn`{% endif %} on {% data variables.location.product_location %}. {% ifversion opentelemetry-and-otel-log-migration-phase-1 %}For more information, see "[AUTOTITLE](/admin/monitoring-managing-and-updating-your-instance/monitoring-your-appliance/about-system-logs#system-logs-in-the-systemd-journal-for-github-enterprise-server)."{% endif %}
|
||||
1. When you're done troubleshooting, select the drop-down and click **Disabled**.
|
||||
|
||||
## Decoding responses
|
||||
|
||||
Some output in {% ifversion opentelemetry-and-otel-log-migration-phase-1 %}the systemd journal for `github-unicorn`{% endif %} may be Base64-encoded. You can access the administrative shell and use the `base64` utility on {% data variables.location.product_location %} to decode these responses. For more information, see "[AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh)."
|
||||
|
||||
To decode the output, run the following command, replacing ENCODED_OUTPUT with the encoded output from the log.
|
||||
|
||||
```shell
|
||||
base64 --decode ENCODED_OUTPUT
|
||||
```
|
||||
|
||||
## Error: "Another user already owns the account"
|
||||
|
||||
When a user signs into {% data variables.location.product_location %} for the first time with SAML authentication, {% data variables.product.product_name %} creates a user account on the instance and maps the SAML `NameID` and `nameid-format` to the account.
|
||||
|
||||
When the user signs in again, {% data variables.product.prodname_ghe_server %} compares the account's `NameID` and `nameid-format` mapping to the IdP's response. If the `NameID` or `nameid-format` in the IdP's response no longer matches the values that {% data variables.product.product_name %} expects for the user, the sign-in will fail. The user will see the following message.
|
||||
|
||||
> Another user already owns the account. Please have your administrator check the authentication log.
|
||||
|
||||
The message typically indicates that the person's username or email address has changed on the IdP. Ensure that the `NameID` and `nameid-format` mapping for the user account on {% data variables.product.prodname_ghe_server %} matches the user's `NameID` and `nameid-format` on your IdP. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/updating-a-users-saml-nameid)."
|
||||
|
||||
## Error: Recipient in SAML response was blank or not valid
|
||||
|
||||
If the `Recipient` does not match the ACS URL for {% data variables.location.product_location %}, one of the following two error messages will appear in the authentication log when a user attempts to authenticate.
|
||||
|
||||
```text
|
||||
Recipient in the SAML response must not be blank.
|
||||
```
|
||||
|
||||
```text
|
||||
Recipient in the SAML response was not valid.
|
||||
```
|
||||
|
||||
Ensure that you set the value for `Recipient` on your IdP to the full ACS URL for {% data variables.location.product_location %}. For example, `https://ghe.corp.example.com/saml/consume`.
|
||||
|
||||
## Error: "SAML Response is not signed or has been modified"
|
||||
|
||||
If your IdP does not sign the SAML response, or the signature does not match the contents, the following error message will appear in the authentication log.
|
||||
|
||||
```text
|
||||
SAML Response is not signed or has been modified.
|
||||
```
|
||||
|
||||
Ensure that you configure signed assertions for the {% data variables.product.product_name %} application on your IdP.
|
||||
|
||||
## Error: "Audience is invalid" or "No assertion found"
|
||||
|
||||
If the IdP's response has a missing or incorrect value for `Audience`, the following error message will appear in the authentication log.
|
||||
|
||||
```text
|
||||
Audience is invalid. Audience attribute does not match https://YOUR-INSTANCE-URL
|
||||
```
|
||||
|
||||
Ensure that you set the value for `Audience` on your IdP to the `EntityId` for {% data variables.location.product_location %}, which is the full URL to your instance. For example, `https://ghe.corp.example.com`.
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.saml.current-time-earlier-than-notbefore-condition %}
|
||||
|
||||
{% ifversion ghec %}
|
||||
{% data reusables.saml.authentication-loop %}
|
||||
{% endif %}
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Updating a user's SAML NameID
|
||||
shortTitle: Update SAML NameID
|
||||
intro: 'When an account''s `NameID` changes on your identity provider (IdP) and the person can no longer {% ifversion ghes %}sign into {% data variables.location.product_location %}{% elsif ghec %}authenticate to access your enterprise''s resources{% endif %}, you must {% ifversion ghec %}either contact {% data variables.product.company_short %} Support or revoke the person''s linked identity{% elsif ghes %}update the `NameID` mapping on {% data variables.location.product_location %}{% endif %}.'
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
redirect_from:
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/updating-a-users-saml-nameid
|
||||
---
|
||||
|
||||
## About updates to users' SAML `NameID`
|
||||
|
||||
In some situations, you may need to update values associated with a person's account on your SAML IdP. If that identifier is also the `NameID` that you use for authentication on {% data variables.product.product_name %}, you must update the `NameID` mapping on your instance so the person can continue to authenticate successfully. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication)."
|
||||
|
||||
To update user SAML `NameID` mappings in bulk, you can use the `ghe-saml-mapping-csv` command. For more information, see "[AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-saml-mapping-csv)."
|
||||
|
||||
## Updating a user's SAML `NameID`
|
||||
|
||||
Enterprise owners can update a user's SAML `NameID` on a {% data variables.product.product_name %} instance.
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
1. In the left sidebar, click **All users**.
|
||||
1. In the list of users, click the username you'd like to update the `NameID` mapping for.
|
||||
{% data reusables.enterprise_site_admin_settings.security-tab %}
|
||||
1. To the right of "Update SAML NameID", click **Edit** .
|
||||
1. In the "NameID" field, type the new `NameID` for the user.
|
||||
1. Click **Update NameID**.
|
||||
Reference in New Issue
Block a user