{"meta":{"title":"Restricting access to GitHub.com using a corporate proxy","intro":"Configure your proxy to block people from accessing GitHub.com with personal accounts.","product":"Enterprise administrators","breadcrumbs":[{"href":"/en/enterprise-cloud@latest/admin","title":"Enterprise administrators"},{"href":"/en/enterprise-cloud@latest/admin/configuring-settings","title":"Configuration"},{"href":"/en/enterprise-cloud@latest/admin/configuring-settings/hardening-security-for-your-enterprise","title":"Harden security"},{"href":"/en/enterprise-cloud@latest/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-access-to-githubcom-using-a-corporate-proxy","title":"Block personal accounts"}],"documentType":"article"},"body":"# Restricting access to GitHub.com using a corporate proxy\n\nConfigure your proxy to block people from accessing GitHub.com with personal accounts.\n\nIf you use Enterprise Managed Users, you can block users on your network from authenticating to GitHub.com with accounts that are not members of your enterprise. This helps reduce the risk of your company's data being exposed to the public.\n\nTo enforce this restriction, you will configure your network proxy or firewall to inject a header into your users' web and API requests to GitHub.com.\n\nThis feature requires an external firewall or proxy. GitHub Support cannot assist with setup or troubleshooting for external tools such as these. For more about scope of support, see [About GitHub Support](/en/enterprise-cloud@latest/support/learning-about-github-support/about-github-support#scope-of-support).\n\n## Enabling access restrictions\n\nThis feature is not enabled by default. An enterprise owner can enable the feature for your enterprise.\n\n1. Navigate to your enterprise. For example, from the [Enterprises](https://github.com/settings/enterprises?ref_product=ghec\\&ref_type=engagement\\&ref_style=text) page on GitHub.com.\n2. At the top of the page, click **Settings**.\n3. Under **Settings**, click **Authentication security**.\n4. In the \"Enterprise access restrictions\" section, select **Enable enterprise access restrictions**.\n\n## Prerequisites\n\n* You must use an enterprise with managed users on GitHub.com.\n * You'll know you're using an enterprise with managed users if all your users' usernames are appended with your enterprise's shortcode.\n * If you use GitHub Enterprise Cloud with data residency, your enterprise resides on a dedicated subdomain of GHE.com, so the header is not required to differentiate traffic to your enterprise's resources.\n* To enforce the restriction, all traffic must flow through a proxy or firewall. The proxy or firewall must:\n * Be capable of intercepting and editing traffic, commonly called a \"break and inspect\" proxy\n * Support arbitrary header injection\n* Your enterprise owner has enabled this feature.\n\n## Finding the header\n\nTo enforce the restriction, you will inject a header into all traffic going to certain supported endpoints. The header is in the following format.\n\n```text\nsec-GitHub-allowed-enterprise: ENTERPRISE-ID\n```\n\nAn enterprise owner can identify the correct enterprise ID to use in the header for your enterprise.\n\n1. Navigate to your enterprise. For example, from the [Enterprises](https://github.com/settings/enterprises?ref_product=ghec\\&ref_type=engagement\\&ref_style=text) page on GitHub.com.\n2. At the top of the page, click **Settings**.\n3. Under **Settings**, click **Authentication security**.\n4. In the \"Enterprise access restrictions\" section, find the header for your enterprise.\n\n## Using the header\n\nFor best results, configure your proxy to inject the header into all traffic to the following **supported endpoints**.\n\n| Endpoint | Purpose |\n| --------------------- | ---------------------------------------------------- |\n| `github.com/*` | Web traffic to GitHub.com |\n| `api.github.com/*` | REST and GraphQL API requests |\n| `*.githubcopilot.com` | Traffic required for certain GitHub Copilot features |\n\nThis will prevent people on your network from accessing these endpoints with user accounts that are not owned by your enterprise. Alongside this feature, you can block traffic from outside your network by setting up an IP allow list. See [Restricting network traffic to your enterprise with an IP allow list](/en/enterprise-cloud@latest/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list).\n\n> \\[!NOTE] Access to `github.com/login` is required to create support tickets. To ensure users with support entitlements can request help, you may want to exempt these users from the restriction.\n\n## Enabling access restrictions for multiple enterprises\n\nEnterprise owners can enforce the restriction across multiple enterprise accounts.\n\n1. Enable the feature for each enterprise account. See [Enabling access restrictions](#enabling-access-restrictions).\n2. Inject a header into all traffic going to certain supported endpoints. The header is in the following format.\n\n```text\nsec-GitHub-allowed-enterprise: ENTERPRISE1-ID, ENTERPRISE2-ID, ENTERPRISE3-ID ... ENTERPRISE20-ID.\n```\n\nEnterprise owners can find the correct enterprise ID to use in the header for each of the enterprises. See [Finding the header](#finding-the-header).\n\n> \\[!NOTE] We currently support up to 20 unique enterprise IDs to be included in the header.\n\n### Lifting the restriction for certain users\n\nYou may want to lift the restriction for certain users who need to contribute to open source resources using a personal account, or who may need to create support tickets in case of issues. To handle this, you must configure your network to inject the header only for users that you intend to restrict.\n\nOptions include:\n\n* **Network segregation**: Create a \"work\" network that injects the header, and an \"open source\" network that does not. Limit access to the \"open source\" network to users who need it.\n* **Device grouping**: If your proxy or firewall is authenticated, you can collect a group of users who don't need the header, and selectively exclude them from injection.\n\n## Unsupported features\n\nBecause this restriction only applies to requests that are sent via a proxy that adds an enterprise header, certain GitHub features do not support the restriction to block users from accessing or using their personal accounts. To block users on your network from accessing these features, you will need to make the changes described below.\n\n| Feature | Associated endpoint | Notes |\n| --------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| GitHub Pages | `github.io` | This is generally user-generated content that cannot accept data. You may not want to restrict access. |\n| GitHub Codespaces | `github.dev` | To restrict access, block the endpoint entirely. |\n| SSH access | Port 22 on GitHub.com | To restrict access, block the endpoint entirely. |\n| SSH over HTTPS | `ssh.github.com` | To restrict access, block the endpoint entirely. |\n| GitHub-hosted runners | Various | To enforce specific routing, use Azure private networking. See [About Azure private networking for GitHub-hosted runners in your enterprise](/en/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise). |\n| Self-hosted runners | Various | To enforce specific routing, utilize a proxy server. See [Using proxy servers with a runner](/en/enterprise-cloud@latest/actions/how-tos/manage-runners/self-hosted-runners/use-proxy-servers). |\n\n### Endpoints that don't require restriction\n\nThe following endpoints do not support or require the restriction because they only provide data, and do not accept it.\n\n* `*.githubusercontent.com`\n* `*.githubassets.com`\n* Websocket traffic on GitHub.com\n\n## How does the restriction work?\n\nFor traffic that includes the enterprise header, when a user attempts to access GitHub.com via the web, Git, or API using a user account (or a token associated with a user account) that is not a member of the enterprise:\n\n* The user will see an error message with a `403` status code. See [Errors displayed to blocked users](#errors-displayed-to-blocked-users).\n* A `business.proxy_security_header_unsatisfied` event will be logged in the enterprise audit logs. These log events will have no `actor` field due to privacy reasons, but will have an `actor_ip` field if enabled (see [Displaying IP addresses in the audit log for your enterprise](/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise)). To investigate these events further, you can review the proxy logs in your environment.\n\nThe following sections provide details for the expected behavior that applies to your users' web activity and API requests.\n\n### Web activity\n\nFor activity in the GitHub.com user interface, the header restricts which accounts a user can sign in to.\n\nWhile on your network, a user:\n\n* **Can** sign in to a managed user account in your enterprise.\n* **Cannot** sign in to an account outside your enterprise.\n* **Cannot** use the account switcher to switch to an account outside your enterprise.\n\nIf a user is already signed in to an account outside your enterprise (for example, they signed in while outside your network), when the user brings their device into your network, they will receive an error and be unable to access GitHub.com until they sign in with their enterprise-owned account.\n\n### Git activity\n\nIf your proxy is configured to inject the header into HTTP(S) requests, users on your network will be blocked from authenticating to GitHub.com over HTTP(S), unless they are a member of your enterprise. Public read requests are not blocked for unauthenticated anonymous users.\n\nYou cannot use the enterprise header to restrict Git activity over SSH. Instead, you can choose to block the port for SSH requests entirely. See [Unsupported features](#unsupported-features).\n\n### API requests\n\nFor REST and GraphQL API traffic to api.github.com, including requests via the GitHub CLI, the header restricts the use of access tokens while users are connected to your network.\n\n| Scenario | Outcome | Affected token types |\n| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------ |\n| A user uses a personal access token associated with an account owned by your enterprise. | The personal access token works as expected in API requests. | `ghp_` and `github_pat_` |\n| While connected to your network, a user tries to use a personal access token associated with a user outside your enterprise. | Requests using the token are blocked. | `ghp_` and `github_pat_` |\n| While outside your network, using an account outside your enterprise, a user signs in to an OAuth app that runs on their device. The user then brings their device inside your network. | OAuth tokens from the app stop working. | `gho_` |\n| While outside your network, using an account outside your enterprise, a user signs in to a GitHub App that runs on their device. The user then brings their device inside your network. | Tokens from the app stop working. | `ghu_` |\n| While connected to your network, an application attempts to refresh a session for a user outside your enterprise using a GitHub App refresh token. | The refresh fails. | `ghr_` |\n| While connected to your network, an application attempts to get an installation token (a token without a user identity, just the app's identity) for an organization outside your enterprise. | The token will not work. | `ghs_` |\n\n## Errors displayed to blocked users\n\nErrors will be displayed to users when the restriction is working as intended. Errors occur in the following situations:\n\n* **Web activity**: When a user is blocked from signing in or using an existing stale session.\n* **API activity**: When a user tries to use a token that is associated with a user outside the enterprise.\n* **Installation token:** When an application attempts to use an installation token to access an organization or user account outside the enterprise. For installations, only write requests are blocked. Read requests are not blocked to resources outside of the enterprise. To learn more about installation tokens, see [Authenticating as a GitHub App installation](/en/enterprise-cloud@latest/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation).\n\n| Scenario | Error code | Message |\n| ------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Web activity | 403 | Your network administrator has blocked access to GitHub except for the `ENTERPRISE` Enterprise. Please sign in with your `_SHORTCODE` account to access GitHub. |\n| API activity | 403 | Your network administrator has blocked access to GitHub except for the `ENTERPRISE` Enterprise. Please use a token for a user from the `_SHORTCODE` enterprise to access GitHub. |\n| Installation token | 403 | Your network administrator has blocked access to GitHub except for the `ENTERPRISE` Enterprise. Only tokens for the \"`SHORTCODE`\" enterprise can access GitHub. |\n\nErrors with a `400` code indicate an error in your configuration. See [Troubleshooting](#troubleshooting).\n\n## Example of testing locally\n\nYou can test your network configuration locally using a web debugging tool. This section provides an example using [Fiddler](https://www.telerik.com/fiddler). Note that Fiddler and other external debugging tools are **not** in the scope of GitHub Support.\n\nIn the following example, you will add some FiddlerScript to run on every request.\n\n1. Install [Fiddler](https://www.telerik.com/fiddler).\n\n2. Configure Fiddler to decrypt HTTPS traffic. See the [Fiddler documentation](https://docs.telerik.com/fiddler/configure-fiddler/tasks/decrypthttps).\n\n3. In Fiddler, navigate to the \"FiddlerScript\" tab, and add the following code to the `OnBeforeRequest` function. Set the `enterpriseId` variable to your own enterprise ID.\n\n ```javascript copy\n // Your enterprise id\n var enterpriseId: String = \"YOUR-ID\";\n\n //Inject on the web UI\n if (oSession.HostnameIs(\"github.com\")){\n oSession.oRequest.headers.Add(\"sec-GitHub-allowed-enterprise\",enterpriseId)\n oSession[\"ui-color\"] = \"green\";\n }\n\n // Inject on API calls\n if (oSession.HostnameIs(\"api.github.com\")){\n oSession.oRequest.headers.Add(\"sec-GitHub-allowed-enterprise\",enterpriseId)\n oSession[\"ui-color\"] = \"blue\";\n }\n\n // Inject on Copilot API calls\n if (oSession.HostnameIs(\"githubcopilot.com\")){\n oSession.oRequest.headers.Add(\"sec-GitHub-allowed-enterprise\",enterpriseId)\n oSession[\"ui-color\"] = \"yellow\";\n }\n ```\n\n4. Click **Save script**.\n\nThe header will now be injected for each of the specified domains while packet capture is active. To enable or disable injection, you can toggle packet capture by clicking **File** > **Capture Traffic**.\n\nYou can turn this injection on and off to simulate signing in with a disallowed account and then entering the network, or trying to sign in to a disallowed account while on the network.\n\n## Troubleshooting\n\nIf your header injection isn't working as expected, you will see errors with a `400` code when you try to use affected endpoints. These are distinct from the `403` errors displayed when the feature is working as expected (see [Errors displayed to blocked users](#errors-displayed-to-blocked-users)).\n\nGenerally, `400` errors occur in the following situations.\n\n* The header uses an invalid slug or enterprise ID.\n* The header lists more than one enterprise.\n* The request contains multiple `sec-GitHub-allowed-enterprise` headers.\n\n| Scenario | Error code | Message |\n| ------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Invalid slug or ID | 400 | The enterprise named in the `sec-GitHub-allowed-enterprise` header cannot be found. Ensure that the \"enterprise slug\" is entered correctly in the firewall or proxy settings. Contact your network administrator if this error persists. |\n| More than one enterprise | 400 | Only one enterprise can be used with the `sec-GitHub-allowed-enterprise` header. Ensure that only a single enterprise and header is provided. If this issue persists, contact your network administrator |\n| Multiple headers | 400 | More than one `sec-GitHub-allowed-enterprise` was received. This header must be overwritten by the firewall or proxy, to ensure that only a single enterprise is granted access. If this issue persists, contact your network administrator. |\n\n## Further reading\n\n* [Managing GitHub Copilot access to your organization's network](/en/enterprise-cloud@latest/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-github-copilot-access-to-your-organizations-network#configuring-copilot-subscription-based-network-routing-for-your-organization)"}