From f07848c770ef6e1b60070e0f7f8d7bc0134a496f Mon Sep 17 00:00:00 2001 From: Tim Hansen Date: Fri, 26 Mar 2021 10:24:45 -0600 Subject: [PATCH 1/2] Add documentation for included auth providers Signed-off-by: Tim Hansen --- docs/auth/auth0/provider.md | 74 +++++++++++++++++++++++++++ docs/auth/github/provider.md | 77 ++++++++++++++++++++++++++++ docs/auth/gitlab/provider.md | 76 ++++++++++++++++++++++++++++ docs/auth/google/provider.md | 81 +++++++++++++++++++++++++++++ docs/auth/microsoft/provider.md | 77 ++++++++++++++++++++++++++++ docs/auth/okta/provider.md | 90 +++++++++++++++++++++++++++++++++ docs/integrations/github/org.md | 4 ++ microsite/sidebars.json | 12 +++++ 8 files changed, 491 insertions(+) create mode 100644 docs/auth/auth0/provider.md create mode 100644 docs/auth/github/provider.md create mode 100644 docs/auth/gitlab/provider.md create mode 100644 docs/auth/google/provider.md create mode 100644 docs/auth/microsoft/provider.md create mode 100644 docs/auth/okta/provider.md diff --git a/docs/auth/auth0/provider.md b/docs/auth/auth0/provider.md new file mode 100644 index 0000000000..e2bed15e55 --- /dev/null +++ b/docs/auth/auth0/provider.md @@ -0,0 +1,74 @@ +--- +id: provider +title: Auth0 Authentication Provider +sidebar_label: Auth0 +description: Adding Auth0 as an authentication provider in Backstage +--- + +The Backstage `core-api` package comes with an Auth0 authentication provider +that can authenticate users using OAuth. + +## Create an Auth0 Application + +1. Log in to the [Auth0 dashboard](https://manage.auth0.com/dashboard/) +2. Navigate to **Applications** +3. Create an Application + - Name: Backstage (or your custom app name) + - Application type: Single Page Web Application +4. Click on the Settings tab +5. Add under `Application URIs` > `Allowed Callback URLs`: + `http://localhost:7000/api/auth/auth0/handler/frame` +6. Click `Save Changes` + +## Configuration + +The provider configuration can then be added to your `app-config.yaml` under the +root `auth` configuration: + +```yaml +auth: + environment: development + providers: + auth0: + development: + clientId: ${AUTH_AUTH0_CLIENT_ID} + clientSecret: ${AUTH_AUTH0_CLIENT_SECRET} + domain: ${AUTH_AUTH0_DOMAIN_ID} +``` + +The Auth0 provider is a structure with three configuration keys: + +- `clientId`: The Application client ID, found on the Auth0 Application page +- `clientSecret`: The Application client secret, found on the Auth0 Application + page +- `domain`: The Application domain, found on the Auth0 Application page + +## Adding the provider to the Backstage frontend + +To add the provider to the frontend, add the auth0AuthApi reference and +SignInPage component to `createApp` in `packages/app/src/App.tsx`: + +```diff ++ import { auth0AuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; + ++ const auth0Provider: SignInConfig = { ++ id: 'auth0-auth-provider', ++ title: 'Auth0', ++ message: 'Sign in using Auth0', ++ apiRef: auth0AuthApiRef, ++}; ++ +const app = createApp({ + apis, + plugins: Object.values(plugins), ++ components: { ++ SignInPage: props => ( ++ ++ ), ++ }, + bindRoutes({ bind }) { +``` diff --git a/docs/auth/github/provider.md b/docs/auth/github/provider.md new file mode 100644 index 0000000000..6a4d952b6b --- /dev/null +++ b/docs/auth/github/provider.md @@ -0,0 +1,77 @@ +--- +id: provider +title: GitHub Authentication Provider +sidebar_label: GitHub +description: Adding GitHub OAuth as an authentication provider in Backstage +--- + +The Backstage `core-api` package comes with a GitHub authentication provider +that can authenticate users using GitHub or GitHub Enterprise OAuth. + +## Create an OAuth App on GitHub + +To add GitHub authentication, you must create an OAuth App from the GitHub +[developer settings](https://github.com/settings/developers). The `Homepage URL` +should point to Backstage's frontend, while the `Authorization callback URL` +will point to the auth backend. + +Settings for local development: + +- Application name: Backstage (or your custom app name) +- Homepage URL: `http://localhost:3000` +- Authorization callback URL: `http://localhost:7000/api/auth/github` + +## Configuration + +The provider configuration can then be added to your `app-config.yaml` under the +root `auth` configuration: + +```yaml +auth: + environment: development + providers: + github: + development: + clientId: ${AUTH_GITHUB_CLIENT_ID} + clientSecret: ${AUTH_GITHUB_CLIENT_SECRET} + ## uncomment if using GitHub Enterprise + # enterpriseInstanceUrl: ${AUTH_GITHUB_ENTERPRISE_INSTANCE_URL} +``` + +The GitHub provider is a structure with three configuration keys: + +- `clientId`: The client ID that you generated on GitHub, e.g. + `b59241722e3c3b4816e2` +- `clientSecret`: The client secret tied to the generated client ID. +- `enterpriseInstanceUrl` (optional): The base URL for a GitHub Enterprise + instance, e.g. `https://ghe..com`. Only needed for GitHub Enterprise. + +## Adding the provider to the Backstage frontend + +To add the provider to the frontend, add the githubAuthApi reference and +SignInPage component to `createApp` in `packages/app/src/App.tsx`: + +```diff ++ import { githubAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; + ++ const githubProvider: SignInConfig = { ++ id: 'github-auth-provider', ++ title: 'GitHub', ++ message: 'Sign in using GitHub', ++ apiRef: githubAuthApiRef, ++}; ++ +const app = createApp({ + apis, + plugins: Object.values(plugins), ++ components: { ++ SignInPage: props => ( ++ ++ ), ++ }, + bindRoutes({ bind }) { +``` diff --git a/docs/auth/gitlab/provider.md b/docs/auth/gitlab/provider.md new file mode 100644 index 0000000000..99f9117e2e --- /dev/null +++ b/docs/auth/gitlab/provider.md @@ -0,0 +1,76 @@ +--- +id: provider +title: GitLab Authentication Provider +sidebar_label: GitLab +description: Adding GitLab OAuth as an authentication provider in Backstage +--- + +The Backstage `core-api` package comes with a GitLab authentication provider +that can authenticate users using GitLab OAuth. + +## Create an OAuth App on GitLab + +To support GitLab authentication, you must create an Application from the +[GitLab settings](https://gitlab.com/-/profile/applications). The `Redirect URI` +should point to your Backstage backend auth handler. + +Settings for local development: + +- Name: Backstage (or your custom app name) +- Redirect URI: `http://localhost:7000/api/auth/gitlab/handler/frame` +- Scopes: read_user + +## Configuration + +The provider configuration can then be added to your `app-config.yaml` under the +root `auth` configuration: + +```yaml +auth: + environment: development + providers: + gitlab: + development: + clientId: ${AUTH_GITLAB_APPLICATION_ID} + clientSecret: ${AUTH_GITLAB_SECRET} + ## uncomment if using self-hosted GitLab + # audience: https://gitlab.company.com +``` + +The GitLab provider is a structure with three configuration keys: + +- `clientId`: The Application ID that you generated on GitLab, e.g. + `4928c033ab3d592845c044a653bc20583baf84f2e67b954c6fdb32a532ab76c9` +- `clientSecret`: The Application secret +- `audience` (optional): The base URL for the self-hosted GitLab instance, e.g. + `https://gitlab.company.com` + +## Adding the provider to the Backstage frontend + +To add the provider to the frontend, add the gitlabAuthApi reference and +SignInPage component to `createApp` in `packages/app/src/App.tsx`: + +```diff ++ import { gitlabAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; + ++ const gitlabProvider: SignInConfig = { ++ id: 'gitlab-auth-provider', ++ title: 'GitLab', ++ message: 'Sign in using GitLab', ++ apiRef: gitlabAuthApiRef, ++}; ++ +const app = createApp({ + apis, + plugins: Object.values(plugins), ++ components: { ++ SignInPage: props => ( ++ ++ ), ++ }, + bindRoutes({ bind }) { +``` diff --git a/docs/auth/google/provider.md b/docs/auth/google/provider.md new file mode 100644 index 0000000000..ea25d6d2a6 --- /dev/null +++ b/docs/auth/google/provider.md @@ -0,0 +1,81 @@ +--- +id: provider +title: Google Authentication Provider +sidebar_label: Google +description: Adding Google OAuth as an authentication provider in Backstage +--- + +The Backstage `core-api` package comes with a Google authentication provider +that can authenticate users using Google OAuth. + +## Create OAuth Credentials + +To support Google authentication, you must create OAuth credentials: + +1. Log in to the [Google Console](https://console.cloud.google.com) +2. Select or create a new project from the dropdown menu on the top bar +3. Navigate to + [APIs & Services > Credentials](https://console.cloud.google.com/apis/credentials) +4. Click **Create Credentials** and choose `OAuth client ID` +5. Configure an OAuth consent screen, if required + - For local development, you do not need to enter any Authorized domain + - For scopes, select `openid`, `auth/userinfo.email` and + `auth/userinfo.profile` + - Add yourself as a test user, if using External user type +6. Set **Application Type** to `Web Application` with these settings: + - `Name`: Backstage (or your custom app name) + - `Authorized JavaScript origins`: http://localhost:3000 + - `Authorized Redirect URIs`: + http://localhost:7000/api/auth/google/handler/frame +7. Click Create + +## Configuration + +The provider configuration can then be added to your `app-config.yaml` under the +root `auth` configuration: + +```yaml +auth: + environment: development + providers: + google: + development: + clientId: ${AUTH_GOOGLE_CLIENT_ID} + clientSecret: ${AUTH_GOOGLE_CLIENT_SECRET} +``` + +The Google provider is a structure with two configuration keys: + +- `clientId`: The client ID that you generated, e.g. + `10023341500512-beui241gjwwkrdkr2eh7dprewj2pp1q.apps.googleusercontent.com` +- `clientSecret`: The client secret tied to the generated client ID. + +## Adding the provider to the Backstage frontend + +To add the provider to the frontend, add the googleAuthApi reference and +SignInPage component to `createApp` in `packages/app/src/App.tsx`: + +```diff ++ import { googleAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; + ++ const googleProvider: SignInConfig = { ++ id: 'google-auth-provider', ++ title: 'Google', ++ message: 'Sign in using Google', ++ apiRef: googleAuthApiRef, ++}; ++ +const app = createApp({ + apis, + plugins: Object.values(plugins), ++ components: { ++ SignInPage: props => ( ++ ++ ), ++ }, + bindRoutes({ bind }) { +``` diff --git a/docs/auth/microsoft/provider.md b/docs/auth/microsoft/provider.md new file mode 100644 index 0000000000..c1080428be --- /dev/null +++ b/docs/auth/microsoft/provider.md @@ -0,0 +1,77 @@ +--- +id: provider +title: Microsoft Azure Authentication Provider +sidebar_label: Azure +description: Adding Microsoft Azure as an authentication provider in Backstage +--- + +The Backstage `core-api` package comes with a Microsoft authentication provider +that can authenticate users using Azure OAuth. + +## Create an App Registration on Azure + +To support Azure authentication, you must create an App Registration: + +1. Log in to the [Azure Portal](https://portal.azure.com/) +2. Create an + [Active Directory Tenant](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview), + if one does not yet exist +3. Navigate to + [Azure Active Directory > App Registrations](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) +4. Register an application + - Name: Backstage (or your custom app name) + - Redirect URI: Web > + `http://localhost:7000/api/auth/microsoft/handler/frame` +5. Navigate to **Certificates & secrets > New client secret** to create a secret + +## Configuration + +The provider configuration can then be added to your `app-config.yaml` under the +root `auth` configuration: + +```yaml +auth: + environment: development + providers: + microsoft: + development: + clientId: ${AUTH_MICROSOFT_CLIENT_ID} + clientSecret: ${AUTH_MICROSOFT_CLIENT_SECRET} + tenantId: ${AUTH_MICROSOFT_TENANT_ID} +``` + +The Microsoft provider is a structure with three configuration keys: + +- `clientId`: Application (client) ID, found on App Registration > Overview +- `clientSecret`: Secret, found on App Registration > Certificates & secrets +- `tenentId`: Directory (tenant) ID, found on App Registration > Overview + +## Adding the provider to the Backstage frontend + +To add the provider to the frontend, add the microsoftAuthApi reference and +SignInPage component to `createApp` in `packages/app/src/App.tsx`: + +```diff ++ import { microsoftAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; + ++ const microsoftProvider: SignInConfig = { ++ id: 'microsoft-auth-provider', ++ title: 'Microsoft Azure', ++ message: 'Sign in using Azure', ++ apiRef: microsoftAuthApiRef, ++}; ++ +const app = createApp({ + apis, + plugins: Object.values(plugins), ++ components: { ++ SignInPage: props => ( ++ ++ ), ++ }, + bindRoutes({ bind }) { +``` diff --git a/docs/auth/okta/provider.md b/docs/auth/okta/provider.md new file mode 100644 index 0000000000..3ea959a85e --- /dev/null +++ b/docs/auth/okta/provider.md @@ -0,0 +1,90 @@ +--- +id: provider +title: Okta Authentication Provider +sidebar_label: Okta +description: Adding Okta OAuth as an authentication provider in Backstage +--- + +The Backstage `core-api` package comes with a Okta authentication provider that +can authenticate users using Okta OpenID Connect. + +## Create an Application on Okta + +To add Okta authentication, you must create an Application from Okta: + +1. Log into Okta (generally company.okta.com) +2. Navigation to Applications > Applications +3. Click `Add Application` +4. Click `Create New App` and select Web + OpenID Connect +5. Fill out the OpenID Connect App Integration form: + - `Application name`: Backstage (or your custom app name) + - `Login redirect URIs`: `Add URI` > + `http://localhost:7000/api/auth/okta/handler/frame` +6. Click Save +7. Under `General Settings`, click Edit and check the `Refresh Token` box +8. Click Save + +## Assign the Application + +Okta login is only permitted to those people or groups that have this new +Application **assigned**. This can be done from Okta's Directory. + +These are the steps to assign Backstage login permission to **everyone**: + +1. Navigate to Directory > Groups on Okta +2. Click on the `Everyone` group +3. Click `Manage Apps` and then `Assign` next to Backstage + +# Configuration + +The provider configuration can then be added to your `app-config.yaml` under the +root `auth` configuration: + +```yaml +auth: + environment: development + providers: + okta: + development: + clientId: ${AUTH_OKTA_CLIENT_ID} + clientSecret: ${AUTH_OKTA_CLIENT_SECRET} + audience: ${AUTH_OKTA_DOMAIN} +``` + +The values referenced are found on the Application page on your Okta site. + +- `clientId`: The client ID that you generated on Okta, e.g. + `3abe134ejxzF21HU74c1` +- `clientSecret`: The client secret shown for the Application. +- `audience`: The Okta domain shown for your Application, e.g. + `https://company.okta.com` + +## Adding the provider to the Backstage frontend + +To add the provider to the frontend, add the oktaAuthApi reference and +SignInPage component to `createApp` in `packages/app/src/App.tsx`: + +```diff ++ import { oktaAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; + ++ const oktaProvider: SignInConfig = { ++ id: 'okta-auth-provider', ++ title: 'Okta', ++ message: 'Sign in using Okta', ++ apiRef: oktaAuthApiRef, ++}; ++ +const app = createApp({ + apis, + plugins: Object.values(plugins), ++ components: { ++ SignInPage: props => ( ++ ++ ), ++ }, + bindRoutes({ bind }) { +``` diff --git a/docs/integrations/github/org.md b/docs/integrations/github/org.md index b52e811002..4a1bf88932 100644 --- a/docs/integrations/github/org.md +++ b/docs/integrations/github/org.md @@ -13,6 +13,10 @@ is a hierarchy of [`Group`](../../features/software-catalog/descriptor-format.md#kind-group) kind entities that mirror your org setup. +> Note: This adds `User` and `Group` entities to the catalog, but does not +> provide authentication. See the +> [GitHub auth provider](../../auth/github/provider.md) for that. + ## Installation The processor that performs the import, `GithubOrgReaderProcessor`, comes diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 322ffc2e03..b719f9329c 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -184,6 +184,18 @@ "Auth and identity": [ "auth/index", "auth/add-auth-provider", + { + "type": "subcategory", + "label": "Included providers", + "ids": [ + "auth/auth0/provider", + "auth/microsoft/provider", + "auth/github/provider", + "auth/gitlab/provider", + "auth/google/provider", + "auth/okta/provider" + ] + }, "auth/auth-backend", "auth/oauth", "auth/glossary", From f5f61e659e841e7e70e1b2da9427be9a2a70b7eb Mon Sep 17 00:00:00 2001 From: Tim Hansen Date: Fri, 26 Mar 2021 11:22:38 -0600 Subject: [PATCH 2/2] Backticks Signed-off-by: Tim Hansen --- docs/auth/auth0/provider.md | 4 ++-- docs/auth/github/provider.md | 4 ++-- docs/auth/gitlab/provider.md | 4 ++-- docs/auth/google/provider.md | 4 ++-- docs/auth/microsoft/provider.md | 4 ++-- docs/auth/okta/provider.md | 4 ++-- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/auth/auth0/provider.md b/docs/auth/auth0/provider.md index e2bed15e55..383cda2014 100644 --- a/docs/auth/auth0/provider.md +++ b/docs/auth/auth0/provider.md @@ -45,8 +45,8 @@ The Auth0 provider is a structure with three configuration keys: ## Adding the provider to the Backstage frontend -To add the provider to the frontend, add the auth0AuthApi reference and -SignInPage component to `createApp` in `packages/app/src/App.tsx`: +To add the provider to the frontend, add the `auth0AuthApi` reference and +`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: ```diff + import { auth0AuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; diff --git a/docs/auth/github/provider.md b/docs/auth/github/provider.md index 6a4d952b6b..6e194f36f7 100644 --- a/docs/auth/github/provider.md +++ b/docs/auth/github/provider.md @@ -48,8 +48,8 @@ The GitHub provider is a structure with three configuration keys: ## Adding the provider to the Backstage frontend -To add the provider to the frontend, add the githubAuthApi reference and -SignInPage component to `createApp` in `packages/app/src/App.tsx`: +To add the provider to the frontend, add the `githubAuthApi` reference and +`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: ```diff + import { githubAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; diff --git a/docs/auth/gitlab/provider.md b/docs/auth/gitlab/provider.md index 99f9117e2e..e9cfdfa98e 100644 --- a/docs/auth/gitlab/provider.md +++ b/docs/auth/gitlab/provider.md @@ -47,8 +47,8 @@ The GitLab provider is a structure with three configuration keys: ## Adding the provider to the Backstage frontend -To add the provider to the frontend, add the gitlabAuthApi reference and -SignInPage component to `createApp` in `packages/app/src/App.tsx`: +To add the provider to the frontend, add the `gitlabAuthApi` reference and +`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: ```diff + import { gitlabAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; diff --git a/docs/auth/google/provider.md b/docs/auth/google/provider.md index ea25d6d2a6..2765b509f3 100644 --- a/docs/auth/google/provider.md +++ b/docs/auth/google/provider.md @@ -52,8 +52,8 @@ The Google provider is a structure with two configuration keys: ## Adding the provider to the Backstage frontend -To add the provider to the frontend, add the googleAuthApi reference and -SignInPage component to `createApp` in `packages/app/src/App.tsx`: +To add the provider to the frontend, add the `googleAuthApi` reference and +`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: ```diff + import { googleAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; diff --git a/docs/auth/microsoft/provider.md b/docs/auth/microsoft/provider.md index c1080428be..3aa9de0df1 100644 --- a/docs/auth/microsoft/provider.md +++ b/docs/auth/microsoft/provider.md @@ -48,8 +48,8 @@ The Microsoft provider is a structure with three configuration keys: ## Adding the provider to the Backstage frontend -To add the provider to the frontend, add the microsoftAuthApi reference and -SignInPage component to `createApp` in `packages/app/src/App.tsx`: +To add the provider to the frontend, add the `microsoftAuthApi` reference and +`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: ```diff + import { microsoftAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; diff --git a/docs/auth/okta/provider.md b/docs/auth/okta/provider.md index 3ea959a85e..091c5fffb6 100644 --- a/docs/auth/okta/provider.md +++ b/docs/auth/okta/provider.md @@ -61,8 +61,8 @@ The values referenced are found on the Application page on your Okta site. ## Adding the provider to the Backstage frontend -To add the provider to the frontend, add the oktaAuthApi reference and -SignInPage component to `createApp` in `packages/app/src/App.tsx`: +To add the provider to the frontend, add the `oktaAuthApi` reference and +`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: ```diff + import { oktaAuthApiRef, SignInConfig, SignInPage } from '@backstage/core';