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

# Enable GitHub OAuth

> Set up GitHub OAuth credentials and configure allowed organizations so your team can sign in to Rootprint using their GitHub accounts.

Rootprint supports GitHub OAuth as an additional sign-in method alongside the default username and password login. Once configured, a "Sign in with GitHub" button appears on the sign-in page. Users who are active members of one of your allowed organizations are automatically provisioned with the `user` role. If a GitHub account's email matches an existing Rootprint account, the two are linked automatically.

## Setup

<Steps>
  <Step title="Register an OAuth App on GitHub">
    Go to GitHub's [Developer settings → OAuth Apps](https://github.com/settings/developers) and click **New OAuth App**. You can register the app under your personal account or, for shared ownership, under one of your organizations (**Organization settings → Developer settings → OAuth Apps**).

    Fill in:

    * **Application name:** any name you like (e.g. `Rootprint`)
    * **Homepage URL:** the public URL of your Rootprint instance
    * **Authorization callback URL:** `https://your-rootprint-url/api/auth/callback/github`

    Replace `your-rootprint-url` with the public URL of your Rootprint instance. After creating the app, copy the **Client ID** and generate a new **Client Secret**. You will need them in the next step.
  </Step>

  <Step title="Enter credentials in Rootprint">
    In Rootprint, go to **Settings → Authentication**, then click **Configure** on the **GitHub** row. Enter:

    * **Client ID**: from your GitHub OAuth App
    * **Client Secret**: from your GitHub OAuth App
    * **Allowed organizations**: one or more GitHub organization logins whose members are permitted to sign in (e.g. `my-company`)

    <Note>
      Only active members of an allowed organization can sign in with GitHub. Add the
      organization's login (the slug from `github.com/<org>`), not its display name. You can add
      multiple organizations if needed.
    </Note>

    You can also verify the **Callback URL** shown in this section matches the authorization callback URL you registered on GitHub.
  </Step>

  <Step title="Save the configuration">
    Click **Save**. The change takes effect immediately. Rootprint reloads its auth
    configuration in place, so no restart is required. The "Sign in with GitHub" button
    appears on the sign-in page right away.

    <Note>
      GitHub auth configuration changes (saving credentials, updating allowed organizations, and
      removing GitHub auth) all apply live. Allowed organizations are evaluated at sign-in time, so
      editing them takes effect on the next GitHub sign-in attempt.
    </Note>
  </Step>
</Steps>

## How organization membership is checked

Rootprint requests the `read:org` and `user:email` scopes when a user signs in with GitHub. At sign-in time it queries GitHub for the user's membership in each allowed organization and grants access only if the user is an **active** member of at least one of them.

<Warning>
  If an organization has **OAuth App access restrictions** enabled, your OAuth App must be approved
  by an organization owner before membership checks succeed for that org. Until it is approved,
  members of that organization will be denied sign-in. You can approve the app from the
  organization's **Settings → Third-party Access → OAuth App policy**.
</Warning>

## Removing GitHub auth

To disable GitHub sign-in, open **Settings → Authentication**, click **Configure** (or **Edit**) on
the **GitHub** row, and click **Remove**. The change applies immediately and the GitHub sign-in
button disappears from the sign-in page. No restart required.

<Warning>
  Rootprint tracks whether each user has a password set. Users who signed in exclusively via GitHub
  never had one, so **Reset password** and self-serve password change are disabled for them. To give
  a GitHub-only user password access after disabling GitHub auth, delete the user from
  **Settings → Users** and invite them again. The new invite link prompts them to set a
  password.
</Warning>