Merge pull request #14628 from dagda1/improve-docs-auth-custom-scmauthapi

improve the Custom ScmAuthApi Implementation section of docs/auth

docs/auth/index.md

@@ -258,9 +258,58 @@ 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 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`:
+```ts
+ScmAuth.createDefaultApiFactory();
+```
+
+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.
+
+```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 only a github provider.
+
+```ts
+export const apis: AnyApiFactory[] = [
+  createApiFactory({
+    api: scmAuthApiRef,
+    deps: {
+      githubAuthApi: githubAuthApiRef,
+    },
+    factory: ({ githubAuthApi }) =>
+      ScmAuth.merge(
+        ScmAuth.forGithub(githubAuthApi),
+      ),
+  });
+```
+
+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 a common internal package for APIs, such as `@internal/apis`:
+
+```ts
+const gheAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & SessionApi> =
+  createApiRef({
+    id: 'internal.auth.ghe',
+  });
+```
+
+The new ref is then used to add a new provider to the ApiFactory:
 
 ```ts
 createApiFactory({
@@ -278,3 +327,14 @@ 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`:
+
+```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(),
+},
+```