For individual providers and images of their setup, see their respective branches.
Main branch contains a unified setup for all providers mentioned above.
Modified from documentation published in https://backstage.io/docs/auth/
This document takes you through setting up a Backstage app that runs in your own environment. It starts with a skeleton install and verifying of the monorepo's functionality. Next, authentication is added and tested.
This document assumes you have Node.js 12 active along with Yarn and Python. Please note, that at the time of this writing, the current version is v0.4.5 This guide can still be used with future versions, just, verify as you go.
From the terminal:
- Create a (monorepo) application:
npx @backstage/create-app
- Enter an
id
for your new app likemybiz-backstage
I went withsimple-backstage-app
- Choose
SQLite
as your database. This is the quickest way to get started as PostgreSQL requires additional setup not covered here. - Start your backend:
yarn --cwd packages/backend start
# You should see positive verbiage in your terminal output
2020-09-11T22:20:26.712Z backstage info Listening on :7000
- Finally, start the frontend. Open a new terminal window and from the root of
your project, run:
yarn start
# You should see positive verbiage in your terminal output
ℹ 「wds」: Project is running at http://localhost:3000/
Once the app compiles, a browser window should have popped with your stand-alone
application loaded at localhost:3000
. This could take a couple minutes.
# You should see positive verbiage in your terminal output
ℹℹ 「wdm」: Compiled successfully.
Since there is no auth currently configured, you are automatically entered as a guest. Let's fix that now and add auth.
Default Backstage installation includes multiple authentication providers out of the box. The steps to enable new authentication provider in Backstage are very similar to each other, the biggest difference is usually configuring the external authentication provider. Please see a subset of possible providers and instructions to integrate them below. Steps 1 & 2 are described separately for each provider and steps beyond that are common for all.
Github
- Open
app-config.yaml
and change it as follows
from:
auth:
providers: {}
to:
auth:
providers:
github:
development:
clientId:
$env: AUTH_GITHUB_CLIENT_ID
clientSecret:
$env: AUTH_GITHUB_CLIENT_SECRET
## uncomment the following two lines if using enterprise
# enterpriseInstanceUrl:
# $env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL
- Generate Github client id and secret
- Log into http://github.com
- Navigate to (Settings > Developer Settings > OAuth Apps > New OAuth App)[https://github.com/settings/applications/new]
- Set Homepage URL = http://localhost:3000
- Set Callback URL = http://localhost:7000/api/auth/github
- Click [Register application]
- On the next page, copy and paste your new Client ID and Client Secret to
environment variables defined in the
app-config.yaml
file,AUTH_GITHUB_CLIENT_ID
&AUTH_GITHUB_CLIENT_SECRET
Gitlab
- Open
app-config.yaml
and change it as follows
from:
auth:
providers: {}
to:
auth:
providers:
gitlab:
development:
clientId:
$env: AUTH_GITLAB_CLIENT_ID
clientSecret:
$env: AUTH_GITLAB_CLIENT_SECRET
audience: https://gitlab.com # Or your self-hosted Gitlab instance URL
- Generate Gitlab Application for client id and secret
- Log into Gitlab
- Navigate to (Profile > Settings > Applications)[https://gitlab.com/-/profile/applications]
- Name your application
- Set Callback URL = http://localhost:7000/api/auth/gitlab/handler/frame
- Select the following values:
read_user (Read the authenticated user's personal information)
read_repository (Allows read-only access to the repository)
write_repository (Allows read-write access to the repository)
openid (Authenticate using OpenID Connect)
profile (Allows read-only access to the user's personal information using OpenID Connect)
email (Allows read-only access to the user's primary email address using OpenID Connect)
- Click [Save application]
- On the next page, copy and paste your new Application ID and Secret to
environment variables defined in the
app-config.yaml
file,AUTH_GITLAB_CLIENT_ID
&AUTH_GITLAB_CLIENT_SECRET
- Open
app-config.yaml
and change it as follows
from:
auth:
providers: {}
to:
auth:
providers:
google:
development:
clientId:
$env: AUTH_GOOGLE_CLIENT_ID
clientSecret:
$env: AUTH_GOOGLE_CLIENT_SECRET
- Generate Google Application in Google Cloud console
- Log into https://console.cloud.google.com
- Select or create a new project from the dropdown on the top bar
- Navigate to (APIs & Services - > Credentials)[https://console.cloud.google.com/apis/credentials]
- Add new Authorised JavaScript origin =
http://localhost:3000
- Add new Authorised redirect URI =
http://localhost:7000/api/auth/google/handler/frame
- Click [Save application]
- Google should display a modal with your Client ID and Secret. Copy and paste
those to environment variables defined in the
app-config.yaml
file,AUTH_GOOGLE_CLIENT_ID
&AUTH_GOOGLE_CLIENT_SECRET
Microsoft
- Open
app-config.yaml
and change it as follows
from:
auth:
providers: {}
to:
auth:
providers:
microsoft:
development:
clientId:
$env: AUTH_MICROSOFT_CLIENT_ID
clientSecret:
$env: AUTH_MICROSOFT_CLIENT_SECRET
tenantId:
$env: AUTH_MICROSOFT_TENANT_ID
- Create Microsoft Directory in Microsoft Portal
- Log into https://portal.azure.com
- Navigate to (Azure Active Directory -> App Registrations)[https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps]
- Create a New Registration
- Add new Redirect URI =
http://localhost:3000
- Add new Authorised redirect URI =
http://localhost:7000/api/auth/microsoft/handler/frame
- Click [Save application]
- Set environment variable
AUTH_MICROSOFT_CLIENT_ID
fromApplication (client) Id
displayed on the directory page - Set environment variable
AUTH_MICROSOFT_TENANT_ID
fromDirectory (tenant) ID
displayed on the directory page - Navigate to Certificates & Secrets section and click [Create a new secret]
- Set environment variable
AUTH_MICROSOFT_CLIENT_SECRET
from thevalue
field created.
Auth0
- Open
app-config.yaml
and change it as follows
from:
auth:
providers: {}
to:
auth:
providers:
auth0:
development:
clientId:
$env: AUTH_AUTH0_CLIENT_ID
clientSecret:
$env: AUTH_AUTH0_CLIENT_SECRET
domain:
$env: AUTH_AUTH0_DOMAIN_ID
- Create Auth0 application in Auth0 management console
- Log into https://manage.auth0.com/dashboard/
- Navigate to Applications
- Create a New Application
- Select Single Page Web Application
- Go to Settings tab
- Add new line to Allowed Callback URLs =
http://localhost:7000/api/auth/auth0/handler/frame
- Click [Save Changes]
- Set environment variables displayed on the Basic Information page
AUTH_AUTH0_CLIENT_ID
fromClient ID
displayed on Auth0 application pageAUTH_AUTH0_CLIENT_SECRET
fromClient Secret
displayed on Auth0 application pageAUTH_AUTH0_DOMAIN_ID
fromDomain
displayed on Auth0 application page
- Set environment variables in whatever fashion is easiest for you. I chose to
add mine to my
.zshrc
profile.
# For macOS Catalina & Z Shell
# ------ simple-backstage-app GitHub
#
# (Change the name of the environment variables based on your auth setup above)
export AUTH_GITHUB_CLIENT_ID=xxx
export AUTH_GITHUB_CLIENT_SECRET=xxx
# export AUTH_GITHUB_ENTERPRISE_INSTANCE_URL=https://github.{MY_BIZ}.com
- And of course I need to source that file.
# Loading the new variables
% source ~/.zshrc
# Any other currently opened terminals need to be restarted to pick up the new values
# verify your setup by running env
% env
# should output something like
> ...
> AUTH_GITHUB_CLIENT_ID=xxx
> AUTH_GITHUB_CLIENT_SECRET=xxx
> ...
- Open and change _root > packages > app > src >
App.tsx
to use correct authentication provider reference
import { githubAuthApiRef, SignInPage } from '@backstage/core';
Modify the imported reference based on authentication method selected above
Auth Provider | Import Name |
---|---|
Github | githubAuthApiRef |
Gitlab | gitlabAuthApiRef |
googleAuthApiRef | |
Microsoft | microsoftAuthApiRef |
Auth0 | googleAuthApiRef |
- In the same file, modify createApp
Remember to modify the provider information based on the table above.
const app = createApp({
apis,
plugins: Object.values(plugins),
components: {
SignInPage: props => {
return (
<SignInPage
{...props}
providers={[
{
id: 'github-auth-provider',
title: 'GitHub',
message: 'Simple Backstage Application Login',
apiRef: githubAuthApiRef,
},
]}
align="center"
/>
);
},
},
});
After finishing setting up one (or multiple) authentication providers defined above you can start the backend and frontend as before
When the browser loads, you should be presented with a login page for GitHub. Login as usual with your GitHub account. If this is your first time, you will be asked to authorize and then are redirected to the catalog page if all is well.
For more information you can clone the repository: https://github.com/RoadieHQ/backstage-auth-example Each authentication setting is set up there on a branch named after the authentication provider.
See more documentation in Backstage documentation page in: https://backstage.io/docs/tutorials/quickstart-app-auth