paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 19 Packages Projects Releases Wiki Activity

Updated Auth Getting started Guide

Browse Source 
Signed-off-by: Andre Wanlin <awanlin@spotify.com>
This commit is contained in:
Andre Wanlin
2024-07-29 15:38:20 -05:00
parent 7ac4599eeb
commit 8c8a62dc06
1 changed files with 67 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/config/authentication.md
+67 -34
View File
@@ -8,43 +8,48 @@ Audience: Admins or Developers
### Setting up authentication
There are multiple authentication providers available for you to use with
Backstage, feel free to follow
[the instructions for adding authentication](../../auth/index.md).
There are multiple authentication providers available for you to use with Backstage, feel free to follow [the instructions for adding authentication](../../auth/index.md).
For this tutorial we choose to use GitHub, a free service most of you might be
familiar with. For other options, see
For this tutorial we choose to use GitHub, a free service most of you might be familiar with. For other options, see
[the auth provider documentation](../../auth/github/provider.md#create-an-oauth-app-on-github).
Go to
[https://github.com/settings/applications/new](https://github.com/settings/applications/new)
to create your OAuth App. The `Homepage URL` should point to Backstage's
frontend, in our tutorial it would be `http://localhost:3000`. The
`Authorization callback URL` will point to the auth backend, which will most
likely be `http://localhost:7007/api/auth/github/handler/frame`.
Go to [https://github.com/settings/applications/new](https://github.com/settings/applications/new) to create your OAuth App. The `Homepage URL` should point to Backstage's frontend, in our tutorial it would be `http://localhost:3000`. The `Authorization callback URL` will point to the auth backend, which will most likely be `http://localhost:7007/api/auth/github/handler/frame`.
![Screenshot of the GitHub OAuth creation page](../../assets/getting-started/gh-oauth.png)
Take note of the `Client ID` and the `Client Secret`. Open `app-config.yaml`,
and add your `clientId` and `clientSecret` to this file. It should end up
looking like this:
Take note of the `Client ID` and the `Client Secret` (clicking the "Generate a new client secret" button will get this value for you). Open `app-config.yaml`, and add your `clientId` and `clientSecret` to this file. It should end up looking like this:
```yaml title="app-config.yaml"
auth:
# see https://backstage.io/docs/auth/ to learn about auth providers
/* highlight-add-start */
environment: development
/* highlight-add-end */
providers:
# See https://backstage.io/docs/auth/guest/provider
guest: {}
/* highlight-add-start */
github:
development:
clientId: YOUR CLIENT ID
clientSecret: YOUR CLIENT SECRET
signIn:
resolvers:
# Matches the GitHub username with the Backstage user entity name.
# See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers.
- resolver: usernameMatchingUserEntityName
/* highlight-add-end */
```
:::note 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](../../auth/identity-resolver.md#sign-in-resolvers) play a role in creating a [Backstage User Identity](../../auth/identity-resolver.md#backstage-user-identity) for logged in users.
:::
### Add sign-in option to the frontend
Backstage will re-read the configuration. If there's no errors, that's great! We
can continue with the last part of the configuration. The next step is needed to
change the sign-in page, this you actually need to add in the source code.
Backstage will re-read the configuration. If there's no errors, that's great! We can continue with the next part of the configuration. The next step is needed to change the sign-in page, this you actually need to add in the source code.
Open `packages/app/src/App.tsx` and below the last `import` line, add:
@@ -71,13 +76,24 @@ components: {
},
```
:::note Note
### Add the auth provider to the backend
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](../../auth/identity-resolver.md#sign-in-resolvers) play a role in creating a [Backstage User Identity](../../auth/identity-resolver.md#backstage-user-identity) for logged in users.
To add the auth provider to the backend we will first need to install the package by running this command:
:::
```bash title="from your Backstage root directory"
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-github-provider
```
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!
Then we will need to add this line:
```ts title="in packages/backend/src/index.ts"
backend.add(import('@backstage/plugin-auth-backend'));
/* highlight-add-start */
backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));
/* highlight-add-end */
```
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 Note
@@ -85,6 +101,33 @@ Sometimes the frontend starts before the backend resulting in errors on the sign
:::
If you try to login at this point you will get a "Failed to sign-in, unable to resolve user identity" message, read on as we'll fix that next.
### Adding a User
As part of the authentication process it will try to match details from the Auth Provider User Profile to User in your Catalog. This is what the `resolver` in the config we added to the `app-config.yaml` in the "[Setting up authentication](#setting-up-authentication)" section is doing.
The recommended approach for adding Users, and Groups, into your Catalog is to use one of the existing Org Entity Providers - [like this one for GitHub](https://backstage.io/docs/integrations/github/org) - or if those don't work you may need to [create one](https://backstage.io/docs/features/software-catalog/external-integrations#custom-entity-providers) that fits your Organization's needs.
For the sake of this guide we'll simply step you though adding a User to the `org.yaml` file that is included when you create a new Backstage instance. Let's do that:
1. Fist open the `/examples/org.yaml` file in your text editor of choice
2. At the bottom we'll add the following YAML:
```yaml
---
apiVersion: backstage.io/v1alpha1
kind: User
metadata:
name: YOUR GITHUB USERNAME
spec:
memberOf: [guests]
```
3. Now make sure to replace the text "YOUR GITHUB USERNAME" with your actual GitHub User name.
Let's restart Backstage from the terminal ponce more, by stopping it with `Control-C`, and starting it with `yarn dev`. You should now be able to log into Backstage and see items in you Catalog.
To learn more about Authentication in Backstage, here are some docs you
could read:
@@ -93,25 +136,15 @@ could read:
### Setting up a GitHub Integration
The GitHub integration supports loading catalog entities from GitHub or GitHub
Enterprise. Entities can be added to static catalog configuration, registered
with the catalog-import plugin, or discovered from a GitHub organization. Users
and Groups can also be loaded from an organization. While using [GitHub Apps](../../integrations/github/github-apps.md)
might be the best way to set up integrations, for this tutorial you'll use a
Personal Access Token.
The GitHub integration supports loading catalog entities from GitHub or GitHub Enterprise. Entities can be added to static catalog configuration, registered with the catalog-import plugin, or discovered from a GitHub organization. Users and Groups can also be loaded from an organization. While using [GitHub Apps](../../integrations/github/github-apps.md) might be the best way to set up integrations, for this tutorial you'll use a Personal Access Token.
Create your Personal Access Token by opening
[the GitHub token creation page](https://github.com/settings/tokens/new). Use a
name to identify this token and put it in the notes field. Choose a number of
days for expiration. If you have a hard time picking a number, we suggest to go
for 7 days, it's a lucky number.
Create your Personal Access Token by opening [the GitHub token creation page](https://github.com/settings/tokens/new). Use a name to identify this token and put it in the notes field. Choose a number of days for expiration. If you have a hard time picking a number, we suggest to go for 7 days, it's a lucky number.
![Screenshot of the GitHub Personal Access Token creation page](../../assets/getting-started/gh-pat.png)
Set the scope to your likings. For this tutorial, selecting `repo` and `workflow` is required as the scaffolding job in this guide configures a GitHub actions workflow for the newly created project.
For this tutorial, we will be writing the token to `app-config.local.yaml`. This file might not exist for you, so if it doesn't go ahead and create it alongside the `app-config.yaml` at the root of the project.
This file should also be excluded in `.gitignore`, to avoid accidental committing of this file.
For this tutorial, we will be writing the token to `app-config.local.yaml`. This file might not exist for you, so if it doesn't go ahead and create it alongside the `app-config.yaml` at the root of the project. This file should also be excluded in `.gitignore`, to avoid accidental committing of this file.
In your `app-config.local.yaml` go ahead and add the following: