From 8c8a62dc0689b1d29fd8d5ea2b721b84b9dee55c Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Mon, 29 Jul 2024 15:38:20 -0500 Subject: [PATCH] Updated Auth Getting started Guide Signed-off-by: Andre Wanlin --- docs/getting-started/config/authentication.md | 101 ++++++++++++------ 1 file changed, 67 insertions(+), 34 deletions(-) diff --git a/docs/getting-started/config/authentication.md b/docs/getting-started/config/authentication.md index e97ed3d89c..72990539ca 100644 --- a/docs/getting-started/config/authentication.md +++ b/docs/getting-started/config/authentication.md @@ -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: