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)

Library API

Core Functions

Configuration Functions

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

📋 API Reference

Troubleshooting

License

MIT