Merge branch 'backstage:master' into feat/add-jwks-access-type-1

2024-05-21 10:24:04 -07:00
parent 922bdddcfa 41b942f6dd
commit 28be70312a
961 changed files with 16148 additions and 5554 deletions
@@ -4,10 +4,14 @@ title: Contributing New Providers
 description: Documentation on adding new authentication providers
 ---

-> NOTE: The primary audience for this documentation are contributors to the main
-> Backstage project that want to add support for new authentication providers.
-> While you can follow it to implement your own custom providers it is much
-> more advanced than using our built-in providers.
+:::note Note
+
+The primary audience for this documentation are contributors to the main
+Backstage project that want to add support for new authentication providers.
+While you can follow it to implement your own custom providers it is much
+more advanced than using our built-in providers.
+
+:::

 ## How Does Authentication Work?

@@ -71,7 +71,11 @@ This provider includes several resolvers out of the box that you can use:
 - `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: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+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.

@@ -170,6 +170,5 @@ backend.add(customAuth);
 The body of the sign-in resolver is up to you to write! The example code above
 is just a copy of what `emailMatchingUserEntityProfileEmail` does. The `info`
 parameter contains all of the results of the sign-in attempt so far. The `ctx`
-context [has several useful
-functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/)
+context [has several useful functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/)
 for issuing tokens in various ways.
@@ -43,13 +43,12 @@ auth:
        # enterpriseInstanceUrl: ${AUTH_GITHUB_ENTERPRISE_INSTANCE_URL}
        signIn:
          resolvers:
-            # typically you would pick one of these
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
+            # Matches the GitHub username with the Backstage user entity name.
+            # See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers.
            - resolver: usernameMatchingUserEntityName
 ```

-The GitHub provider is a structure with three configuration keys:
+The GitHub provider is a structure with these configuration keys:

 - `clientId`: The client ID that you generated on GitHub, e.g.
  `b59241722e3c3b4816e2`
@@ -60,6 +59,9 @@ The GitHub provider is a structure with three configuration keys:
  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).
+- `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).

 ### Resolvers

@@ -69,7 +71,11 @@ This provider includes several resolvers out of the box that you can use:
 - `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: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note
+
+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.

@@ -70,7 +70,11 @@ This provider includes several resolvers out of the box that you can use:
 - `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: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+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.

@@ -50,7 +50,11 @@ This provider includes several resolvers out of the box that you can use:
 - `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`.
 - `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `google.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.

-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+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.

@@ -64,7 +64,11 @@ This provider includes several resolvers out of the box that you can use:
 - `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`.
 - `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `google.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.

-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+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.

@@ -5,8 +5,7 @@ description: An introduction to Backstage user identities and sign-in resolvers
 ---

 :::info
-This documentation is written for [the new backend
-system](../backend-system/index.md) which is the default since Backstage
+This documentation is written for [the new backend system](../backend-system/index.md) which is the default since Backstage
 [version 1.24](../releases/v1.24.0.md). If you are still on the old backend
 system, you may want to read [its own article](./identity-resolver--old.md)
 instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
@@ -31,15 +30,13 @@ testing purposes and quickly getting started locally, but is not safe for use in
 production and that particular provider will refuse to work there.

 Because of this, one of the early things you want to do when standing up your
-Backstage instance is to choose a production ready auth provider. See [the auth
-overview page](./index.md) for a full list of providers and how to install and
+Backstage instance is to choose a production ready auth provider. See [the auth overview page](./index.md) for a full list of providers and how to install and
 configure them.

 ## Backstage User Identity

 A user identity within Backstage is built up from two main pieces of
-information: a user [entity
-reference](../features/software-catalog/references.md), and a set of ownership
+information: a user [entity reference](../features/software-catalog/references.md), and a set of ownership
 references. When a user signs in, a Backstage token is generated which is then
 used to identify the user within the Backstage ecosystem.

@@ -194,8 +191,7 @@ backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));
 backend.add(customAuth);
 ```

-Check out [the naming patterns
-article](../backend-system/architecture/07-naming-patterns.md) for what rules
+Check out [the naming patterns article](../backend-system/architecture/07-naming-patterns.md) for what rules
 apply regarding how to form valid IDs. In this example we also put the module
 declaration directly in `packages/backend/src/index.ts` but that's just for
 simplicity. You can place it anywhere you like, including in other packages, and
@@ -244,8 +240,7 @@ async signInResolver(info, ctx) {
 If you throw an error in the sign in resolver function, the sign in attempt is
 immediately rejected, and the error details are presented in the user interface.

-The `ctx` context [has several useful
-functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/)
+The `ctx` context [has several useful functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/)
 for issuing tokens in various ways.

 ### Custom Ownership Resolution
@@ -10,12 +10,16 @@ configure Backstage to have any number of authentication providers, but only
 one of these will typically be used for sign-in, with the rest being used to provide
 access to external resources.

-> NOTE: Identity management and the Sign-In page in Backstage is NOT a method for blocking
-> access for unauthorized users. The identity system only serves to provide a personalized
-> experience and access to a Backstage Identity Token, which can be passed to backend plugins.
-> This also means that your Backstage backend APIs are by default unauthenticated.
-> Thus, if your Backstage instance is exposed to the Internet, anyone can access
-> information in the Backstage. You can learn more [here](../overview/threat-model.md#integrator-responsibilities).
+:::note Note
+
+Identity management and the Sign-In page in Backstage is NOT a method for blocking
+access for unauthorized users. The identity system only serves to provide a personalized
+experience and access to a Backstage Identity Token, which can be passed to backend plugins.
+This also means that your Backstage backend APIs are by default unauthenticated.
+Thus, if your Backstage instance is exposed to the Internet, anyone can access
+information in the Backstage. You can learn more [here](../overview/threat-model.md#integrator-responsibilities).
+
+:::

 ## Built-in Authentication Providers

@@ -141,8 +145,12 @@ const app = createApp({
 });
 ```

-> NOTE: You can configure sign-in to use a redirect flow with no pop-up by adding
-> `enableExperimentalRedirectFlow: true` to the root of your `app-config.yaml`
+:::note Note
+
+You can configure sign-in to use a redirect flow with no pop-up by adding
+`enableExperimentalRedirectFlow: true` to the root of your `app-config.yaml`
+
+:::

 ## Sign-In with Proxy Providers

@@ -84,7 +84,11 @@ This provider includes several resolvers out of the box that you can use:
 - `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`.
 - `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `microsoft.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.

-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+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.

@@ -103,6 +107,5 @@ hosts:
 - `login.microsoftonline.com`, to get and exchange authorization codes and access
  tokens
 - `graph.microsoft.com`, to fetch user profile information (as seen
-  in [this source
-  code](https://github.com/seanfisher/passport-microsoft/blob/0456aa9bce05579c18e77f51330176eb26373658/lib/strategy.js#L93-L95)).
+  in [this source code](https://github.com/seanfisher/passport-microsoft/blob/0456aa9bce05579c18e77f51330176eb26373658/lib/strategy.js#L93-L95)).
  If this host is unreachable, users may see an `Authentication failed, failed to fetch user profile` error when they attempt to log in.
@@ -40,7 +40,11 @@ This provider includes several resolvers out of the box that you can use:
 - `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`.
 - `forwardedUserMatchingUserEntityName`: Matches the value in the `x-forwarded-user` header from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.

-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+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.

@@ -75,7 +75,11 @@ This provider includes several resolvers out of the box that you can use:
 - `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`.
 - `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `okta.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.

-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+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.

@@ -6,8 +6,7 @@ description: This section describes service to service authentication works, bot
 ---

 :::info
-This documentation is written for [the new backend
-system](../backend-system/index.md) which is the default since Backstage
+This documentation is written for [the new backend system](../backend-system/index.md) which is the default since Backstage
 [version 1.24](../releases/v1.24.0.md). If you are still on the old backend
 system, you may want to read [its own article](./service-to-service-auth--old.md)
 instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
@@ -206,8 +205,12 @@ payload:
 - `sub`: the exact string "backstage-server"
 - `exp`: one hour from the time it was generated, in epoch seconds

-> NOTE: The JWT must encode the `alg` header as a protected header, such as with
-> [setProtectedHeader](https://github.com/panva/jose/blob/main/docs/classes/jwt_sign.SignJWT.md#setprotectedheader).
+:::note Note
+
+The JWT must encode the `alg` header as a protected header, such as with
+[setProtectedHeader](https://github.com/panva/jose/blob/main/docs/classes/jwt_sign.SignJWT.md#setprotectedheader).
+
+:::

 The caller then passes along the JWT token with requests in the `Authorization`
 header:
@@ -12,14 +12,11 @@ Cloud Console and within a Backstage app required to enable this capability.
 ## Create an OAuth App in the VMware Cloud Console

 1. Log in to the [VMware Cloud Console](https://console.cloud.vmware.com).
-1. Navigate to [Identity & Access Management > OAuth
-   Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps)
-   and click the [Owned
-   Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps/owned-apps/view)
+1. Navigate to [Identity & Access Management > OAuth Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps)
+   and click the [Owned Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps/owned-apps/view)
   tab -- if you are not an Organization Owner or Administrator but only a
   Member, you will not see this nav entry unless the **Developer** check box is
-   selected for your role (see the [Organization roles and
-   permissions](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-C11D3AAC-267C-4F16-A0E3-3EDF286EBE53.html#organization-roles-and-permissions-0)
+   selected for your role (see the [Organization roles and permissions](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-C11D3AAC-267C-4F16-A0E3-3EDF286EBE53.html#organization-roles-and-permissions-0)
   docs for details).
 1. Click **Create App**, choose 'Web/Mobile app' and click **Continue**.
 1. Use default settings except:
@@ -161,8 +158,7 @@ auth:
 ```

 Where `APP_ID` refers to the ID retrieved when creating the OAuth App, and
-`ORG_ID` is the [long ID of the
-Organization](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-CF9E9318-B811-48CF-8499-9419997DC1F8.html#view-the-organization-id-1)
+`ORG_ID` is the [long ID of the Organization](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-CF9E9318-B811-48CF-8499-9419997DC1F8.html#view-the-organization-id-1)
 in VMware Cloud for which you wish to enable sign-in.

 Note that VMware Cloud requires OAuth Apps to use
@@ -180,6 +176,10 @@ This provider includes several resolvers out of the box that you can use:
 - `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`.
 - `vmwareCloudSignInResolvers`: 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 sign in the user without associating with a catalog user.

-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+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.