Log in

Standing Up Backstage

40 MINS

Setting up authentication

There are multiple authentication providers available for you to use with Backstage. For this tutorial we choose to use GitHub, a free service most of you might be familiar with, and even have an account on.

Add a new app to GitHub

Go to https://github.com/settings/applications/new to create your OAuth App.

  • Homepage URL should point to Backstage's frontend, in our tutorial it would be http://localhost:3000
  • Authorization callback URL should point to the auth backend, http://localhost:7007/api/auth/github/handler/frame
Creating OAuth App on GitHub

Generate a new Client Secret and take a note of the Client ID and the Client Secret.

Add the credentials to the configuration

Open app-config.local.yaml we've created earlier. Below the PostgreSQL configuration, add the below configuration and replace the values with the Client ID and the Client Secret from GitHub.

<span class="line"><span style="color:#85E89D">auth</span><span style="color:#E1E4E8">:</span></span>
<span class="line"><span style="color:#6A737D">  # see https://backstage.io/docs/auth/ to learn about auth providers</span></span>
<span class="line"><span style="color:#85E89D">  environment</span><span style="color:#E1E4E8">: </span><span style="color:#9ECBFF">development</span></span>
<span class="line"><span style="color:#85E89D">  providers</span><span style="color:#E1E4E8">:</span></span>
<span class="line"><span style="color:#85E89D">    github</span><span style="color:#E1E4E8">:</span></span>
<span class="line"><span style="color:#85E89D">      development</span><span style="color:#E1E4E8">:</span></span>
<span class="line"><span style="color:#85E89D">        clientId</span><span style="color:#E1E4E8">: </span><span style="color:#9ECBFF">YOUR CLIENT ID</span></span>
<span class="line"><span style="color:#85E89D">        clientSecret</span><span style="color:#E1E4E8">: </span><span style="color:#9ECBFF">YOUR CLIENT SECRET</span></span>
<span class="line"></span>

Backstage will re-read the configuration. If there's no errors, that's great! We can continue with the last part of the configuration.

Add sign-in option to the frontend

This step is needed to change the sign-in page. Get ready to dive into the code.

  1. Open packages/app/src/App.tsx in your favorite code editor. Below the last import line, add:
<span class="line"><span style="color:#F97583">import</span><span style="color:#E1E4E8"> { githubAuthApiRef } </span><span style="color:#F97583">from</span><span style="color:#9ECBFF"> '@backstage/core-plugin-api'</span><span style="color:#E1E4E8">;</span></span>
<span class="line"><span style="color:#F97583">import</span><span style="color:#E1E4E8"> { SignInProviderConfig, SignInPage } </span><span style="color:#F97583">from</span><span style="color:#9ECBFF"> '@backstage/core-components'</span><span style="color:#E1E4E8">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:#F97583">const</span><span style="color:#79B8FF"> githubProvider</span><span style="color:#F97583">:</span><span style="color:#B392F0"> SignInProviderConfig</span><span style="color:#F97583"> =</span><span style="color:#E1E4E8"> {</span></span>
<span class="line"><span style="color:#E1E4E8">  id: </span><span style="color:#9ECBFF">'github-auth-provider'</span><span style="color:#E1E4E8">,</span></span>
<span class="line"><span style="color:#E1E4E8">  title: </span><span style="color:#9ECBFF">'GitHub'</span><span style="color:#E1E4E8">,</span></span>
<span class="line"><span style="color:#E1E4E8">  message: </span><span style="color:#9ECBFF">'Sign in using GitHub'</span><span style="color:#E1E4E8">,</span></span>
<span class="line"><span style="color:#E1E4E8">  apiRef: githubAuthApiRef,</span></span>
<span class="line"><span style="color:#E1E4E8">};</span></span>
<span class="line"></span>
  1. Search for const app = createApp({ in this file, and below apis, add:
<span class="line"><span style="color:#B392F0">components</span><span style="color:#E1E4E8">: {</span></span>
<span class="line"><span style="color:#B392F0">   SignInPage</span><span style="color:#E1E4E8">: </span><span style="color:#FFAB70">props</span><span style="color:#F97583"> =></span><span style="color:#E1E4E8"> (</span></span>
<span class="line"><span style="color:#F97583">     &#x3C;</span><span style="color:#FFAB70">SignInPage</span></span>
<span class="line"><span style="color:#E1E4E8">       {</span><span style="color:#F97583">...</span><span style="color:#FFAB70">props</span><span style="color:#E1E4E8">}</span></span>
<span class="line"><span style="color:#FFAB70">       auto</span></span>
<span class="line"><span style="color:#E1E4E8">       provider</span><span style="color:#F97583">=</span><span style="color:#E1E4E8">{githubProvider}</span></span>
<span class="line"><span style="color:#F97583">     /></span></span>
<span class="line"><span style="color:#E1E4E8">   ),</span></span>
<span class="line"><span style="color:#E1E4E8"> },</span></span>
<span class="line"></span>

Note: The default Backstage app comes with a guest Sign In Resolver. This resolver makes all users share a single "guest" identity and is only intended as a minimum requirement to quickly get up and running. You can read more about how Sign In Resolvers play a role in creating a Backstage User Identity for logged in users.

Restart Backstage from the terminal, by stopping it with Control-C, and starting it with yarn dev . You should be welcomed by a login prompt.

Note: Sometimes the frontend starts before the backend resulting in errors on the sign in page. Wait for the backend to start and then reload Backstage to proceed.

Standing Up Backstage | Spotify for Backstage