Update Sept 2021: Backstage now supports GitHub authentication via GitHub apps. If you are using a GitHub app, you do not need to follow the steps described below. They are only valid if you are using a GitHub Personal Access Token with Backstage.

GitHub is one of the most popular Backstage authentication mechanisms going. There’s a good reason for this, Backstage ultimately needs to pull service catalog information from YAML files, those YAML files usually live in git, and the git repos usually live on GitHub.

Setting up GitHub authentication can be a little tricky, but this post will tell you everything you need to know.

There are basically two steps:

1. Create an OAuth application on GitHub,
2. Pass the identity information from this application to Backstage.

Let’s get into it.

Create an OAuth application on GitHub

To create an OAuth app for local development, visit your OAuth Apps settings page on GitHub. Click the “New OAuth App” button and you’ll see a form you have to fill out.

Enter the following values:

Application name

Backstage local development

Homepage URL

http://localhost:3000

Application description

Login to Backstage on localhost

Authorization callback URL

http://localhost:7000/api/auth/github/handler/frame

Your form should now look something like this:

The tricky thing with this, is that the homepage URL should point to the Backstage Frontend, because that’s what your users will consider to be “Backstage”, but the Authorization callback URL must point to the Backstage Backend.

When GitHub authenticates a user, it will call out to the application Backend, with some authentication parameters included in the URL query string. Backstage will check these parameters and then server-side render a confirmation page for the user.

Once you submit that form, GitHub provides you with a Client ID and Client Secret for your OAuth application.

Note these down, you’ll need them in the next step.

Tell Backstage about your OAuth application

Go back to the command line where you run the Backstage backend and pass the Client ID and Client Secret into Backstage when you start it up.

# starting in the root of your Backstage repo
» cd packages/backend
» env AUTH_GITHUB_CLIENT_ID=eafc816045b5533ba581 AUTH_GITHUB_CLIENT_SECRET=34922f6547991760e8f5219a529a9c00b0fd44ea yarn start

That’s all there is to it. When Backstage starts up and opens on http://localhost:3000, you’ll be able to login via GitHub.

Further reading

The authentication docs for Backstage can be found in the docs/auth directory, within the repo.

They are rather engineering focussed and not the easiest to follow if you’re just trying to authenticate with GitHub.