Modifying auth tutorial to contain different providers.

Adding a better example repo link.
2021-01-11 08:57:15 +01:00
parent ded5005799
commit c2386e9e86
1 changed files with 239 additions and 26 deletions
@@ -3,20 +3,17 @@ id: quickstart-app-auth
 title: Monorepo App Setup With Authentication
 ---

-###### September 15th 2020 - @backstage/create-app - v0.1.1-alpha.21
+###### January 8th 2021 - @backstage/create-app - v0.4.5

 <br />

 > 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, GitHub authentication is added and tested.
+> 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
-> 0.1.1-alpha.21. This guide can still be used with future versions, just,
-> verify as you go. If you run into issues, you can compare your setup with mine
-> here >
-> [simple-backstage-app](https://github.com/johnson-jesse/simple-backstage-app).
+> 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.

 # The Skeleton Application

@@ -55,6 +52,16 @@ guest. Let's fix that now and add auth.

 # The Auth Configuration

+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.
+
+<details><summary>Github</summary>
+<p>
+
 1. Open `app-config.yaml` and change it as follows

 _from:_
@@ -75,23 +82,224 @@ auth:
          $env: AUTH_GITHUB_CLIENT_ID
        clientSecret:
          $env: AUTH_GITHUB_CLIENT_SECRET
-        ## uncomment the following three lines if using enterprise
+        ## uncomment the following two lines if using enterprise
        # enterpriseInstanceUrl:
        #  $env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL
 ```

-2. Set environment variables in whatever fashion is easiest for you. I chose to
+2. 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`
+
+</p>
+</details>
+
+<details><summary>Gitlab</summary>
+<p>
+
+1. Open `app-config.yaml` and change it as follows
+
+_from:_
+
+```yaml
+auth:
+  providers: {}
+```
+
+_to:_
+
+```yaml
+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
+```
+
+2. 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`
+
+</p>
+</details>
+
+<details><summary>Google</summary>
+<p>
+
+1. Open `app-config.yaml` and change it as follows
+
+_from:_
+
+```yaml
+auth:
+  providers: {}
+```
+
+_to:_
+
+```yaml
+auth:
+  providers:
+    google:
+      development:
+        clientId:
+          $env: AUTH_GOOGLE_CLIENT_ID
+        clientSecret:
+          $env: AUTH_GOOGLE_CLIENT_SECRET
+```
+
+2. 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`
+
+</p>
+</details>
+
+<details><summary>Microsoft</summary>
+<p>
+
+1. Open `app-config.yaml` and change it as follows
+
+_from:_
+
+```yaml
+auth:
+  providers: {}
+```
+
+_to:_
+
+```yaml
+auth:
+  providers:
+    microsoft:
+      development:
+        clientId:
+          $env: AUTH_MICROSOFT_CLIENT_ID
+        clientSecret:
+          $env: AUTH_MICROSOFT_CLIENT_SECRET
+        tenantId:
+          $env: AUTH_MICROSOFT_TENANT_ID
+```
+
+2. 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` from
+  `Application (client) Id` displayed on the directory page
+- Set environment variable `AUTH_MICROSOFT_TENANT_ID` from
+  `Directory (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 the `value` field
+  created.
+
+</p>
+</details>
+
+<details><summary>Auth0</summary>
+<p>
+
+1. Open `app-config.yaml` and change it as follows
+
+_from:_
+
+```yaml
+auth:
+  providers: {}
+```
+
+_to:_
+
+```yaml
+auth:
+  providers:
+    auth0:
+      development:
+        clientId:
+          $env: AUTH_AUTH0_CLIENT_ID
+        clientSecret:
+          $env: AUTH_AUTH0_CLIENT_SECRET
+        domain:
+          $env: AUTH_AUTH0_DOMAIN_ID
+```
+
+2. 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` from `Client ID` displayed on Auth0 application page
+  - `AUTH_AUTH0_CLIENT_SECRET` from `Client Secret` displayed on Auth0
+    application page
+  - `AUTH_AUTH0_DOMAIN_ID` from `Domain` displayed on Auth0 application page
+
+</p>
+</details>
+
+3. Set environment variables in whatever fashion is easiest for you. I chose to
   add mine to my `.zshrc` profile.

 ```zsh
 # 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
 ```

-3. And of course I need to source that file.
+4. And of course I need to source that file.

 ```zsh
 # Loading the new variables
@@ -107,26 +315,26 @@ export AUTH_GITHUB_CLIENT_SECRET=xxx
 > ...
 ```

-4. The values to replace `xxx` above come from your oauth app setup.
-
-```
-> 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 the environment variables above, `AUTH_GITHUB_CLIENT_ID` & `AUTH_GITHUB_CLIENT_SECRET`
-> Don't forget to `source` that profile file again if necessary.
-```
-
-5. Open and change _root > packages > app > src >_`App.tsx` as follows
+6. Open and change _root > packages > app > src >_`App.tsx` to use correct
+   authentication provider reference

 ```tsx
-// Add the following imports to the existing list from core
 import { githubAuthApiRef, SignInPage } from '@backstage/core';
 ```

-6. In the same file, change the createApp function as follows
+Modify the imported reference based on authentication method selected above
+
+| Auth Provider | Import Name         |
+| ------------- | ------------------- |
+| Github        | githubAuthApiRef    |
+| Gitlab        | gitlabAuthApiRef    |
+| Google        | googleAuthApiRef    |
+| Microsoft     | microsoftAuthApiRef |
+| Auth0         | googleAuthApiRef    |
+
+7. In the same file, modify createApp
+
+Remeber to modify the provider information based on the table above.

 ```tsx
 const app = createApp({
@@ -153,12 +361,17 @@ const app = createApp({
 });
 ```

-7. Start the backend and frontend as before
+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.
+
 # Where to go from here

 > You're probably eager to write your first custom plugin. Follow this next