Demo Authentication

In previous examples we used the built-in guest user. This guide shows how to let users sign in with GitHub by:

Registering a GitHub OAuth App.
Configuring Backstage frontend and backend to use GitHub as an auth provider.
Adding a sign-in resolver to map GitHub identities to Backstage User entities.
Reproducing and resolving the common “unable to resolve user identity” error by importing or creating matching user entities.

Prerequisites: a running Backstage app (frontend typically at http://localhost:3000, backend at http://localhost:7007 in development). Quick overview of the flow:

GitHub performs OAuth and returns an identity.
Backstage auth backend validates the OAuth flow.
The Sign-in resolver maps the identity to a Backstage User entity in the catalog.
If no matching User exists, sign-in fails with the resolver error.

You may already have some of the configuration in place. Example publish/auth snippet (use environment variables for secrets in production):

runIn: 'docker' # Alternatives - 'local'
publisher:
  type: 'local' # Alternatives - 'googleGcs' or 'awsS3'

auth:
  # see https://backstage.io/docs/auth/ to learn about auth providers
  providers:
    github:
      development:
        clientId: YOUR_GITHUB_CLIENT_ID
        clientSecret: YOUR_GITHUB_CLIENT_SECRET
  # See https://backstage.io/docs/auth/guest/provider
  guest: {}

Example catalog provider for importing organization data from GitHub:

catalog:
  providers:
    githubOrg:
      - id: github
        githubUrl: https://github.com
        orgs: ['shopping-hub']
        schedule:
          initialDelay: { seconds: 30 }
          frequency: { hours: 1 }
          timeout: { minutes: 50 }

If you want to demonstrate the resolver error, temporarily disable user-importing providers so no User entities are imported from GitHub — this reproduces the “unable to resolve user identity” case later.

1. Create a GitHub OAuth App

GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.
Application name: e.g. backstage-auth.
Homepage URL: your Backstage frontend URL, e.g. http://localhost:3000 or http://<IP_ADDRESS>:3000.
Authorization callback URL: your auth backend handler, e.g. http://localhost:7007/api/auth/github/handler/frame.

A screenshot of the GitHub Developer Settings page showing the OAuth Apps section with two registered applications named "backstage" and "test," each with an Edit button. The left sidebar also shows navigation for GitHub Apps and Personal access tokens.

After registering, GitHub provides a Client ID and allows you to generate a Client Secret. Copy both values — you will use them in Backstage configuration.

A screenshot of GitHub's "Register a new OAuth app" page showing form fields including Application name ("backstage-auth"), a Homepage URL with an IP address and port, and an Authorization callback URL. The "Register application" button is visible at the bottom.

GitHub shows the client secret only once when you create it. Copy it immediately and store it securely (for example, in environment variables or a secrets manager). Do not commit secrets to source control.

You can view the Client ID and manage Client Secrets from the OAuth app settings page. If you lose the secret, generate a new one.

2. Configure Backstage auth in app-config.yaml

Add the GitHub provider configuration to app-config.yaml. Use environment variables rather than hard-coded secrets for production. Example minimal development config with a sign-in resolver:

auth:
  # see https://backstage.io/docs/auth/ to learn about auth providers
  environment: development
  providers:
    guest: {}
    github:
      development:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
        signIn:
          resolvers:
            # Matches the GitHub username with the Backstage user entity metadata.name
            - resolver: usernameMatchingUserEntityName

Notes:

environment: development selects the credentials under github.development.
signIn.resolvers tells Backstage how to map the identity returned by GitHub to a Backstage User entity.
usernameMatchingUserEntityName attempts to match the GitHub username (login) to a User entity’s metadata.name.

Other resolvers are available (for example, email-based resolvers). See the Backstage authentication docs for the full list and pick the one that fits your user model: https://backstage.io/docs/auth/

3. Backend — register the GitHub auth backend module

Install and register the GitHub auth backend provider module so the backend can handle the OAuth flow. Install the provider module from the workspace root:

yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-github-provider

import { createBackend } from '@backstage/backend-plugin-api';
import authPlugin from '@backstage/plugin-auth-backend';
// import the provider module
import githubProviderModule from '@backstage/plugin-auth-backend-module-github-provider';

const backend = createBackend();

backend.add(authPlugin);
backend.add(githubProviderModule);

backend.start();

Important: ensure the provider id exposed by the backend matches the frontend provider id (commonly github). Backend registration details depend on your backend structure, but the provider module must be added and active. To display a GitHub sign-in button, add the GitHub provider to the SignInPage component (e.g., packages/app/src/app.tsx). Import the API ref:

import { githubAuthApiRef } from '@backstage/core-plugin-api';

Then add the provider to the SignInPage components config:

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

You can include multiple providers (for example both guest and github) so users can choose their sign-in method. Rebuild/restart the frontend after changes. Backstage uses HTTP cookies for sessions. To test first-run behavior:

Clear cookies/site data for your Backstage origin in the browser.
Reload the SignIn page.

If GitHub is misconfigured (missing environment, clientId, or clientSecret), the SignIn page may show an error like “The GitHub provider is not configured to support sign-in.”

Clearing cookies ensures you test the full OAuth flow from the beginning. This helps validate that the frontend, backend, and GitHub OAuth callback are wired correctly.

6. Common error: “unable to resolve user identity”

After GitHub consent you might see this error:

Login failed: 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.

A web app login screen titled "Scaffolded Backstage App" showing two sign-in cards for "Guest" and "Github." A red error banner at the top reports a login failure saying it can't resolve the user identity.

This means GitHub authenticated you, but Backstage could not map the returned identity to any User entity in the catalog using the configured resolver.

The sign-in resolver maps identity attributes returned by GitHub (e.g., username or email) to a Backstage User entity. If no matching user entity exists, sign-in fails with the “unable to resolve user identity” error.

Options to fix the error:

Create a User entity that matches the resolver’s expectations. Example YAML if using usernameMatchingUserEntityName:

# Example user entity in the catalog
apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: sanjeev  # must match the GitHub username if using usernameMatchingUserEntityName
spec:
  memberOf: [guests]

Import users (and optionally groups) from GitHub into the catalog by enabling a catalog.providers.githubOrg (or other GitHub provider) configuration and restarting the backend so entities are ingested automatically.

If you prefer to import users automatically, re-enable or add the appropriate catalog provider and ensure it imports User and Group descriptors (or repositories containing catalog-info.yaml that describe them).

7. Final verification

Verify each step:

OAuth app registered on GitHub with the correct callback URL.
auth.providers.github set in app-config.yaml with environment and credentials.
GitHub provider module registered on the backend.
Backstage catalog contains User entities that match your sign-in resolver (manually created or imported).

On success you will be able to sign in with GitHub and see your account in the Software Catalog (Users).

A web application dashboard titled "My Company Catalog" with a left sidebar menu and a main panel listing "All Users (3)". The user table shows three entries (guest, Jenny Doe, and Sanjeev Thiyagarajan) with search and action icons.

That completes the GitHub authentication integration for Backstage. You can adapt the same steps for other providers (Google, OAuth2, SAML) by consulting the Backstage authentication docs and selecting sign-in resolvers appropriate for your user identity model:

Backstage Authentication docs: https://backstage.io/docs/auth/
Backstage Catalog docs: https://backstage.io/docs/features/software-catalog/overview

Useful configuration summary

Item	Location / File	Purpose / Example
Auth provider config	`app-config.yaml`	Set `auth.providers.github` and `environment` with `${AUTH_GITHUB_CLIENT_ID}` and `${AUTH_GITHUB_CLIENT_SECRET}`
Backend provider module	`packages/backend`	`@backstage/plugin-auth-backend-module-github-provider` must be added and registered
Frontend sign-in	`packages/app/src/app.tsx`	Add provider to `SignInPage` using `githubAuthApiRef`
Catalog import	`app-config.yaml` (catalog.providers)	`githubOrg` or `github` provider to import `User`/`Group` entities
User entity example	`catalog-info.yaml`	`kind: User` with `metadata.name` matching GitHub username if using username resolver

Tips:

Use environment variables or a secrets manager for clientSecret.
If you see a sign-in resolver error, check the catalog contents and the resolver type you configured.
Test locally by clearing cookies and running the full sign-in flow.

Introduction

Backstage Basics

Catalog

Templates

TechDocs & Search

Customization & Plugins

Production Backstage

Demo Authentication

1. Create a GitHub OAuth App

2. Configure Backstage auth in app-config.yaml

3. Backend — register the GitHub auth backend module

6. Common error: “unable to resolve user identity”

7. Final verification

Watch Video

Practice Lab

​1. Create a GitHub OAuth App

​2. Configure Backstage auth in app-config.yaml

​3. Backend — register the GitHub auth backend module

​4. Frontend — enable GitHub on the SignIn page

​5. Clear cookies to test a fresh sign-in

​6. Common error: “unable to resolve user identity”

​7. Final verification

Watch Video

Practice Lab

1. Create a GitHub OAuth App

2. Configure Backstage auth in app-config.yaml

3. Backend — register the GitHub auth backend module

4. Frontend — enable GitHub on the SignIn page

5. Clear cookies to test a fresh sign-in

6. Common error: “unable to resolve user identity”

7. Final verification