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
@@ -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