Merge pull request #10902 from Bonial-International-GmbH/PJ_msgraph_email-annotation

feat: add annotation `microsoft.com/email` when using the `defaultUserTransformer`

.changeset/giant-cheetahs-thank.md

@@ -0,0 +1,30 @@
+---
+'@backstage/plugin-catalog-backend-module-msgraph': patch
+---
+
+Add annotation `microsoft.com/email` when using the `defaultUserTransformer`.
+
+This will allow users of the Microsoft auth provider to utilize the predefined
+SignIn resolver instead of maintaining their own.
+
+```typescript
+// backend/plugins/auth.ts
+
+// [...]
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  return await createRouter({
+    // [...]
+    providerFactories: {
+      microsoft: providers.microsoft.create({
+        signIn: {
+          resolver:
+            providers.microsoft.resolvers.emailMatchingUserEntityAnnotation(),
+        },
+      }),
+    },
+  });
+}
+```

plugins/catalog-backend-module-msgraph/api-report.md

@@ -49,6 +49,9 @@ export type GroupTransformer = (
   groupPhoto?: string,
 ) => Promise<GroupEntity | undefined>;
 
+// @public
+export const MICROSOFT_EMAIL_ANNOTATION = 'microsoft.com/email';
+
 // @public
 export const MICROSOFT_GRAPH_GROUP_ID_ANNOTATION =
   'graph.microsoft.com/group-id';

plugins/catalog-backend-module-msgraph/src/microsoftGraph/constants.ts

@@ -14,6 +14,13 @@
  * limitations under the License.
  */
 
+/**
+ * The (primary) user email. Also used by the Microsoft auth provider to resolve the User entity.
+ *
+ * @public
+ */
+export const MICROSOFT_EMAIL_ANNOTATION = 'microsoft.com/email';
+
 /**
  * The tenant id used by the Microsoft Graph API
  *

plugins/catalog-backend-module-msgraph/src/microsoftGraph/index.ts

@@ -19,6 +19,7 @@ export type { GroupMember, ODataQuery } from './client';
 export { readMicrosoftGraphConfig } from './config';
 export type { MicrosoftGraphProviderConfig } from './config';
 export {
+  MICROSOFT_EMAIL_ANNOTATION,
   MICROSOFT_GRAPH_GROUP_ID_ANNOTATION,
   MICROSOFT_GRAPH_TENANT_ID_ANNOTATION,
   MICROSOFT_GRAPH_USER_ID_ANNOTATION,

plugins/catalog-backend-module-msgraph/src/microsoftGraph/read.test.ts

@@ -96,6 +96,7 @@ describe('read microsoft graph', () => {
           metadata: {
             annotations: {
               'graph.microsoft.com/user-id': 'userid',
+              'microsoft.com/email': 'user.name@example.com',
             },
             name: 'user.name_example.com',
           },
@@ -146,6 +147,7 @@ describe('read microsoft graph', () => {
           metadata: {
             annotations: {
               'graph.microsoft.com/user-id': 'userid',
+              'microsoft.com/email': 'user.name@example.com',
             },
             name: 'user.name_example.com',
           },
@@ -263,6 +265,7 @@ describe('read microsoft graph', () => {
           metadata: {
             annotations: {
               'graph.microsoft.com/user-id': 'userid',
+              'microsoft.com/email': 'user.name@example.com',
             },
             name: 'user.name_example.com',
           },
@@ -339,6 +342,7 @@ describe('read microsoft graph', () => {
           metadata: {
             annotations: {
               'graph.microsoft.com/user-id': 'userid',
+              'microsoft.com/email': 'user.name@example.com',
             },
             name: 'user.name_example.com',
           },

plugins/catalog-backend-module-msgraph/src/microsoftGraph/read.ts

@@ -24,6 +24,7 @@ import limiterFactory from 'p-limit';
 import { Logger } from 'winston';
 import { MicrosoftGraphClient } from './client';
 import {
+  MICROSOFT_EMAIL_ANNOTATION,
   MICROSOFT_GRAPH_GROUP_ID_ANNOTATION,
   MICROSOFT_GRAPH_TENANT_ID_ANNOTATION,
   MICROSOFT_GRAPH_USER_ID_ANNOTATION,
@@ -57,6 +58,7 @@ export async function defaultUserTransformer(
     metadata: {
       name,
       annotations: {
+        [MICROSOFT_EMAIL_ANNOTATION]: user.mail!,
         [MICROSOFT_GRAPH_USER_ID_ANNOTATION]: user.id!,
       },
     },