Merge branch 'master' into techdocs-common/case-sensitive-migration

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

docs/auth/identity-resolver.md

@@ -111,6 +111,48 @@ export default async function createPlugin({
 ...
 ```
 
+## Resolving membership through the catalog
+
+If you want to provide additional claims through Sign-In resolvers but still
+have the software catalog handle group (and transitive group) membership, you
+can do this using the `CatalogIdentityClient` provided as context to Sign-In
+resolvers:
+
+```ts
+export default async function createPlugin({
+  ...
+}: PluginEnvironment): Promise<Router> {
+  return await createRouter({
+    ...
+    providerFactories: {
+      google: createGoogleProvider({
+        signIn: {
+          resolver: async ({ profile: { email } }, ctx) => {
+            const [sub] = email?.split('@') ?? '';
+            // Fetch from an external system that returns entity claims like:
+            // ['user:default/breanna.davison', ...]
+            const ent = await externalSystemClient.getUsernames(email);
+
+            // Resolve group membership from the Backstage catalog
+            const fullEnt = await ctx.catalogIdentityClient.resolveCatalogMembership({
+              entityRefs: [sub].concat(ent),
+              logger: ctx.logger,
+            });
+            const token = await ctx.tokenIssuer.issueToken({
+              claims: { sub, ent: fullEnt },
+            });
+            return { sub, token };
+          },
+        },
+      }),
+      ...
+```
+
+The `resolveCatalogMembership` method will retrieve the referenced entities from
+the catalog, if possible, and check for
+[memberOf](../features/software-catalog/well-known-relations.md#memberof-and-hasmember)
+relations to add additional entity claims.
+
 ## AuthHandler
 
 Similar to a custom sign-in resolver, you can also write a custom auth handler