Skip to content
downpipes docs

Sign in to downpipes with GitHub

downpipes signs people in to the console against GitHub over OAuth2. GitHub issues no ID token, so there is no signed token to verify: the engine exchanges the authorisation code over a TLS-protected token call, then reads identity from the GitHub API and keys each person on their immutable numeric user id, never the renameable login. The shared add-a-connection mechanics and the pre-save test live on Connect OIDC or OAuth2.

What you need

  • A GitHub account that can create an OAuth App, plus organisation owner rights if you want team and organisation membership for role mapping.
  • Owner access to the downpipes console, since connection management is owner-only and asks for a step-up sign-in.

Set it up

  1. Sign in to GitHub and open Settings, then Developer settings, then OAuth Apps, and choose New OAuth App. Register a classic OAuth App here, not a GitHub App.
  2. Set an Application name (for example “downpipes”) and a Homepage URL. For the Authorization callback URL, use your downpipes callback URL, which is your console origin followed by /admin/oidc/callback/<connId>, for example https://console.example.com/admin/oidc/callback/github; the console shows the exact value when you add the connection.
  3. Choose Register application and copy the Client ID, then Generate a new client secret and copy it straight away, since GitHub shows the secret only once.
  4. In the downpipes console, open the external identity providers screen (/access/idp), choose the GitHub tile and Add a connection. This is owner-only and asks for a step-up sign-in.
  5. Paste the client id and client secret, run Test connection, then Add the connection.

Group-to-role mapping

downpipes requests the read:org and user:email scopes, and read:org lets it read your team and organisation membership so those can map to roles. Map a GitHub team or organisation onto a downpipes role on Group-to-role mapping. If your organisation has OAuth App access restrictions turned on (the default for newer organisations), an owner must approve downpipes under Settings, Third-party access before membership is returned.

Good to know

  • Identity keys on the immutable user id. downpipes stores each person against their numeric GitHub id, not their login, so renaming a GitHub user never loses their access.
  • The client secret is shown once. Copy it before you leave the registration page; if you lose it, generate a new one and update the connection.
  • Register a classic OAuth App, not a GitHub App. The two are separate registrations and only the OAuth App matches this preset.
  • There is no signed token in this flow. Trust comes from the TLS-protected token exchange and identity from the authenticated GitHub API call, not from a token signature.

Last updated .