auth-backend: move getDefaultOwnershipEntityRefs to resolver context

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/four-readers-vanish.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-node': patch
+---
+
+Added `AuthResolverContext.resolveOwnershipEntityRefs` as a way of accessing the default ownership resolution logic in sign-in resolvers, replacing `getDefaultOwnershipEntityRefs` from `@backstage/plugin-auth-backend`.

.changeset/silver-fishes-shop.md

@@ -0,0 +1,23 @@
+---
+'@backstage/plugin-auth-backend': patch
+---
+
+Deprecated `getDefaultOwnershipEntityRefs` in favor of the new `.resolveOwnershipEntityRefs(...)` method in the `AuthResolverContext`.
+
+The following code in a custom sign-in resolver:
+
+```ts
+import { getDefaultOwnershipEntityRefs } from '@backstage/plugin-auth-backend';
+
+// ...
+
+const ent = getDefaultOwnershipEntityRefs(entity);
+```
+
+Can be replaced with the following:
+
+```ts
+const { ownershipEntityRefs: ent } = await ctx.resolveOwnershipEntityRefs(
+  entity,
+);
+```

docs/auth/identity-resolver.md

@@ -298,10 +298,9 @@ of lower-level calls:
 
 ```ts
 // File: packages/backend/src/plugins/auth.ts
-import { getDefaultOwnershipEntityRefs } from '@backstage/plugin-auth-backend';
 
 // ...
-async signInResolver({ profile: { email} }, ctx) {
+async signInResolver({ profile: { email } }, ctx) {
   if (!email) {
     throw new Error('User profile contained no email');
   }
@@ -323,19 +322,19 @@ async signInResolver({ profile: { email} }, ctx) {
   //
   // You might also replace it if you for example want to filter out certain groups.
   //
-  // Note that `getDefaultOwnershipEntityRefs` only includes groups to which the
-  // user has a direct MEMBER_OF relationship. It's perfectly fine to include
-  // groups that the user is transitively part of in the claims array, but the
-  // catalog doesn't currently provide a direct way of accessing this list of
-  // groups.
-  const ownershipRefs = getDefaultOwnershipEntityRefs(entity);
+  // Note that `ctx.resolveOwnershipEntityRefs(...)` by default only includes groups
+  // to which the user has a direct MEMBER_OF relationship.
+  // It's perfectly fine to include groups that the user is transitively part of
+  // in the claims array, but the catalog doesn't currently provide a direct
+  // way of accessing this list of groups.
+  const { ownershipEntityRefs } = await ctx.resolveOwnershipEntityRefs(entity);
 
   // The last step is to issue the token, where we might provide more options in the
   // future.
   return ctx.issueToken({
     claims: {
       sub: stringifyEntityRef(entity),
-      ent: ownershipRefs,
+      ent: ownershipEntityRefs,
     },
   });
 }

plugins/auth-backend-module-vmware-cloud-provider/src/authenticator.test.ts

@@ -235,6 +235,7 @@ describe('vmwareCloudAuthenticator', () => {
         signInWithCatalogUser: jest.fn().mockResolvedValue({
           token: 'backstageToken',
         }),
+        resolveOwnershipEntityRefs: jest.fn(),
       };
 
       oAuthState = {
@@ -432,6 +433,7 @@ describe('vmwareCloudAuthenticator', () => {
         signInWithCatalogUser: jest.fn().mockResolvedValue({
           token: 'backstageToken',
         }),
+        resolveOwnershipEntityRefs: jest.fn(),
       };
 
       refreshRequest = {

plugins/auth-backend/report.api.md

@@ -216,7 +216,7 @@ export type GcpIapResult = GcpIapResult_2;
 // @public @deprecated
 export type GcpIapTokenInfo = GcpIapTokenInfo_2;
 
-// @public
+// @public @deprecated
 export function getDefaultOwnershipEntityRefs(entity: Entity): string[];
 
 // @public (undocumented)

plugins/auth-backend/src/lib/resolvers/CatalogAuthResolverContext.ts

@@ -46,6 +46,7 @@ import { CatalogIdentityClient } from '../catalog';
  * A reference to the entity itself will also be included in the returned array.
  *
  * @public
+ * @deprecated use `ctx.resolveOwnershipEntityRefs(entity)` from the provided `AuthResolverContext` instead.
  */
 export function getDefaultOwnershipEntityRefs(entity: Entity) {
   const membershipRefs =
@@ -164,21 +165,26 @@ export class CatalogAuthResolverContext implements AuthResolverContext {
 
   async signInWithCatalogUser(query: AuthResolverCatalogUserQuery) {
     const { entity } = await this.findCatalogUser(query);
-    let ent: string[];
-    if (this.ownershipResolver) {
-      const { ownershipEntityRefs } =
-        await this.ownershipResolver.resolveOwnershipEntityRefs(entity);
-      ent = ownershipEntityRefs;
-    } else {
-      ent = getDefaultOwnershipEntityRefs(entity);
-    }
+
+    const { ownershipEntityRefs } = await this.resolveOwnershipEntityRefs(
+      entity,
+    );
 
     const token = await this.tokenIssuer.issueToken({
       claims: {
         sub: stringifyEntityRef(entity),
-        ent,
+        ent: ownershipEntityRefs,
       },
     });
     return { token };
   }
+
+  async resolveOwnershipEntityRefs(
+    entity: Entity,
+  ): Promise<{ ownershipEntityRefs: string[] }> {
+    if (this.ownershipResolver) {
+      return this.ownershipResolver.resolveOwnershipEntityRefs(entity);
+    }
+    return { ownershipEntityRefs: getDefaultOwnershipEntityRefs(entity) };
+  }
 }

plugins/auth-backend/src/providers/oidc/provider.test.ts

@@ -119,6 +119,7 @@ describe('oidc.create', () => {
         issueToken: jest.fn(),
         findCatalogUser: jest.fn(),
         signInWithCatalogUser: jest.fn(),
+        resolveOwnershipEntityRefs: jest.fn(),
       },
     };
   });

plugins/auth-node/report.api.md

@@ -113,6 +113,9 @@ export type AuthResolverContext = {
   signInWithCatalogUser(
     query: AuthResolverCatalogUserQuery,
   ): Promise<BackstageSignInResult>;
+  resolveOwnershipEntityRefs(entity: Entity): Promise<{
+    ownershipEntityRefs: string[];
+  }>;
 };
 
 // @public

plugins/auth-node/src/types.ts

@@ -161,6 +161,14 @@ export type AuthResolverContext = {
   signInWithCatalogUser(
     query: AuthResolverCatalogUserQuery,
   ): Promise<BackstageSignInResult>;
+
+  /**
+   * Resolves the ownership entity references for the provided entity.
+   * This will use the `AuthOwnershipResolver` if one is installed, and otherwise fall back to the default resolution logic.
+   */
+  resolveOwnershipEntityRefs(
+    entity: Entity,
+  ): Promise<{ ownershipEntityRefs: string[] }>;
 };
 
 /**