> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub OAuth

> Configure ngrok to authenticate users with GitHub OAuth. Register an OAuth app and set the callback URL.

This guide walks you through creating a GitHub OAuth app and configuring ngrok to use it for user authentication.

## What you'll need

* A [GitHub](https://github.com/) account with permission to create OAuth apps.
* Your ngrok authtoken and an endpoint with the OAuth action in its Traffic Policy.

## Create a GitHub OAuth application

1. Follow [GitHub's documentation for creating an OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) until the final step of submitting the registration form.
2. Set the **Authorization callback URL** to `https://idp.ngrok.com/oauth2/callback`.
3. Submit the form.
4. From the application overview, save your **Client ID** and **Client secret** for use in ngrok.

## Update your ngrok endpoint Traffic Policy

1. Access the [ngrok Dashboard Endpoints page](https://dashboard.ngrok.com/endpoints?sortBy=createdAt\&orderBy=desc) and locate an existing endpoint you'd like to add this to or create a new one.
2. In your traffic policy, add the following configuration:

<Note>
  You may add [any scopes](https://developers.facebook.com/docs/apps/review/login-permissions) that are required by your application with the following caveats.

  * Scopes which require a Facebook [app review](https://developers.facebook.com/docs/apps/review/#app-review) are unsupported.
  * ngrok will enforce that users [accept all permissions](https://developers.facebook.com/docs/facebook-login/handling-declined-permissions#reprompt) before completing authorization.
</Note>

<CodeGroup>
  ```yaml policy.yml theme={null}
  on_http_request:
    - actions:
        - type: oauth
          config:
            provider: github
            client_id: '{your app''s oauth client id}'
            client_secret: '{your app''s oauth client secret}'
            scopes:
              - read:user
              - read:org
  ```

  ```json policy.json theme={null}
  {
    "on_http_request": [
      {
        "actions": [
          {
            "type": "oauth",
            "config": {
              "provider": "github",
              "client_id": "{your app's oauth client id}",
              "client_secret": "{your app's oauth client secret}",
              "scopes": [
                "read:user",
                "read:org"
              ]
            }
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

Click **Save** to validate and update your traffic policy.

### Configure access control

Optionally, configure access control to your service by only allowing specific users or domains.

<CodeGroup>
  ```yaml policy.yml theme={null}
  on_http_request:
    - expressions:
        - '!(actions.ngrok.oauth.identity.email in [''me@example.com''])'
      actions:
        - type: deny
  ```

  ```json policy.json theme={null}
  {
    "on_http_request": [
      {
        "expressions": [
          "!(actions.ngrok.oauth.identity.email in ['me@example.com'])"
        ],
        "actions": [
          {
            "type": "deny"
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

## Known limitations

* Users who use GitHub's [private email setting](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#:~:text=If%20you%27d%20like%20to%20keep%20your%20personal,to%20Keep%20my%20email%20address%20private) are not able to sign in.