Skip to main content
Enable GitHub authentication in your Backstage instance so users can sign in with their GitHub accounts and be automatically recognized. In this guide, you will:
  • Register a GitHub OAuth App.
  • Configure app-config.yaml for GitHub auth.
  • Install the GitHub auth-backend module.
  • Update the frontend SignInPage.
  • Test login and troubleshoot common issues.
  • Import GitHub users into the Backstage catalog.

​
Quick Steps Overview

StepDescription
1. Register OAuth AppCreate a GitHub OAuth App for Backstage
2. Configure app-config.yamlAdd GitHub provider under auth
3. Install Backend ModuleAdd and register @backstage/plugin-auth-backend-module-github-provider
4. Update Frontend Sign-In PageAdd GitHub button on your SignInPage
5. Test & TroubleshootVerify login flow and fix configuration errors
6. Import User EntitiesSync your GitHub org users into the catalog
7. Verify Successful LoginConfirm you can sign in as a GitHub user

​
1. Register a GitHub OAuth App

Follow the official Backstage GitHub Auth docs to set up your OAuth application.
The image shows a webpage from Backstage documentation, detailing how to set up authentication using GitHub. It includes instructions and a form for registering a new OAuth application.
Scroll to the GitHub OAuth section:
The image shows a webpage from Backstage documentation about setting up authentication using GitHub OAuth. It includes instructions and a form for registering a new OAuth application.
  1. In GitHub, go to Settings → Developer settings → OAuth Apps.
  2. Click New OAuth App.
  3. Fill in the form:
    • Application name: Backstage Auth
    • Homepage URL: http://<BACKSTAGE_HOST>:3000
    • Authorization callback URL:
      http://<BACKSTAGE_HOST>:7007/api/auth/github/handler/frame
The image shows a GitHub Developer Settings page for an application named "backstage," displaying details like the owner, client ID, and client secrets. There are options to transfer ownership, list the application in the marketplace, and manage user tokens.
  1. Register the app, copy the Client ID, and generate a Client Secret:
The image shows a GitHub page for registering a new OAuth application, with fields for application name, homepage URL, application description, and authorization callback URL. There is also an option to enable Device Flow and buttons to register the application or cancel.
The image shows a GitHub application settings page displaying a client ID and client secret management section, with options to generate a new client secret and upload an application logo.

​
2. Configure Backstage (app-config.yaml)

Enable GitHub under the auth section of your app-config.yaml: 
auth:
  environment: development         # Replace with your environment key
  providers:
    guest: {}
    github:
      development:
        clientId: YOUR_CLIENT_ID
        clientSecret: YOUR_CLIENT_SECRET
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName
Ensure that the environment value matches the top-level key under providers:. If they don’t match, the GitHub provider won’t be found.
This setup uses the usernameMatchingUserEntityName resolver to match GitHub usernames to Backstage user entities.

​
3. Install the GitHub Backend Module

Install the GitHub auth backend package: 
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-github-provider
Then register it in packages/backend/src/index.ts: 
import { createRouter } from '@backstage/plugin-auth-backend';
import githubProviderModule from '@backstage/plugin-auth-backend-module-github-provider';
import guestProviderModule from '@backstage/plugin-auth-backend-module-guest-provider';

// ...

backend.add(
  createRouter({
    // other config...
    providers: {
      github: githubProviderModule(),
      guest: guestProviderModule(),
    },
  }),
);

​
4. Update the Frontend Sign-In Page

In packages/app/src/app.tsx, import githubAuthApiRef and add a GitHub button to SignInPage: 
import { createApp } from '@backstage/app-defaults';
import { SignInPage } from '@backstage/core-components';
import { githubAuthApiRef } from '@backstage/core-plugin-api';

const app = createApp({
  components: {
    SignInPage: props => (
      <SignInPage
        {...props}
        auto
        provider={{
          id: 'github',
          title: 'GitHub',
          message: 'Sign in using GitHub',
          apiRef: githubAuthApiRef,
        }}
      />
    ),
  },
  // other app config...
});

​
5. Test and Troubleshoot

Clear your browser cookies for the Backstage domain and reload. You should see:
  • Enter as guest
  • Sign in using GitHub
If you see an error like GitHub provider is not configured to support sign-in, double-check your app-config.yaml for missing environment or providers entries.
The image shows a login page for a "Scaffolded Backstage App" with options to enter as a guest or sign in using GitHub. There's an error message indicating that the GitHub provider is not configured to support sign-in.

​
6. Import User Entities from GitHub

If you sign in and see: 
Error: failed to sign in; unable to resolve user identity;
please verify that your catalog contains the expected user entities
that would match your configured sign-in resolver.
Then enable the GitHub org provider to sync users and teams: 
catalog:
  providers:
    githubOrg:
      - id: github
        githubUrl: https://github.com
        orgs: ['shopping-hub']
        schedule:
          initialDelay:
            seconds: 30
          frequency:
            hours: 1
          timeout:
            minutes: 50
Restart Backstage, clear cookies again, and sign in. All members of shopping-hub will be imported into your catalog.
The image shows a user interface for "My Company Catalog" with a list of users, including "guest," "Jenny Doe," and another user. There are options for filtering and actions like editing or starring users.

​
7. Verify Successful GitHub Login

Once your GitHub username matches a catalog user entity, login will succeed and you’ll be signed in as that user.
The image shows a GitHub Developer Settings page for an application named "backstage-auth," displaying details like the owner, client ID, and client secrets. A dropdown menu is open on the right, showing user profile options.
Congratulations—GitHub authentication is now fully integrated into your Backstage instance!

Watch Video

Practice Lab