Using GitHub Auth with Backstage
By David Tuite • August 5th, 2020 — last validated on September 14th, 2021Update 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:
- Create an OAuth application on GitHub,
- 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.