Merge pull request #9513 from backstage/rugvip/authdocs

docs: tweak auth docs and add new ScmAuthApi section + link from error

.changeset/seven-rocks-share.md

@@ -0,0 +1,5 @@
+---
+'@backstage/integration-react': patch
+---
+
+Updated the `ScmAuth` error message for missing provider configurations to link to `ScmAuthApi` setup documentation.

docs/auth/index.md

@@ -56,18 +56,15 @@ allows a single auth backend to serve multiple environments, such as running a
 local frontend against a deployed backend. The provider configuration matching
 the local `auth.environment` setting will be selected.
 
-### Adding the provider to the sign-in page
+## Using an authentication provider for sign-in
 
-After configuring an authentication provider, the `app` frontend package needs a
-small update to show this provider as a login option. The `SignInPage` component
-handles this, and takes either a `provider` or `providers` (array) prop of
-`SignInProviderConfig` definitions.
+If you want to use an authentication provider for sign-in, as opposed to just accessing external resources, you'll need to configure that in your app as well. This is done by providing a custom `SignInPage` component to the app, which will require the user to sign in before they can access the app. Note that this does not block access to the app, which you can read more about [here](./using-auth.md).
 
-These reference the `ApiRef` exported by the provider. Again, an example using
-GitHub that can be adapted to any of the built-in providers:
+If you want to, you can use the `SignInPage` component that is provided by `@backstage/core-components`, which takes either a `provider` or `providers` (array) prop of `SignInProviderConfig` definitions. These reference the `ApiRef` exported for the provider.
+
+Again, the following example for GitHub shows the additions needed to `packages/app/src/App.tsx`, and can be adapted to any of the built-in providers:
 
 ```diff
-# packages/app/src/App.tsx
 + import { githubAuthApiRef } from '@backstage/core-plugin-api';
 + import { SignInProviderConfig, SignInPage } from '@backstage/core-components';
 
@@ -78,8 +75,8 @@ GitHub that can be adapted to any of the built-in providers:
 +  apiRef: githubAuthApiRef,
 +};
 +
-const app = createApp({
-  apis,
+ const app = createApp({
+   apis,
 +  components: {
 +    SignInPage: props => (
 +      <SignInPage
@@ -89,15 +86,15 @@ const app = createApp({
 +      />
 +    ),
 +  },
-  bindRoutes({ bind }) {
+   bindRoutes({ bind }) {
 ```
 
 To also allow unauthenticated guest access, use the `providers` prop for
 `SignInPage`:
 
 ```diff
-const app = createApp({
-  apis,
+ const app = createApp({
+   apis,
 +  components: {
 +    SignInPage: props => (
 +      <SignInPage
@@ -106,7 +103,7 @@ const app = createApp({
 +      />
 +    ),
 +  },
-  bindRoutes({ bind }) {
+   bindRoutes({ bind }) {
 ```
 
 ## Adding a custom authentication provider
@@ -119,3 +116,26 @@ Backstage uses [Passport](http://www.passportjs.org/) under the hood, which has
 a wide library of authentication strategies for different providers. See
 [Add authentication provider](add-auth-provider.md) for details on adding a new
 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.
+
+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
+createApiFactory({
+  api: scmAuthApiRef,
+  deps: {
+    gheAuthApi: gheAuthApiRef,
+    githubAuthApi: githubAuthApiRef,
+  },
+  factory: ({ githubAuthApi, gheAuthApi }) =>
+    ScmAuth.merge(
+      ScmAuth.forGithub(githubAuthApi),
+      ScmAuth.forGithub(gheAuthApi, {
+        host: 'ghe.example.com',
+      }),
+    ),
+});
+```

microsite/pages/en/link.js

@@ -5,6 +5,7 @@ const React = require('react');
 const redirects = {
   'bind-routes':
     '/docs/plugins/composability#binding-external-routes-in-the-app',
+  'scm-auth': '/docs/auth/#custom-scmauthapi-implementation',
 };
 const fallback = '/docs';
 

packages/integration-react/src/api/ScmAuth.test.ts

@@ -238,7 +238,7 @@ describe('ScmAuth', () => {
     await expect(
       emptyMux.getCredentials({ url: 'http://example.com' }),
     ).rejects.toThrow(
-      "No authentication provider available for access to 'http://example.com'",
+      "No auth provider available for 'http://example.com', see https://backstage.io/link?scm-auth",
     );
 
     const scmAuth = ScmAuth.merge(
@@ -256,12 +256,12 @@ describe('ScmAuth', () => {
     await expect(
       scmAuth.getCredentials({ url: 'http://not.example.com' }),
     ).rejects.toThrow(
-      "No authentication provider available for access to 'http://not.example.com'",
+      "No auth provider available for 'http://not.example.com', see https://backstage.io/link?scm-auth",
     );
     await expect(
       scmAuth.getCredentials({ url: 'http://example.com:8080' }),
     ).rejects.toThrow(
-      "No authentication provider available for access to 'http://example.com:8080'",
+      "No auth provider available for 'http://example.com:8080', see https://backstage.io/link?scm-auth",
     );
   });
 });

packages/integration-react/src/api/ScmAuth.ts

@@ -53,7 +53,7 @@ class ScmAuthMux implements ScmAuthApi {
     const provider = this.#providers.find(p => p.isUrlSupported(url));
     if (!provider) {
       throw new Error(
-        `No authentication provider available for access to '${options.url}'`,
+        `No auth provider available for '${options.url}', see https://backstage.io/link?scm-auth`,
       );
     }