Skip to content

Integrate Faction with GitHub Authentication

Faction can use GitHub as a Single Sign-On provider. Unlike OIDC providers, GitHub uses plain OAuth2 (there is no discovery document or ID token), so it is configured separately from the OAuth2.0/OIDC section using a dedicated GitHub Configuration in the Faction admin.

Because GitHub does not expose a user's email in the OAuth profile, Faction automatically requests the user:email scope and retrieves the user's verified primary email from the GitHub API. That email is matched against an existing Faction user, so every GitHub user who logs in must already exist in Faction with a matching, verified email.

Create a GitHub OAuth App

  1. Log in to GitHub and go to Settings → Developer settings → OAuth Apps (for an organization, use the organization's Settings → Developer settings → OAuth Apps).

    Create an OAuth App, not a GitHub App — Faction uses the OAuth2 web flow.

  2. Click New OAuth App.

  3. Fill in the application details:
    • Application name: something specific like Faction SSO.
    • Homepage URL: the URL of your Faction instance, e.g. https://furry-hyena-1111.factionsecurity.com
    • Authorization callback URL: your Faction URL with /github/callback appended: 
      https://furry-hyena-1111.factionsecurity.com/github/callback

      Faction automatically appends ?client_name=githubClient to the callback at login time. GitHub allows the extra query parameter, so you only need to register the base /github/callback URL above.

  4. Click Register application.
  5. Take note of the Client ID.
  6. Click Generate a new client secret and take note of the Client Secret (it is only shown once). These will be used in the Configure Faction section below.

Configure Faction

  1. Log into Faction as an admin user.
  2. Navigate to Admin → Users.
  3. In the GitHub Configuration section, enter the Client Id and Client Secret you noted above.
  4. Click Save.

Once saved, a Sign in with GitHub button appears on the Faction login screen.

Adding a GitHub User

  1. Under Admin → Users, click Add User.
  2. Set the Username to the part of the user's email address before the @ symbol. If the email is test.user@yourcompany.com then the username is test.user.
  3. ⭐️ Leave the Password Field Blank. ⭐️
  4. Enter the First and Last name.
  5. Enter the email address. It must match the user's verified email in GitHub (the address GitHub returns from /user/emails).
  6. Click Save Changes.

If a user's GitHub email is private, Faction still retrieves it through the user:email scope as long as it is a verified email on their GitHub account. Unverified emails are ignored.

Login with GitHub

From the Faction login screen, click Sign in with GitHub. Faction redirects the user to GitHub to authorize, then signs them in by matching their verified GitHub email to their Faction user.

Custom SignOn URLS

You can send users straight to the GitHub login flow by linking to the URL below. This skips the Faction login form entirely.

https://YOURHOST/sso/github