From caa0979c4ae41a3b4892c2f5b193ed892b0499fb Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 14 Feb 2022 13:13:28 +0100 Subject: [PATCH 1/4] docs: update auth sign-in setup docs Signed-off-by: Patrik Oldsberg --- docs/auth/index.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index e407480f65..afed116afb 100644 --- a/docs/auth/index.md +++ b/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 the your app as well. This is done by provided a custom `SingInPage` component to the app, which will require the user to sign-in before they can access the app. Note that this is 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 use 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 => ( + + ), + }, - 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 => ( + + ), + }, - bindRoutes({ bind }) { + bindRoutes({ bind }) { ``` ## Adding a custom authentication provider From c939e23269dd0b41a1d438ea3021f845596dddcc Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 14 Feb 2022 13:29:50 +0100 Subject: [PATCH 2/4] docs: add scm auth setup docs Signed-off-by: Patrik Oldsberg --- docs/auth/index.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/auth/index.md b/docs/auth/index.md index afed116afb..8b16764d23 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -116,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 what resource is being accessed, and is used for example by the Scaffolder (Software Templates) and Catalog Import plugin. + +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', + }), + ), +}); +``` From f0e2f7a56a5ff9a70d67169276e47c042bd1d8fe Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 14 Feb 2022 13:32:42 +0100 Subject: [PATCH 3/4] integration-react: link to scm auth setup docs if provider config is missing Signed-off-by: Patrik Oldsberg --- .changeset/seven-rocks-share.md | 5 +++++ microsite/pages/en/link.js | 1 + packages/integration-react/src/api/ScmAuth.test.ts | 6 +++--- packages/integration-react/src/api/ScmAuth.ts | 2 +- 4 files changed, 10 insertions(+), 4 deletions(-) create mode 100644 .changeset/seven-rocks-share.md diff --git a/.changeset/seven-rocks-share.md b/.changeset/seven-rocks-share.md new file mode 100644 index 0000000000..db131a85dc --- /dev/null +++ b/.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. diff --git a/microsite/pages/en/link.js b/microsite/pages/en/link.js index ddac35e545..727b15bfd8 100644 --- a/microsite/pages/en/link.js +++ b/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'; diff --git a/packages/integration-react/src/api/ScmAuth.test.ts b/packages/integration-react/src/api/ScmAuth.test.ts index 4ebfef749e..1ad391d8d2 100644 --- a/packages/integration-react/src/api/ScmAuth.test.ts +++ b/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", ); }); }); diff --git a/packages/integration-react/src/api/ScmAuth.ts b/packages/integration-react/src/api/ScmAuth.ts index 071374e6cb..b3dab4029e 100644 --- a/packages/integration-react/src/api/ScmAuth.ts +++ b/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`, ); } From baf9097e2c1666debcb12e0a436235e457627fd7 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 14 Feb 2022 15:37:58 +0100 Subject: [PATCH 4/4] docs: fix auth doc spleling Signed-off-by: Patrik Oldsberg --- docs/auth/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index 8b16764d23..6bda35232a 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -58,9 +58,9 @@ the local `auth.environment` setting will be selected. ## Using an authentication provider for sign-in -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 the your app as well. This is done by provided a custom `SingInPage` component to the app, which will require the user to sign-in before they can access the app. Note that this is does not block access to the app, which you can read more about [here](./using-auth.md). +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). -If you want to use 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. +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: @@ -119,7 +119,7 @@ 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 what resource is being accessed, and is used for example by the Scaffolder (Software Templates) and Catalog Import plugin. +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`: