Merge pull request #25824 from awanlin/docs/auth-getting-started-updates
Updated Auth Getting started Guide
This commit is contained in:
Fredrik Adelöw
@@ -1,50 +1,54 @@
|
||||
---
|
||||
id: authentication
|
||||
title: Authentication
|
||||
description: How to set up authentication into your Backstage installation
|
||||
description: How to setup authentication for your Backstage app
|
||||
---
|
||||
|
||||
Audience: Admins or Developers
|
||||
|
||||
### Setting up authentication
|
||||
## Summary
|
||||
|
||||
There are multiple authentication providers available for you to use with
|
||||
Backstage, feel free to follow
|
||||
[the instructions for adding authentication](../../auth/index.md).
|
||||
We'll be walking you through how to setup authentication for your Backstage app using Github. After finishing this guide, you'll have both working authentication and users in your Backstage app to match to the users logging in!
|
||||
|
||||
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).
|
||||
There are multiple authentication providers available for you to use with Backstage, feel free to follow [their instructions for adding authentication](../../auth/index.md).
|
||||
|
||||
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`.
|
||||
:::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.
|
||||
|
||||
:::
|
||||
|
||||
## Setting up authentication
|
||||
|
||||
For this tutorial we choose to use GitHub, a free service most of you might be familiar with, and we'll be using an OAuth app. For detailed options, see
|
||||
[the GitHub 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`.
|
||||
|
||||
|
||||
|
||||
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 them as `clientId` and `clientSecret` in 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
|
||||
/* highlight-add-end */
|
||||
```
|
||||
|
||||
### Add sign-in option to the frontend
|
||||
## 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.
|
||||
The next step is to change the sign-in page. For this, you'll actually need to write some code.
|
||||
|
||||
Open `packages/app/src/App.tsx` and below the last `import` line, add:
|
||||
|
||||
@@ -71,13 +75,52 @@ components: {
|
||||
},
|
||||
```
|
||||
|
||||
:::note Note
|
||||
## Add sign-in resolver(s)
|
||||
|
||||
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.
|
||||
Next we need to add the sign-in resolver to our configuration. Here's how:
|
||||
|
||||
:::
|
||||
```yaml title="app-config.yaml"
|
||||
auth:
|
||||
# see https://backstage.io/docs/auth/ to learn about auth providers
|
||||
environment: development
|
||||
providers:
|
||||
# See https://backstage.io/docs/auth/guest/provider
|
||||
guest: {}
|
||||
github:
|
||||
development:
|
||||
clientId: YOUR CLIENT ID
|
||||
clientSecret: YOUR CLIENT SECRET
|
||||
/* highlight-add-start */
|
||||
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 */
|
||||
```
|
||||
|
||||
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!
|
||||
What this will do is take the user details provided by the auth provider and match that against a User in the Catalog. In this case - `usernameMatchingUserEntityName` - will match the GitHub user name with the `metadata.name` value of a User in the Catalog, if none is found you will get an "Failed to sign-in, unable to resolve user identity" message. We'll cover this in the next few sections.
|
||||
|
||||
Learn more about this topic in the [Sign-in Resolvers](../../auth/identity-resolver.md#sign-in-resolvers) documentation.
|
||||
|
||||
## Add the auth provider to the backend
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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 `Ctrl+C`, and starting it with `yarn dev`. You should be welcomed by a login prompt! 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.
|
||||
|
||||
:::note Note
|
||||
|
||||
@@ -85,33 +128,46 @@ Sometimes the frontend starts before the backend resulting in errors on the sign
|
||||
|
||||
:::
|
||||
|
||||
## Adding a User
|
||||
|
||||
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. First 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 once more, by stopping it with `Ctrl+C`, and starting it with `yarn dev`. You should now be able to log into Backstage and see items in your Catalog.
|
||||
|
||||
To learn more about Authentication in Backstage, here are some docs you
|
||||
could read:
|
||||
|
||||
- [Authentication in Backstage](../../auth/index.md)
|
||||
- [Using organizational data from GitHub](../../integrations/github/org.md)
|
||||
|
||||
### Setting up a GitHub Integration
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
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. More details on this file can be found in the [Static Configuration documentation](../../conf/index.md).
|
||||
|
||||
In your `app-config.local.yaml` go ahead and add the following:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user