From 85f2d90543c4274e74b6dba044489b44e50adfd6 Mon Sep 17 00:00:00 2001 From: Maixmilian Ressel Date: Tue, 14 Jun 2022 16:22:54 +0200 Subject: [PATCH 1/2] docs: scaffolder: improve docs to setup the RepoUrlPicker authentication Signed-off-by: Maixmilian Ressel --- docs/auth/index.md | 18 ++++++++++++++++++ .../software-templates/writing-templates.md | 3 +++ microsite/pages/en/link.js | 2 +- 3 files changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index c34d244886..e644fb74ed 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -185,6 +185,24 @@ const app = createApp({ When using multiple auth providers like this, it's important that you configure the different sign-in resolvers so that they resolve to the same identity regardless of the method used. +## Scaffolder Configuration (Software Templates) + +If you want to use the authentication capabilities of the [Repository Picker](../features/software-templates/writing-templates.md#the-repository-picker) inside your Software Templates you will need to configure the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi) alongside your authentication provider. It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed. + +To set it up, you'll need to add an API factory entry to `packages/app/src/apis.ts`. The example below sets up the `ScmAuthApi` for an already configured GitLab authentication provider: + +```ts +createApiFactory({ + api: scmAuthApiRef, + deps: { + gitlabAuthApi: gitlabAuthApiRef, + }, + factory: ({ gitlabAuthApi }) => ScmAuth.forGitlab(gitlabAuthApi), +}); +``` + +In case you are using a custom authentication providers, you might need to add a [custom `ScmAuthApi` implementation](./index.md#custom-scmauthapi-implementation). + ## For Plugin Developers The Backstage frontend core APIs provide a set of Utility APIs for plugin developers diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md index 27e6e76817..4078b18a2b 100644 --- a/docs/features/software-templates/writing-templates.md +++ b/docs/features/software-templates/writing-templates.md @@ -397,6 +397,9 @@ There's also the ability to pass additional scopes when requesting the `oauth` token from the user, which you can do on a per-provider basis, in case your template can be published to multiple providers. +Note, that you will need to configure an [authentication provider](../../auth/index.md#configuring-authentication-providers), alongside the +[`ScmAuthApi`](../../auth/index.md#scaffolder-configuration-software-templates) for your source code management (scm) service to make this feature work. + ### Accessing the signed-in users details Sometimes when authoring templates, you'll want to access the user that is running the template, and get details from the profile or the users `Entity` in the Catalog. diff --git a/microsite/pages/en/link.js b/microsite/pages/en/link.js index 727b15bfd8..6f56aa768c 100644 --- a/microsite/pages/en/link.js +++ b/microsite/pages/en/link.js @@ -5,7 +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', + 'scm-auth': '/docs/auth/#scaffolder-configuration-software-templates', }; const fallback = '/docs'; From 557072e19b8da48a4203b1458436a8eb21cbfb2a Mon Sep 17 00:00:00 2001 From: Maixmilian Ressel Date: Thu, 16 Jun 2022 12:43:32 +0200 Subject: [PATCH 2/2] change some capitalizations Signed-off-by: Maixmilian Ressel --- docs/auth/index.md | 2 +- docs/features/software-templates/writing-templates.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index e644fb74ed..e713e722ef 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -187,7 +187,7 @@ sign-in resolvers so that they resolve to the same identity regardless of the me ## Scaffolder Configuration (Software Templates) -If you want to use the authentication capabilities of the [Repository Picker](../features/software-templates/writing-templates.md#the-repository-picker) inside your Software Templates you will need to configure the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi) alongside your authentication provider. It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed. +If you want to use the authentication capabilities of the [Repository Picker](../features/software-templates/writing-templates.md#the-repository-picker) inside your software templates you will need to configure the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi) alongside your authentication provider. It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed. To set it up, you'll need to add an API factory entry to `packages/app/src/apis.ts`. The example below sets up the `ScmAuthApi` for an already configured GitLab authentication provider: diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md index 4078b18a2b..ff9962d8d4 100644 --- a/docs/features/software-templates/writing-templates.md +++ b/docs/features/software-templates/writing-templates.md @@ -398,7 +398,7 @@ token from the user, which you can do on a per-provider basis, in case your template can be published to multiple providers. Note, that you will need to configure an [authentication provider](../../auth/index.md#configuring-authentication-providers), alongside the -[`ScmAuthApi`](../../auth/index.md#scaffolder-configuration-software-templates) for your source code management (scm) service to make this feature work. +[`ScmAuthApi`](../../auth/index.md#scaffolder-configuration-software-templates) for your source code management (SCM) service to make this feature work. ### Accessing the signed-in users details