Added dedicated resolvers section

Signed-off-by: Andre Wanlin <awanlin@spotify.com>
2024-04-16 11:03:28 -05:00
parent a874dd1524
commit 8383e2ca7d
9 changed files with 105 additions and 55 deletions
@@ -54,8 +54,6 @@ auth:
            - resolver: usernameMatchingUserEntityName
 ```

-> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
-
 The Atlassian provider is a structure with three configuration keys:

 - `clientId`: The Key you generated in the developer console.
@@ -64,6 +62,18 @@ The Atlassian provider is a structure with three configuration keys:

 **NOTE:** the scopes `offline_access`, `read:jira-work`, and `read:jira-user` are provided by default.

+### Resolvers
+
+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`.
+
+> 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.
+
 ## Adding the provider to the Backstage frontend

 To add the provider to the frontend, add the `atlassianAuthApi` reference and
@@ -48,8 +48,6 @@ auth:
            - resolver: usernameMatchingUserEntityName
 ```

-> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
-
 The GitHub provider is a structure with three configuration keys:

 - `clientId`: The client ID that you generated on GitHub, e.g.
@@ -62,6 +60,18 @@ The GitHub provider is a structure with three configuration keys:
  `https://your-intermediate-service.com/handler`. Only needed if Backstage is
  not the immediate receiver (e.g. one OAuth app for many backstage instances).

+### Resolvers
+
+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`.
+
+> 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.
+
 ## Adding the provider to the Backstage frontend

 To add the provider to the frontend, add the `githubAuthApi` reference and
@@ -50,8 +50,6 @@ auth:
            - resolver: usernameMatchingUserEntityName
 ```

-> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
-
 The GitLab provider is a structure with three configuration keys:

 - `clientId`: The Application ID that you generated on GitLab, e.g.
@@ -63,6 +61,18 @@ The GitLab provider is a structure with three configuration keys:
  `https://$backstage.acme.corp/api/auth/gitlab/handler/frame`
  Note: Due to a peculiarity with GitLab OAuth, ensure there is no trailing `/` after 'frame' in the URL.

+### Resolvers
+
+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`.
+
+> 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.
+
 ## Adding the provider to the Backstage frontend

 To add the provider to the frontend, add the `gitlabAuthApi` reference and
@@ -34,8 +34,6 @@ auth:
          - resolver: emailMatchingUserEntityAnnotation
 ```

-> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
-
 The full `audience` value can be obtained by visiting your [Identity-Aware Proxy Google Cloud console](https://console.cloud.google.com/security/iap), selecting your project, finding your Backend Service to proxy, clicking the 3 vertical dots then "Get JWT Audience Code", and copying from the resulting popup, which will look similar to the following:

 ![Identity-Aware Proxy JWT Audience Code popup](../../assets/auth/gcp-iap-jwt-audience-code-popup.png)
@@ -43,6 +41,18 @@ The full `audience` value can be obtained by visiting your [Identity-Aware Proxy
 This config section must be in place for the provider to load at all. Now let's
 add the provider itself.

+### Resolvers
+
+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`.
+- `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`.
+
+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 Changes

 This provider is not enabled by default in the auth backend code, because
@@ -49,14 +49,24 @@ auth:
            - resolver: emailMatchingUserEntityAnnotation
 ```

-> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
-
 The Google provider is a structure with two configuration keys:

 - `clientId`: The client ID that you generated, e.g.
  `10023341500512-beui241gjwwkrdkr2eh7dprewj2pp1q.apps.googleusercontent.com`
 - `clientSecret`: The client secret tied to the generated client ID.

+### Resolvers
+
+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`.
+- `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`.
+
+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.
+
 ## Adding the provider to the Backstage frontend

 To add the provider to the frontend, add the `googleAuthApi` reference and
@@ -64,8 +64,6 @@ auth:
            - resolver: emailMatchingUserEntityAnnotation
 ```

-> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
-
 The Microsoft provider is a structure with three mandatory configuration keys:

 - `clientId`: Application (client) ID, found on App Registration > Overview
@@ -77,6 +75,18 @@ The Microsoft provider is a structure with three mandatory configuration keys:
  For more details, see [Home Realm Discovery](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/home-realm-discovery-policy)
 - `additionalScopes` (optional): List of scopes for the App Registration. The default and mandatory value is ['user.read'].

+### Resolvers
+
+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`.
+- `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`.
+
+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.
+
 ## Adding the provider to the Backstage frontend

 To add the provider to the frontend, add the `microsoftAuthApiRef` reference and
@@ -31,43 +31,17 @@ auth:
            - resolver: forwardedUserMatchingUserEntityName
 ```

-> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+### Resolvers

-Right now no configuration options are supported, but the empty object is needed
-to enable the provider in the auth backend.
+This provider includes several resolvers out of the box that you can use:

-To use the `oauth2Proxy` provider you must also configure it with a sign-in resolver.
-For more information about the sign-in process in general, see the
-[Sign-in Identities and Resolvers](../identity-resolver.md) documentation.
+- `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`.
+- `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`.

-For the `oauth2Proxy` provider, the sign-in result is quite different than other providers.
-Because it's a proxy provider that can be configured to forward information through
-arbitrary headers, the auth result simply just gives you access to the HTTP headers
-of the incoming request. Using these you can either extract the information directly,
-or grab ID or access tokens to look up additional information and/or validate the request.
+> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.

-A simple sign-in resolver might for example look like this:
-
-```ts
-providerFactories: {
-  ...defaultAuthProviderFactories,
-  oauth2Proxy: providers.oauth2Proxy.create({
-    signIn: {
-      async resolver({ result }, ctx) {
-        const name = result.getHeader('x-forwarded-user');
-        if (!name) {
-          throw new Error('Request did not contain a user')
-        }
-        return ctx.signInWithCatalogUser({
-          entityRef: { name },
-        });
-      },
-    },
-  }),
-},
-```
-
-[An example on how to sign a user in without a matching user](https://github.com/backstage/backstage/blob/master/packages/backend/src/plugins/auth.ts)
+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.

 ## Adding the provider to the Backstage frontend

@@ -29,7 +29,7 @@ To add Okta authentication, you must create an Application from Okta:

 The configuration examples provided above are suitable for local development. For a production deployment, substitute `http://localhost:7007` with the url that your Backstage instance is available at.

-# Configuration
+## Configuration

 The provider configuration can then be added to your `app-config.yaml` under the
 root `auth` configuration:
@@ -54,8 +54,6 @@ auth:
            - resolver: emailMatchingUserEntityAnnotation
 ```

-> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
-
 The values referenced are found on the Application page on your Okta site.

 - `clientId`: The client ID that you generated on Okta, e.g.
@@ -68,6 +66,18 @@ The values referenced are found on the Application page on your Okta site.

 `additionalScopes` is an optional value, a string of space separated scopes, that will be combined with the default `scope` value of `openid profile email offline_access` to adjust the `scope` sent to Okta during OAuth. This will have an impact on [the dependent claims returned](https://developer.okta.com/docs/reference/api/oidc/#scope-dependent-claims-not-always-returned). For example, setting the `additionalScopes` value to `groups` will result in the claim returning a list of the groups that the user is a member of that also match the ID token group filter of the client app.

+### Resolvers
+
+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`.
+- `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`.
+
+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.
+
 ## Adding the provider to the Backstage frontend

 To add the provider to the frontend, add the `oktaAuthApi` reference and
@@ -107,10 +107,6 @@ export default async function createPlugin(
 In the above, `commonSignInResolvers.emailLocalPartMatchingUserEntityName()`
 can be replaced with a more suitable resolver for the app in question.

-## Configure Sign-in Resolution
-
-See [Sign-in Identities and Resolvers](../identity-resolver.md) for details.
-
 ## Add to Sign-in Page

 See the [Sign-In Configuration](../index.md#sign-in-configuration) docs for
@@ -163,9 +159,7 @@ auth:
            - resolver: vmwareCloudSignInResolvers
 ```

-> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
-
-where `APP_ID` refers to the ID retrieved when creating the OAuth App, and
+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)
 in VMware Cloud for which you wish to enable sign-in.
@@ -176,3 +170,15 @@ library used by this provider requires the use of Express session middleware to
 do this. Therefore the value `your session secret` under `auth.session.secret`
 should be replaced with a long, complex and unique string which will act as a
 key for signing session cookies set by Backstage.
+
+### Resolvers
+
+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`.
+- `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`.
+
+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.