From 005cb9fece472e16ce9f2c0605249ad1fb1827db Mon Sep 17 00:00:00 2001 From: Aditya Kumar Date: Wed, 1 Jan 2025 10:04:04 +0530 Subject: [PATCH 1/5] minor updates in provider doc file Signed-off-by: Aditya Kumar --- docs/auth/github/provider.md | 24 ++++++++++++------------ docs/auth/gitlab/provider.md | 12 ++++++------ 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/auth/github/provider.md b/docs/auth/github/provider.md index 3b61815017..c1c3fd253e 100644 --- a/docs/auth/github/provider.md +++ b/docs/auth/github/provider.md @@ -10,7 +10,7 @@ provider that can authenticate users using GitHub or GitHub Enterprise OAuth. ## Create an OAuth App on GitHub -To add GitHub authentication, you must create either a GitHub App, or an OAuth +To add GitHub authentication, you must create either a GitHub App or an OAuth App from the GitHub [developer settings](https://github.com/settings/developers). The `Homepage URL` should point to Backstage's frontend, while the `Authorization callback URL` @@ -30,9 +30,9 @@ Settings for local development: GitHub Apps handle OAuth scope at the app installation level, meaning that the `scope` parameter for the call to `getAccessToken` in the frontend has no -effect. When calling `getAccessToken` in open source plugins, one should still +effect. When calling `getAccessToken` in open-source plugins, one should still include the appropriate scope, but also document in the plugin README what -scopes are required for GitHub Apps. +Scopes are required for GitHub Apps. ## Configuration @@ -57,15 +57,15 @@ auth: The GitHub provider is a structure with these configuration keys: -- `clientId`: The client ID that you generated on GitHub, e.g. +- `clientId`: The client ID that you generated on GitHub, e.g., `b59241722e3c3b4816e2` - `clientSecret`: The client secret tied to the generated client ID. - `enterpriseInstanceUrl` (optional): The base URL for a GitHub Enterprise - instance, e.g. `https://ghe..com`. Only needed for GitHub Enterprise. + instance, e.g., `https://ghe..com`. Only needed for GitHub Enterprise. - `callbackUrl` (optional): The callback URL that GitHub will use when - initiating an OAuth flow, e.g. + initiating an OAuth flow, e.g., `https://your-intermediate-service.com/handler`. Only needed if Backstage is - not the immediate receiver (e.g. one OAuth app for many backstage instances). + not the immediate receiver (e.g., one OAuth app for many backstage instances). - `signIn`: The configuration for the sign-in process, including the **resolvers** that should be used to match the user from the auth provider with the user entity in the Backstage catalog (typically a single resolver is sufficient). @@ -74,17 +74,17 @@ The GitHub provider is a structure with these configuration keys: This provider includes several resolvers out of the box that you can use: -- `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found it will throw a `NotFoundError`. -- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`. -- `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`. +- `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found, it will throw a `NotFoundError`. +- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`. +- `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`. :::note Note -The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`. +The resolvers will be tried in order but will only be skipped if they throw a `NotFoundError`. ::: -If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation. +If these resolvers do not fit your needs, you can build a custom resolver; this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation. ## Backend Installation diff --git a/docs/auth/gitlab/provider.md b/docs/auth/gitlab/provider.md index 65d1909f41..28f204d785 100644 --- a/docs/auth/gitlab/provider.md +++ b/docs/auth/gitlab/provider.md @@ -66,21 +66,21 @@ The GitLab provider is a structure with three configuration keys: This provider includes several resolvers out of the box that you can use: -- `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found it will throw a `NotFoundError`. -- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`. -- `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`. +- `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found, it will throw a `NotFoundError`. +- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`. +- `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`. :::note Note -The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`. +The resolvers will be tried in order but will only be skipped if they throw a `NotFoundError`. ::: -If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation. +If these resolvers do not fit your needs, you can build a custom resolver; this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation. ## Backend Installation -To add the provider to the backend we will first need to install the package by running this command: +To add the provider to the backend, we will first need to install the package by running this command: ```bash title="from your Backstage root directory" yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-gitlab-provider From 307b1b148d12844b68be98befb8d48db526b3001 Mon Sep 17 00:00:00 2001 From: Aditya Kumar Date: Mon, 6 Jan 2025 08:58:28 +0530 Subject: [PATCH 2/5] minor updates in provider doc of bitbucket Signed-off-by: Aditya Kumar --- docs/auth/bitbucket/provider.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/auth/bitbucket/provider.md b/docs/auth/bitbucket/provider.md index e58ad622fc..e84e58c70a 100644 --- a/docs/auth/bitbucket/provider.md +++ b/docs/auth/bitbucket/provider.md @@ -53,22 +53,22 @@ The Bitbucket provider is a structure with two configuration keys: This provider includes several resolvers out of the box that you can use: -- `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found it will throw a `NotFoundError`. -- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`. -- `userIdMatchingUserEntityAnnotation`: Matches the `userId` from the auth provider with the User entity that has a matching `bitbucket.org/user-id` annotation. If no match is found it will throw a `NotFoundError`. -- `usernameMatchingUserEntityAnnotation`: Matches the `username` from the auth provider with the User entity that has a matching `bitbucket.org/username` annotation. If no match is found it will throw a `NotFoundError`. +- `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found, it will throw a `NotFoundError`. +- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`. +- `userIdMatchingUserEntityAnnotation`: Matches the `userId` from the auth provider with the User entity that has a matching `bitbucket.org/user-id` annotation. If no match is found, it will throw a `NotFoundError`. +- `usernameMatchingUserEntityAnnotation`: Matches the `username` from the auth provider with the User entity that has a matching `bitbucket.org/username` annotation. If no match is found, it will throw a `NotFoundError`. :::note Note -The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`. +The resolvers will be tried in order but will only be skipped if they throw a `NotFoundError`. ::: -If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation. +If these resolvers do not fit your needs, you can build a custom resolver; this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation. ## Backend Installation -To add the provider to the backend we will first need to install the package by running this command: +To add the provider to the backend, we will first need to install the package by running this command: ```bash title="from your Backstage root directory" yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-bitbucket-provider From 1d0a8e8be522b9cb5d94f1c726407f28504d0304 Mon Sep 17 00:00:00 2001 From: Aditya Kumar Date: Mon, 6 Jan 2025 08:59:27 +0530 Subject: [PATCH 3/5] minor updates in provider doc of bitbucketServer Signed-off-by: Aditya Kumar --- docs/auth/bitbucketServer/provider.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/auth/bitbucketServer/provider.md b/docs/auth/bitbucketServer/provider.md index c41457d09c..6063796dd2 100644 --- a/docs/auth/bitbucketServer/provider.md +++ b/docs/auth/bitbucketServer/provider.md @@ -45,20 +45,20 @@ The Bitbucket Server provider is a structure with two configuration keys: This provider includes several resolvers out of the box that you can use: -- `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found it will throw a `NotFoundError`. -- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`. +- `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found, it will throw a `NotFoundError`. +- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`. :::note Note -The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`. +The resolvers will be tried in order but will only be skipped if they throw a `NotFoundError`. ::: -If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation. +If these resolvers do not fit your needs, you can build a custom resolver; this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation. ## Backend Installation -To add the provider to the backend we will first need to install the package by running this command: +To add the provider to the backend, we will first need to install the package by running this command: ```bash title="from your Backstage root directory" yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-bitbucket-server-provider @@ -87,4 +87,4 @@ To add the provider to the frontend, add the `bitbucketServerAuthApiRef` referen ### ScmAuth -For backstage to be able to use the oauth token of the logged in user to access the Bitbucket Server API, you need to add it to list of ScmAuth providers as shown in [Custom ScmAuthApi Implementation](../index.md#custom-scmauthapi-implementation) using the `ScmAuth.forBitbucketServer` method. +For Backstage to be able to use the OAuth token of the logged-in user to access the Bitbucket Server API, you need to add it to the list of ScmAuth providers as shown in [Custom ScmAuthApi Implementation](../index.md#custom-scmauthapi-implementation) using the `ScmAuth.forBitbucketServer` method. From 5a0914a15a3b484bc8afe48ad468442ef993d3b2 Mon Sep 17 00:00:00 2001 From: Aditya Kumar Date: Mon, 6 Jan 2025 09:00:33 +0530 Subject: [PATCH 4/5] minor updates in provider doc of cloudflare Signed-off-by: Aditya Kumar --- docs/auth/cloudflare/provider.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/auth/cloudflare/provider.md b/docs/auth/cloudflare/provider.md index 224a64f056..7611a0ca48 100644 --- a/docs/auth/cloudflare/provider.md +++ b/docs/auth/cloudflare/provider.md @@ -51,20 +51,20 @@ This config section must be in place for the provider to load at all. This provider includes several resolvers out of the box that you can use: -- `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found it will throw a `NotFoundError`. -- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`. +- `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found, it will throw a `NotFoundError`. +- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`. :::note Note -The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`. +The resolvers will be tried in order but will only be skipped if they throw a `NotFoundError`. ::: -If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation. +If these resolvers do not fit your needs, you can build a custom resolver; this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation. ## Backend Installation -To add the provider to the backend we will first need to install the package by running this command: +To add the provider to the backend, we will first need to install the package by running this command: ```bash title="from your Backstage root directory" yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-cloudflare-access-provider @@ -83,6 +83,6 @@ backend.add( ## Adding the provider to the Backstage frontend -See [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) for pointers on how to set up the sign-in page, and to also make it work smoothly for local development. You'll use `cfaccess` as the provider name. +See [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) for pointers on how to set up the sign-in page and also make it work smoothly for local development. You'll use `cfaccess` as the provider name. -If you [provide a custom sign in resolver](https://backstage.io/docs/auth/identity-resolver#building-custom-resolvers), you can skip the `signIn` block entirely. +If you [provide a custom sign-in resolver](https://backstage.io/docs/auth/identity-resolver#building-custom-resolvers), you can skip the `signIn` block entirely. From dcfe1f2c9c10311202dea28ea6346cd8358e500f Mon Sep 17 00:00:00 2001 From: Aditya Kumar <136452216+AdityaK60@users.noreply.github.com> Date: Thu, 30 Jan 2025 08:58:50 +0530 Subject: [PATCH 5/5] Update provider.md Signed-off-by: Aditya Kumar <136452216+AdityaK60@users.noreply.github.com> --- docs/auth/github/provider.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/auth/github/provider.md b/docs/auth/github/provider.md index c1c3fd253e..51610b36ec 100644 --- a/docs/auth/github/provider.md +++ b/docs/auth/github/provider.md @@ -30,9 +30,9 @@ Settings for local development: GitHub Apps handle OAuth scope at the app installation level, meaning that the `scope` parameter for the call to `getAccessToken` in the frontend has no -effect. When calling `getAccessToken` in open-source plugins, one should still +effect. When calling `getAccessToken` in open source plugins, one should still include the appropriate scope, but also document in the plugin README what -Scopes are required for GitHub Apps. +scopes are required for GitHub Apps. ## Configuration