PIM Me

Azure PIM role activation library and MCP server. Activate roles programmatically or through natural language with your AI assistant. Save your frequently-used roles as favorites and activate them all with a single command.

Quick Start

Prerequisites

• Node.js 18+
• Azure CLI installed and logged in (az login)
• Azure account with PIM-eligible roles

As an MCP Server

Add to your MCP client:

VS Code (.vscode/mcp.json):

{
  "servers": {
    "pim-me": {
      "command": "npx",
      "args": ["-y", "pim-me-mcp"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "pim-me": {
      "command": "npx",
      "args": ["-y", "pim-me-mcp"]
    }
  }
}

As a Library

npm install pim-me-mcp

import { 
  listEligibleRoles, 
  listActiveRoles, 
  activateRoles,
  activateQuickRoles 
} from 'pim-me-mcp';

// List all roles you can activate
const eligible = await listEligibleRoles();
console.log(eligible.roles);

// Check what's currently elevated
const active = await listActiveRoles();
active.roles.forEach(role => {
  console.log(`${role.roleName} expires at ${role.endDateTime}`);
});

// Activate specific roles
const result = await activateRoles(
  [{ name: 'Contributor', scope: 'my-subscription' }],
  'Development work',
  8 // hours
);

// Or activate your saved favorites
const quickResult = await activateQuickRoles('Development work');

MCP Server Usage

Setting Up Quick Roles

The easiest way to use this tool is to set up your frequently-used roles once:

1. Ask: "Show me my PIM roles" or "Help me set up my quick roles"
2. Pick roles from the numbered list: "Save roles 20, 21, 22 as my quick roles"
3. Set a default justification (optional): Include defaultJustification: "Development work" when saving

Your configuration is saved to ~/.pim-me-mcp.json:

{
  "quickRoles": {
    "roles": [
      { "name": "Owner", "scope": "my-resource-group" },
      { "name": "Contributor", "scope": "my-subscription" }
    ],
    "description": "My daily development roles",
    "defaultJustification": "Development work"
  }
}

Daily Usage

Once configured, just say:

• "Activate my quick roles" — uses your default justification
• "Activate my quick roles for debugging production issue" — custom justification
• "List my eligible roles" — see all roles you can activate
• "List my active roles" — see currently elevated roles with expiration times
• "Activate the Contributor role for my-subscription" — activate specific roles

Available Tools (MCP)

| Tool | Description | |------|-------------| | list_eligible_roles | Lists all PIM roles you can activate | | list_active_roles | Lists currently elevated roles with expiration times | | list_quick_roles | Shows eligible roles with indices + your saved quick roles | | save_quick_roles | Saves selected roles (by index) as quick roles | | activate_quick_roles | Activates your saved quick roles | | activate_pim_roles | Activates specific roles by name |

Library API

Core Functions

| Function | Description | |----------|-------------| | listEligibleRoles() | Returns all PIM roles you can activate | | listActiveRoles() | Returns currently elevated roles with expiration times | | activateRoles(roles, justification, hours) | Activates specific roles | | activateQuickRoles(justification?, hours?) | Activates your saved favorites |

Configuration Functions

| Function | Description | |----------|-------------| | loadQuickRolesConfig() | Loads quick roles from config file or env | | saveQuickRolesConfig(roles, desc?, justification?) | Saves quick roles to config | | getConfigPath() | Returns path to ~/.pim-me-mcp.json |

Types

interface RoleConfig {
  name: string;   // e.g., "Contributor"
  scope: string;  // e.g., "my-subscription"
}

interface QuickRolesConfig {
  roles: RoleConfig[];
  description?: string;
  defaultJustification?: string;
}

How It Works

This MCP server uses the Azure CLI to interact with the Azure PIM REST API:

1. Lists eligible roles via roleEligibilityScheduleInstances API
2. Lists active roles via roleAssignmentScheduleInstances API (filtered to assignmentType=Activated)
3. Activates roles via roleAssignmentScheduleRequests API with SelfActivate request type

API Version: 2020-10-01

Tricky Implementation Details

🔑 Group-Based Role Assignments

The trickiest part of Azure PIM automation is handling group-based role assignments. When a role is assigned to a group (rather than directly to a user), activation requires special handling.

Problem 1: Wrong Principal ID

Symptom: "InsufficientPermissions" or "The assignee cannot be found"

Cause: The roleEligibilityScheduleInstances API returns the group's principal ID, but the activation API needs the user's principal ID.

Solution: Extract the user's OID from the Azure access token JWT:

async function getCurrentUserPrincipalId(): Promise<string> {
  const tokenResult = await azCommand(
    "account get-access-token --resource https://management.azure.com"
  );
  const tokenData = JSON.parse(tokenResult);
  
  // Decode JWT payload (base64)
  const payload = JSON.parse(
    Buffer.from(tokenData.accessToken.split('.')[1], 'base64').toString()
  );
  
  return payload.oid;  // The user's Azure AD Object ID
}

Problem 2: Missing Linked Schedule ID

Symptom: Activation fails for group-based roles even with correct principal ID

Solution: For group-based assignments, include linkedRoleEligibilityScheduleId in the request body. This links the activation back to the group's eligibility schedule.

📦 Activation Request Body

{
  "properties": {
    "principalId": "<user-oid>",
    "roleDefinitionId": "<role-definition-id>",
    "requestType": "SelfActivate",
    "justification": "<business-justification>",
    "scheduleInfo": {
      "expiration": {
        "type": "AfterDuration",
        "duration": "PT8H"
      }
    },
    "linkedRoleEligibilityScheduleId": "<eligibility-schedule-id>"
  }
}

Note: linkedRoleEligibilityScheduleId is required for group-based assignments, optional for direct assignments.

⚠️ Error Handling

| Error Code | Meaning | Solution | |------------|---------|----------| | RoleAssignmentExists | Role already activated | Treat as success ✅ | | InsufficientPermissions | Wrong principal ID | Use user's OID, not group's | | The assignee cannot be found | Principal ID mismatch | Extract OID from access token |

📋 API Reference

| Endpoint | Method | Purpose | |----------|--------|---------| | /providers/Microsoft.Authorization/roleEligibilityScheduleInstances?$filter=asTarget() | GET | List eligible roles | | /providers/Microsoft.Authorization/roleAssignmentScheduleInstances?$filter=asTarget() | GET | List active roles | | /{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{guid} | PUT | Activate a role |

Troubleshooting

| Issue | Solution | |-------|----------| | "Command 'az' not found" | Install Azure CLI | | "Please run 'az login'" | Run az login to authenticate | | Role not found | Use list_eligible_roles to see exact role names and scopes |

License

MIT