Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Let readers sign in with GitHub

Readers can sign in with their GitHub account, matched to a registered reader by a verified email address. The web editor's GitHub App provides the credentials.

Before you begin

A GitHub App (or an OAuth App) with the docs site's callback URL. One GitHub App can serve the docs site, the web editor and the build webhook; see One GitHub App for the site, the editor and builds.

  1. Add $PUBLIC_URL/auth/github/callback to the App's callback URLs.

    A GitHub App takes up to ten callback URLs, so the editor's $EDITOR_PUBLIC_URL/auth/github/callback stays next to it. For a GitHub App, give it the account permission Email addresses: Read-only.

  2. Set GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_CLIENT_SECRET on the web service: the same values as the editor's.
  3. Let your own team in without registering each person: set OPEND_GITHUB_COLLABORATOR_ORG to an organization slug, and OPEND_GITHUB_COLLABORATOR_STAFF=1 to make them staff.

    Then anyone with write, maintain or admin access to the docs repository becomes a reader of that organization the first time they sign in with GitHub. The server asks GitHub through the App installation, so the repository must be registered with its installationId, and GITHUB_APP_ID set. Their primary email must be verified on GitHub and not already belong to a reader. Each such reader is recorded in the audit log as reader.provision.

  4. Restart the web service and open $PUBLIC_URL/auth/login.

    The sign-in page lists Sign in with GitHub, and any other configured provider. With exactly one provider and no demo readers, it goes straight to it.

Results

  • The flow is GitHub's OAuth web flow with a random state and PKCE (S256), held in a signed, HttpOnly cookie for ten minutes. It asks for read:user user:email (OAuth Apps); a GitHub App uses its permissions instead.
  • The server reads the account's addresses from GitHub and uses only verified ones, the primary first. The first that matches a registered reader links that reader to the GitHub account, and later sign-ins match the account itself, even after its email changes. Another GitHub account with the same email cannot take the reader over.
  • GitHub sign-in and OIDC are separate links: a reader may use both.
  • Anyone else sees "No access" and is not signed in.