add group modification route with protected groups support

Author: devksingh4

src/api/functions/entraId.ts

@@ -1,20 +1,17 @@
 import { genericConfig } from "../../common/config.js";
 import {
+  EntraGroupError,
   EntraInvitationError,
   InternalServerError,
 } from "../../common/errors/index.js";
 import { getSecretValue } from "../plugins/auth.js";
 import { ConfidentialClientApplication } from "@azure/msal-node";
 import { getItemFromCache, insertItemIntoCache } from "./cache.js";
+import {
+  EntraGroupActions,
+  EntraInvitationResponse,
+} from "../../common/types/iam.js";
 
-interface EntraInvitationResponse {
-  status: number;
-  data?: Record<string, string>;
-  error?: {
-    message: string;
-    code?: string;
-  };
-}
 export async function getEntraIdToken(
   clientId: string,
   scopes: string[] = ["https://graph.microsoft.com/.default"],
@@ -76,6 +73,7 @@ export async function getEntraIdToken(
 
 /**
  * Adds a user to the tenant by sending an invitation to their email
+ * @param token - Entra ID token authorized to take this action.
  * @param email - The email address of the user to invite
  * @throws {InternalServerError} If the invitation fails
  * @returns {Promise<boolean>} True if the invitation was successful
@@ -123,3 +121,115 @@ export async function addToTenant(token: string, email: string) {
     });
   }
 }
+
+/**
+ * Resolves an email address to an OID using Microsoft Graph API.
+ * @param token - Entra ID token authorized to perform this action.
+ * @param email - The email address to resolve.
+ * @throws {Error} If the resolution fails.
+ * @returns {Promise<string>} The OID of the user.
+ */
+export async function resolveEmailToOid(
+  token: string,
+  email: string,
+): Promise<string> {
+  email = email.toLowerCase().replace(/\s/g, "");
+
+  const url = `https://graph.microsoft.com/v1.0/users?$filter=mail eq '${email}'`;
+
+  const response = await fetch(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+  });
+
+  if (!response.ok) {
+    const errorData = (await response.json()) as {
+      error?: { message?: string };
+    };
+    throw new Error(errorData?.error?.message ?? response.statusText);
+  }
+
+  const data = (await response.json()) as {
+    value: { id: string }[];
+  };
+
+  if (!data.value || data.value.length === 0) {
+    throw new Error(`No user found with email: ${email}`);
+  }
+
+  return data.value[0].id;
+}
+
+/**
+ * Adds or removes a user from an Entra ID group.
+ * @param token - Entra ID token authorized to take this action.
+ * @param email - The email address of the user to add or remove.
+ * @param group - The group ID to take action on.
+ * @param action - Whether to add or remove the user from the group.
+ * @throws {EntraGroupError} If the group action fails.
+ * @returns {Promise<boolean>} True if the action was successful.
+ */
+export async function modifyGroup(
+  token: string,
+  email: string,
+  group: string,
+  action: EntraGroupActions,
+): Promise<boolean> {
+  email = email.toLowerCase().replace(/\s/g, "");
+  if (!email.endsWith("@illinois.edu")) {
+    throw new EntraGroupError({
+      group,
+      message: "User's domain must be illinois.edu to be added to the group.",
+    });
+  }
+
+  try {
+    const oid = await resolveEmailToOid(token, email);
+    const methodMapper = {
+      [EntraGroupActions.ADD]: "POST",
+      [EntraGroupActions.REMOVE]: "DELETE",
+    };
+
+    const urlMapper = {
+      [EntraGroupActions.ADD]: `https://graph.microsoft.com/v1.0/groups/${group}/members/$ref`,
+      [EntraGroupActions.REMOVE]: `https://graph.microsoft.com/v1.0/groups/${group}/members/${oid}/$ref`,
+    };
+    const url = urlMapper[action];
+    const body = {
+      "@odata.id": `https://graph.microsoft.com/v1.0/directoryObjects/${oid}`,
+    };
+
+    const response = await fetch(url, {
+      method: methodMapper[action],
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const errorData = (await response.json()) as {
+        error?: { message?: string };
+      };
+      throw new EntraGroupError({
+        message: errorData?.error?.message ?? response.statusText,
+        group,
+      });
+    }
+
+    return true;
+  } catch (error) {
+    if (error instanceof EntraGroupError) {
+      throw error;
+    }
+
+    throw new EntraGroupError({
+      message: error instanceof Error ? error.message : String(error),
+      group,
+    });
+  }
+}

src/api/routes/iam.ts

@@ -1,11 +1,16 @@
 import { FastifyPluginAsync } from "fastify";
 import { AppRoles } from "../../common/roles.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
-import { addToTenant, getEntraIdToken } from "../functions/entraId.js";
+import {
+  addToTenant,
+  getEntraIdToken,
+  modifyGroup,
+} from "../functions/entraId.js";
 import {
   BaseError,
   DatabaseFetchError,
   DatabaseInsertError,
+  EntraGroupError,
   EntraInvitationError,
   InternalServerError,
   NotFoundError,
@@ -22,7 +27,10 @@ import {
   invitePostRequestSchema,
   GroupMappingCreatePostRequest,
   groupMappingCreatePostSchema,
-  invitePostResponseSchema,
+  entraActionResponseSchema,
+  groupModificationPatchSchema,
+  GroupModificationPatchRequest,
+  EntraGroupActions,
 } from "../../common/types/iam.js";
 
 const dynamoClient = new DynamoDBClient({
@@ -134,7 +142,7 @@ const iamRoutes: FastifyPluginAsync = async (fastify, _options) => {
     "/inviteUsers",
     {
       schema: {
-        response: { 200: zodToJsonSchema(invitePostResponseSchema) },
+        response: { 200: zodToJsonSchema(entraActionResponseSchema) },
       },
       preValidation: async (request, reply) => {
         await fastify.zodValidateBody(request, reply, invitePostRequestSchema);
@@ -176,6 +184,104 @@ const iamRoutes: FastifyPluginAsync = async (fastify, _options) => {
       reply.status(202).send(response);
     },
   );
+  fastify.patch<{
+    Body: GroupModificationPatchRequest;
+    Querystring: { groupId: string };
+  }>(
+    "/groupMembership/:groupId",
+    {
+      schema: {
+        querystring: {
+          type: "object",
+          properties: {
+            groupId: {
+              type: "string",
+            },
+          },
+        },
+      },
+      preValidation: async (request, reply) => {
+        await fastify.zodValidateBody(
+          request,
+          reply,
+          groupModificationPatchSchema,
+        );
+      },
+      onRequest: async (request, reply) => {
+        await fastify.authorize(request, reply, [AppRoles.IAM_ADMIN]);
+      },
+    },
+    async (request, reply) => {
+      const groupId = (request.params as Record<string, string>).groupId;
+      if (!groupId || groupId === "") {
+        throw new NotFoundError({
+          endpointName: request.url,
+        });
+      }
+      if (genericConfig.ProtectedEntraIDGroups.includes(groupId)) {
+        throw new EntraGroupError({
+          code: 403,
+          message:
+            "This group is protected and may not be modified by this service. You must log into Entra ID directly to modify this group.",
+          group: groupId,
+        });
+      }
+      const entraIdToken = await getEntraIdToken(
+        fastify.environmentConfig.AadValidClientId,
+      );
+      const addResults = await Promise.allSettled(
+        request.body.add.map((email) =>
+          modifyGroup(entraIdToken, email, groupId, EntraGroupActions.ADD),
+        ),
+      );
+      const removeResults = await Promise.allSettled(
+        request.body.remove.map((email) =>
+          modifyGroup(entraIdToken, email, groupId, EntraGroupActions.REMOVE),
+        ),
+      );
+      const response: Record<string, Record<string, string>[]> = {
+        success: [],
+        failure: [],
+      };
+      for (let i = 0; i < addResults.length; i++) {
+        const result = addResults[i];
+        if (result.status === "fulfilled") {
+          response.success.push({ email: request.body.add[i] });
+        } else {
+          if (result.reason instanceof EntraGroupError) {
+            response.failure.push({
+              email: request.body.add[i],
+              message: result.reason.message,
+            });
+          } else {
+            response.failure.push({
+              email: request.body.add[i],
+              message: "An unknown error occurred.",
+            });
+          }
+        }
+      }
+      for (let i = 0; i < removeResults.length; i++) {
+        const result = removeResults[i];
+        if (result.status === "fulfilled") {
+          response.success.push({ email: request.body.remove[i] });
+        } else {
+          if (result.reason instanceof EntraGroupError) {
+            response.failure.push({
+              email: request.body.add[i],
+              message: result.reason.message,
+            });
+          } else {
+            response.failure.push({
+              email: request.body.add[i],
+              message: "An unknown error occurred.",
+            });
+          }
+        }
+      }
+      reply.status(202).send(response);
+    },
+  );
 };
 
 export default iamRoutes;

src/common/config.ts

@@ -30,12 +30,17 @@ type GenericConfigType = {
   TicketMetadataTableName: string;
   MerchStoreMetadataTableName: string;
   IAMTablePrefix: string;
+  ProtectedEntraIDGroups: string[]; // these groups are too privileged to be modified via this portal and must be modified directly in Entra ID.
 };
 
 type EnvironmentConfigType = {
   [env in RunEnvironment]: ConfigType;
 };
 
+export const infraChairsGroupId = "48591dbc-cdcb-4544-9f63-e6b92b067e33";
+export const officersGroupId = "ff49e948-4587-416b-8224-65147540d5fc";
+export const execCouncilGroupId = "ad81254b-4eeb-4c96-8191-3acdce9194b1";
+
 const genericConfig: GenericConfigType = {
   EventsDynamoTableName: "infra-core-api-events",
   CacheDynamoTableName: "infra-core-api-cache",
@@ -48,12 +53,13 @@ const genericConfig: GenericConfigType = {
   TicketPurchasesTableName: "infra-events-tickets",
   TicketMetadataTableName: "infra-events-ticketing-metadata",
   IAMTablePrefix: "infra-core-api-iam",
+  ProtectedEntraIDGroups: [infraChairsGroupId, officersGroupId],
 } as const;
 
 const environmentConfig: EnvironmentConfigType = {
   dev: {
     GroupRoleMapping: {
-      "48591dbc-cdcb-4544-9f63-e6b92b067e33": allAppRoles, // Infra Chairs
+      [infraChairsGroupId]: allAppRoles, // Infra Chairs
       "940e4f9e-6891-4e28-9e29-148798495cdb": allAppRoles, // ACM Infra Team
       "f8dfc4cf-456b-4da3-9053-f7fdeda5d5d6": allAppRoles, // Infra Leads
       "0": allAppRoles, // Dummy Group for development only
@@ -76,12 +82,9 @@ const environmentConfig: EnvironmentConfigType = {
   },
   prod: {
     GroupRoleMapping: {
-      "48591dbc-cdcb-4544-9f63-e6b92b067e33": allAppRoles, // Infra Chairs
-      "ff49e948-4587-416b-8224-65147540d5fc": allAppRoles, // Officers
-      "ad81254b-4eeb-4c96-8191-3acdce9194b1": [
-        AppRoles.EVENTS_MANAGER,
-        AppRoles.IAM_INVITE_ONLY,
-      ], // Exec
+      [infraChairsGroupId]: allAppRoles, // Infra Chairs
+      [officersGroupId]: allAppRoles, // Officers
+      [execCouncilGroupId]: [AppRoles.EVENTS_MANAGER, AppRoles.IAM_INVITE_ONLY], // Exec
     },
     UserRoleMapping: {
       "[email protected]": allAppRoles,

src/common/errors/index.ts

@@ -179,3 +179,25 @@ export class NotSupportedError extends BaseError<"NotSupportedError"> {
     });
   }
 }
+
+export class EntraGroupError extends BaseError<"EntraGroupError"> {
+  group: string;
+  constructor({
+    code,
+    message,
+    group,
+  }: {
+    code?: number;
+    message?: string;
+    group: string;
+  }) {
+    super({
+      name: "EntraGroupError",
+      id: 308,
+      message:
+        message || `Could not modify the group membership for group ${group}.`,
+      httpStatusCode: code || 500,
+    });
+    this.group = group;
+  }
+}