From 6574d52e6f4978d63e496d9b53d8a8e61c0e7277 Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Tue, 15 Nov 2022 09:06:47 +0000 Subject: [PATCH 1/4] improve the Custom ScmAuthApi Implementation section of docs/auth Signed-off-by: Paul Cowan --- docs/auth/index.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index ab04d3ed87..bdf053c57c 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -260,7 +260,18 @@ Passport-supported authentication method. If you are using any custom authentication providers, like for example one for GitHub Enterprise, then you are likely to need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed, and is used for example by the Scaffolder (Software Templates) and Catalog Import plugins. -To set up a custom `ScmAuthApi` implementation, you'll need to add an API factory entry to `packages/app/src/apis.ts`. The following example shows an implementation that supports both public GitHub via `githubAuthApi` as well as a GitHub Enterprise installation hosted at `ghe.example.com` via `gheAuthApi`: +To set up a custom `ScmAuthApi` implementation, you'll will need to complete the following steps which creates an example entry for a github enterprise installation: + +1. Create an additional `xxxAuthApiRef` which can be defined either inside the app itself if it's only used for this purpose, or inside an internal common package for APIs, such as `@internal/apis`: + + ```ts + const gheAuthApiRef: ApiRef = + createApiRef({ + id: 'internal.auth.ghe', + }); + ``` + +2. Add an API factory entry to `packages/app/src/apis.ts`. The following example shows an implementation that supports both public GitHub via `githubAuthApi` as well as a GitHub Enterprise installation hosted at `ghe.example.com` via `gheAuthApi`: ```ts createApiFactory({ @@ -278,3 +289,16 @@ createApiFactory({ ), }); ``` +_**Warning:** You will need to remove the default `ScmAuth.createDefaultApiFactory();` with this approach. + +3. Finally you also need to add and configure another GitHub provider to the `auth-backend` using the provider ID, which in this example is `ghe`: + + + ```ts + import { providers } from '@backstage/plugin-auth-backend'; + + // Add the following options to `createRouter` in packages/backend/src/plugins/auth.ts + providerFactories: { + ghe: providers.github.create(), + }, + ``` \ No newline at end of file From 1a15f11d5f1c979da5b69fc7d11d205403d4512c Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Tue, 15 Nov 2022 09:37:43 +0000 Subject: [PATCH 2/4] run prettier Signed-off-by: Paul Cowan --- docs/auth/index.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index bdf053c57c..c77d42a86c 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -264,12 +264,12 @@ To set up a custom `ScmAuthApi` implementation, you'll will need to complete the 1. Create an additional `xxxAuthApiRef` which can be defined either inside the app itself if it's only used for this purpose, or inside an internal common package for APIs, such as `@internal/apis`: - ```ts - const gheAuthApiRef: ApiRef = - createApiRef({ - id: 'internal.auth.ghe', - }); - ``` +```ts +const gheAuthApiRef: ApiRef = + createApiRef({ + id: 'internal.auth.ghe', + }); +``` 2. Add an API factory entry to `packages/app/src/apis.ts`. The following example shows an implementation that supports both public GitHub via `githubAuthApi` as well as a GitHub Enterprise installation hosted at `ghe.example.com` via `gheAuthApi`: @@ -289,16 +289,16 @@ createApiFactory({ ), }); ``` -_**Warning:** You will need to remove the default `ScmAuth.createDefaultApiFactory();` with this approach. -3. Finally you also need to add and configure another GitHub provider to the `auth-backend` using the provider ID, which in this example is `ghe`: +\_**Warning:** You will need to remove the default `ScmAuth.createDefaultApiFactory();` with this approach. +3. Finally you also need to add and configure another GitHub provider to the `auth-backend` using the provider ID, which in this example is `ghe`: - ```ts - import { providers } from '@backstage/plugin-auth-backend'; - - // Add the following options to `createRouter` in packages/backend/src/plugins/auth.ts - providerFactories: { - ghe: providers.github.create(), - }, - ``` \ No newline at end of file +```ts +import { providers } from '@backstage/plugin-auth-backend'; + +// Add the following options to `createRouter` in packages/backend/src/plugins/auth.ts +providerFactories: { + ghe: providers.github.create(), +}, +``` From 1e0a64a5247a9e67c96024f1825ddb3b385a67f9 Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Thu, 17 Nov 2022 10:38:32 +0000 Subject: [PATCH 3/4] update custom ScmAuthApi Implementation docs Signed-off-by: Paul Cowan --- docs/auth/index.md | 50 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 7 deletions(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index c77d42a86c..8f973a3611 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -258,11 +258,49 @@ Passport-supported authentication method. ## Custom ScmAuthApi Implementation -If you are using any custom authentication providers, like for example one for GitHub Enterprise, then you are likely to need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed, and is used for example by the Scaffolder (Software Templates) and Catalog Import plugins. +The default `ScmAuthAPi` provides integrations for `github`, `gitlab`, `azure` and `bitbucket` and is created by the following code in `packages/app/src/apis.ts`: -To set up a custom `ScmAuthApi` implementation, you'll will need to complete the following steps which creates an example entry for a github enterprise installation: +```ts +ScmAuth.createDefaultApiFactory(); +``` -1. Create an additional `xxxAuthApiRef` which can be defined either inside the app itself if it's only used for this purpose, or inside an internal common package for APIs, such as `@internal/apis`: +If you only require only a subset of these integrations then you will need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed, and is used for example by the Scaffolder (Software Templates) and Catalog Import plugins. + +The first step is to remove the code that creates the default providers. + +```diff + import { + ScmIntegrationsApi, + scmIntegrationsApiRef, ++ ScmAuth, + } from '@backstage/integration-react'; + + export const apis: AnyApiFactory[] = [ +... ++ ScmAuth.createDefaultApiFactory(), +... + ]; +``` + +Then replace it with something like this which will create an `ApiFactory` with + +```ts +export const apis: AnyApiFactory[] = [ + createApiFactory({ + api: scmAuthApiRef, + deps: { + githubAuthApi: githubAuthApiRef, + }, + factory: ({ githubAuthApi }) => + ScmAuth.merge( + ScmAuth.forGithub(githubAuthApi), + ), + }); +``` + +If you are using any custom authentication integrations, a new provider can be added to the `ApiFactory`. + +The first step is to create a new authentication ref which follows the naming convention of `xxxAuthApiRef`. The example below is for a new github enterprise integration which can be defined either inside the app itself if it's only used for this purpose, or inside an internal common package for APIs, such as `@internal/apis`: ```ts const gheAuthApiRef: ApiRef = @@ -271,7 +309,7 @@ const gheAuthApiRef: ApiRef = }); ``` -2. Add an API factory entry to `packages/app/src/apis.ts`. The following example shows an implementation that supports both public GitHub via `githubAuthApi` as well as a GitHub Enterprise installation hosted at `ghe.example.com` via `gheAuthApi`: +The new ref is then used to add a new provider to the ApiFactory: ```ts createApiFactory({ @@ -290,9 +328,7 @@ createApiFactory({ }); ``` -\_**Warning:** You will need to remove the default `ScmAuth.createDefaultApiFactory();` with this approach. - -3. Finally you also need to add and configure another GitHub provider to the `auth-backend` using the provider ID, which in this example is `ghe`: +Finally you also need to add and configure another provider to the `auth-backend` using the provider ID, which in this example is `ghe`: ```ts import { providers } from '@backstage/plugin-auth-backend'; From cd03a88ea973b7b8e54396b361f7cf68261b1004 Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Thu, 17 Nov 2022 10:53:04 +0000 Subject: [PATCH 4/4] run prettier Signed-off-by: Paul Cowan --- docs/auth/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index 8f973a3611..5702e96cee 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -264,7 +264,7 @@ The default `ScmAuthAPi` provides integrations for `github`, `gitlab`, `azure` a ScmAuth.createDefaultApiFactory(); ``` -If you only require only a subset of these integrations then you will need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed, and is used for example by the Scaffolder (Software Templates) and Catalog Import plugins. +If you require only a subset of these integrations, then you will need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate different SCM systems generically, based on what resource is being accessed, and is used for example, by the Scaffolder (Software Templates) and Catalog Import plugins. The first step is to remove the code that creates the default providers. @@ -282,7 +282,7 @@ The first step is to remove the code that creates the default providers. ]; ``` -Then replace it with something like this which will create an `ApiFactory` with +Then replace it with something like this, which will create an `ApiFactory` with only a github provider. ```ts export const apis: AnyApiFactory[] = [ @@ -298,9 +298,9 @@ export const apis: AnyApiFactory[] = [ }); ``` -If you are using any custom authentication integrations, a new provider can be added to the `ApiFactory`. +If you use any custom authentication integrations, a new provider can be added to the `ApiFactory`. -The first step is to create a new authentication ref which follows the naming convention of `xxxAuthApiRef`. The example below is for a new github enterprise integration which can be defined either inside the app itself if it's only used for this purpose, or inside an internal common package for APIs, such as `@internal/apis`: +The first step is to create a new authentication ref, which follows the naming convention of `xxxAuthApiRef`. The example below is for a new GitHub enterprise integration which can be defined either inside the app itself if it's only used for this purpose or inside a common internal package for APIs, such as `@internal/apis`: ```ts const gheAuthApiRef: ApiRef = @@ -328,7 +328,7 @@ createApiFactory({ }); ``` -Finally you also need to add and configure another provider to the `auth-backend` using the provider ID, which in this example is `ghe`: +Finally, you also need to add and configure another provider to the `auth-backend` using the provider ID, which in this example is `ghe`: ```ts import { providers } from '@backstage/plugin-auth-backend';