Skip to main content

GitHub OAuth

Creating a custom GitHub OAuth application​

  1. Follow GitHub's documentation 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. A working example registration:
  4. Save the client ID and client secret from the application overview:
  5. Return to the ngrok dashboard and create or edit an OAuth endpoint configuration module.
  6. Choose to use your own application with GitHub as the provider.
  7. Include the client ID and secret from earlier.
  8. Add any scopes your application requires.
    • Include the read:user scope (or more permissive, like user) for ngrok.
  9. Add any team or organization constraints by the their mention handle(s), excluding the @ prefix.
    • For example, the ngrok organization's mention handle is @ngrok, so the organization constraint would be ngrok. Similarly, the @ngrok/developers team would be matched by the constraint ngrok/developers.
    • If a constraint is specified, the read:org scope is required. A more permissive scope, such as org, also works.
    • Organizations must allow third-party access to your app.

Additional GitHub headers provided by ngrok​

In addition to the headers set for every OAuth provider, these additional headers are available when using GitHub.

ngrok-auth-github-user-id

The username of the authorized user.

ngrok-auth-github-organization

Only when a team or organization constraint matches: the first matching GitHub organization's mention handle (e.g "coreutils").

ngrok-auth-github-team

Only when a team constraint matches: the first matching GitHub team mention handle (e.g "coreutils/contributors").

Using Organization and Teams​

To authorize users based on organization or team membership, the organization must allow third party access. There are multiple ways to grant access:

  • Organizations may allow unrestricted third-party access from settings.
  • Owners can grant access to an application during authorization.
  • Members can request access as part of authorization.
  • Members can request access from settings.

The ngrok managed application can authorize users based on organization or team. For organizations concerned about membership privacy, your own application should always be used. When granting third-party access to the managed application, anyone using the managed application may constrain based on your organization's membership.

Header presence and constraint ordering​

Organization and team headers are present only when an organization or team constraint matches. For example, an endpoint constrained solely on the ngrok organization will always have authorized users with the ngrok organization header. An endpoint without any organization or team constraints will receive no organization or team header.

ngrok authorizes against users' first 200 memberships of each constraint in chronological order of the team or organization's creation. Headers are filled from the first user data match in order:

  1. From any team membership, check the parent organization.
  2. Check team membership.
  3. Check organization membership.

Known Limitations​