Restricting access to GitHub.com using a corporate proxy

If 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.

To 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.

This feature requires an external firewall or proxy. Soporte de GitHub cannot assist with setup or troubleshooting for external tools such as these. For more about scope of support, see Acerca del Soporte de GitHub.

Requesting access

This feature is not enabled by default, and is currently only available to enterprises that pay by invoice.

• If you pay by invoice, to request access, contact your account manager in GitHub's Sales team.
• If you pay via credit card or PayPal, this feature is currently unavailable.

Prerequisites

• You must use an empresa con usuarios administrados on GitHub.com.
  • You'll know you're using an empresa con usuarios administrados if all your users' usernames are appended with your enterprise's shortcode.
  • If you use Nube de GitHub Enterprise con residencia de datos, your enterprise resides on a dedicated subdomain of GHE.com, so the header is not required to differentiate traffic to your enterprise's resources.
• To enforce the restriction, all traffic must flow through a proxy or firewall. The proxy or firewall must:
  • Be capable of intercepting and editing traffic, commonly called a "break and inspect" proxy
  • Support arbitrary header injection
• Your account team at GitHub must have granted you access to this feature.

Finding the header

To enforce the restriction, you will inject a header into all traffic going to certain supported endpoints. The header is in the following format.

sec-GitHub-allowed-enterprise: ENTERPRISE-ID

An enterprise owner can identify the correct enterprise ID to use in the header for your enterprise.

1. En la esquina superior derecha de GitHub, haz clic en tu foto de perfil y, a continuación, en Your enterprise.
2. En el lado izquierdo de la página, en la barra lateral de la cuenta de empresa, haz clic en Configuración.
3. Under Settings, click Authentication security.
4. In the "Enterprise access restrictions" section, find the header for your enterprise. This section is only visible for enterprises with the feature enabled.

Using the header

For best results, configure your proxy to inject the header into all traffic to the following supported endpoints.

Endpoint	Purpose
github.com/*	Web traffic to GitHub.com
api.github.com/*	REST and GraphQL API requests
*.githubcopilot.com	Traffic required for certain GitHub Copilot features

This 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 Restricción del tráfico de red a la empresa con una lista de direcciones IP permitidas.

Lifting the restriction for certain users

You 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.

Options include:

• 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.
• 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.

Unsupported features

Because 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.

Feature	Associated endpoint	Notes
GitHub Pages	github.io	This is generally user-generated content that cannot accept data. You may not want to restrict access.
GitHub Codespaces	github.dev	To restrict access, block the endpoint entirely.
SSH access	Port 22 on GitHub.com	To restrict access, block the endpoint entirely.
GitHub-hosted runners	Various	To enforce specific routing, use Azure private networking. See Acerca de las redes privadas de Azure para ejecutores hospedados en GitHub en su empresa.

Endpoints that don't require restriction

The following endpoints do not support or require the restriction because they only provide data, and do not accept it.

• *.githubusercontent.com
• *.githubassets.com
• Websocket traffic on GitHub.com

How does the restriction work?

For 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:

• The user will see an error message with a 403 status code. See Errors displayed to blocked users.
• 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 Presentación de direcciones IP en el registro de auditoría de la empresa). To investigate these events further, you can review the proxy logs in your environment.

The following sections provide details for the expected behavior that applies to your users' web activity and API requests.

Web activity

For activity in the GitHub.com user interface, the header restricts which accounts a user can sign in to.

While on your network, a user:

• Can sign in to a cuenta de usuario administrada in your enterprise.
• Cannot sign in to an account outside your enterprise.
• Cannot use the account switcher to switch to an account outside your enterprise.

If 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.

Git activity

If 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.

You 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.

API requests

For 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.

Scenario	Outcome	Affected token types
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_
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_
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_
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_
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_
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_

Errors displayed to blocked users

Errors will be displayed to users when the restriction is working as intended. Errors occur in the following situations:

• Web activity: When a user is blocked from signing in or using an existing stale session.
• API activity: When a user tries to use a token that is associated with a user outside the enterprise.
• 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 Autenticación como una instalación de una aplicación de GitHub.

Scenario	Error code	Message
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.
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.
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.

Errors with a 400 code indicate an error in your configuration. See Troubleshooting.

Example of testing locally

You can test your network configuration locally using a web debugging tool. This section provides an example using Fiddler. Note that Fiddler and other external debugging tools are not in the scope of Soporte de GitHub.

In the following example, you will add some FiddlerScript to run on every request.

1. Install Fiddler.

2. Configure Fiddler to decrypt HTTPS traffic. See the Fiddler documentation.

3. 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.

   JavaScript

   // Your enterprise id
   var enterpriseId: String = "YOUR-ID";
   
    //Inject on the web UI
    if (oSession.HostnameIs("github.com")){
        oSession.oRequest.headers.Add("sec-GitHub-allowed-enterprise",enterpriseId)
        oSession["ui-color"] = "green";
    }
   
    // Inject on API calls
    if (oSession.HostnameIs("api.github.com")){
        oSession.oRequest.headers.Add("sec-GitHub-allowed-enterprise",enterpriseId)
        oSession["ui-color"] = "blue";
        }
   
    // Inject on Copilot API calls
    if (oSession.HostnameIs("githubcopilot.com")){
        oSession.oRequest.headers.Add("sec-GitHub-allowed-enterprise",enterpriseId)
        oSession["ui-color"] = "yellow";
    }
   

4. Click Save script.

The 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.

You 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.

Troubleshooting

If 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).

Generally, 400 errors occur in the following situations.

• The header uses an invalid slug or enterprise ID.
• The header lists more than one enterprise.
• The request contains multiple sec-GitHub-allowed-enterprise headers.

Scenario	Error code	Message
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.
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
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.

Further reading

• Administración del acceso a GitHub Copilot en la red de la organización