assign_users_to_groups

Assign users to specific groups in the Okta MCP Server using attribute-based mapping, streamlining group management and organization.

Instructions

Assign multiple users to groups based on attributes

Input Schema

TableJSON Schema

Name	Required	Description	Default
`attributeMapping`	Yes	Mapping of user attributes to group IDs (e.g., {"department": {"Engineering": "group1Id", "Sales": "group2Id"}})
`userIds`	Yes	List of user IDs to assign

Implementation Reference

src/tools/onboarding.ts:290-393 (handler)

The main handler function for the 'assign_users_to_groups' tool. It parses input, fetches user profiles from Okta, matches attributes to group mappings, assigns users to corresponding groups using Okta API, and returns a detailed summary of successes and failures.

  assign_users_to_groups: async (request: { parameters: unknown }) => {
    const { userIds, attributeMapping } = 
      onboardingSchemas.assignUsersToGroups.parse(request.parameters);
    
    try {
      const oktaClient = getOktaClient();
      
      const results = {
        success: [] as any[],
        failed: [] as any[]
      };
      
      // Process each user
      for (const userId of userIds) {
        try {
          // Get user details to access attributes
          const user = await oktaClient.userApi.getUser({ userId });
          
          if (!user || !user.profile) {
            results.failed.push({
              userId: userId,
              reason: 'User not found or profile unavailable'
            });
            continue;
          }
          
          // Determine which groups to assign based on user attributes
          const groupsToAssign = new Set<string>();
          
          // Process attribute mapping
          for (const [attribute, valueMapping] of Object.entries(attributeMapping)) {
            const userAttributeValue = user.profile[attribute as keyof typeof user.profile];
            if (userAttributeValue && valueMapping[userAttributeValue as string]) {
              groupsToAssign.add(valueMapping[userAttributeValue as string]);
            }
          }
          
          // Skip if no groups matched
          if (groupsToAssign.size === 0) {
            results.success.push({
              id: userId,
              email: user.profile.email,
              assignedGroups: [],
              message: 'No group mappings matched user attributes'
            });
            continue;
          }
          
          // Assign user to each mapped group
          const assignedGroups = [];
          for (const groupId of groupsToAssign) {
            await oktaClient.groupApi.assignUserToGroup({
              groupId,
              userId
            });
            assignedGroups.push(groupId);
          }
          
          results.success.push({
            userId: userId,
            email: user.profile.email,
            assignedGroups
          });
        } catch (error) {
          results.failed.push({
            id: userId,
            reason: error instanceof Error ? error.message : String(error)
          });
        }
      }
      
      // Format response
      const summary = `Processed group assignments for ${userIds.length} users:
- Successful assignments: ${results.success.length}
- Failed assignments: ${results.failed.length}

${results.success.length > 0 ? `• Successfully assigned users:
${results.success.map((user, i) => {
  const groupsInfo = user.assignedGroups.length > 0 
    ? `assigned to ${user.assignedGroups.length} groups`
    : user.message || 'no matching groups';
  return `${i+1}. ${user.email || user.userId} (${groupsInfo})`;
}).join('\n')}` : ''}

${results.failed.length > 0 ? `• Failed assignments:
${results.failed.map((user, i) => `${i+1}. User ID: ${user.userId} - ${user.reason}`).join('\n')}` : ''}`;
      
      return {
        content: [{ type: 'text', text: summary }],
        data: results
      };
    } catch (error) {
      console.error("Error during group assignment:", error);
      return {
        content: [
          {
            type: "text",
            text: `Failed to assign users to groups: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  },

src/tools/onboarding.ts:15-20 (schema)

Zod schema used for internal input validation within the handler of the 'assign_users_to_groups' tool.

assignUsersToGroups: z.object({
  userIds: z.array(z.string().min(1, "User ID is required")),
  attributeMapping: z.record(z.record(z.string())).describe(
    "Mapping of user attributes to group IDs (e.g., {\"department\": {\"Engineering\": \"group1Id\"}})"
  ),
}),

src/tools/onboarding.ts:93-110 (registration)

Tool registration object defining the name, description, and input schema for the 'assign_users_to_groups' tool, included in the onboardingTools export which is aggregated into the main TOOLS array.

  name: "assign_users_to_groups",
  description: "Assign multiple users to groups based on attributes",
  inputSchema: {
    type: "object",
    properties: {
      userIds: {
        type: "array",
        items: { type: "string" },
        description: "List of user IDs to assign"
      },
      attributeMapping: {
        type: "object",
        description: "Mapping of user attributes to group IDs (e.g., {\"department\": {\"Engineering\": \"group1Id\", \"Sales\": \"group2Id\"}})"
      }
    },
    required: ["userIds", "attributeMapping"]
  },
},

src/tools/index.ts:6-6 (registration)
Aggregation of all tools including onboardingTools (which contains 'assign_users_to_groups') into the main TOOLS export used by the MCP server.
```
export const TOOLS = [...userTools, ...groupTools, ...onboardingTools];
```
src/tools/index.ts:9-9 (registration)
Aggregation of all handlers including onboardingHandlers (which contains the handler for 'assign_users_to_groups') into the main HANDLERS export used by the MCP server.
```
export const HANDLERS = {
```

Okta MCP Server