AI导哈

PIM角色激活工具

Azure PIM角色激活库和MCP服务器，支持通过编程或自然语言激活角色，并可保存常用角色为一键激活。

  • by Harley-Adams
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Harley-Adams/PIM-Me

使用说明

PIM我

Azure PIM角色激活库和MCP服务器。通过编程或自然语言与您的AI助手激活角色。将常用角色另存为收藏夹，并使用一个命令全部激活。

快速开始

先决条件

  • Node.js 18+
  • Azure CLI已安装并登录(az login)
  • 具有PIM资格角色的Azure帐户

作为MCP服务器

添加到您的MCP客户端：

VS Code (.vscode/mcp.json):

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

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json):

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

作为图书馆

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服务器使用情况

设置快速角色

使用此工具的最简单方法是设置一次常用角色：

  1. 问：“显示我的PIM角色”或“帮助我设置快速角色”
  2. 选择角色 从编号列表中：“将角色20、21、22另存为我的快速角色”
  3. 设置默认对齐方式 （可选）：包括 defaultJustification: "Development work" 保存时

您的配置已保存到 ~/.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"
  }
}

日常使用

配置后，只需说：

  • “激活我的快速角色” --使用默认理由
  • “激活我的快速角色以调试生产问题” --自定义理由
  • “列出我符合条件的角色” --查看您可以激活的所有角色
  • “列出我的活动角色” --查看当前提升的角色及其过期时间
  • “激活我的订阅的参与者角色” --激活特定角色

可用工具（MCP）

工具 说明
list_eligible_roles 列出您可以激活的所有PIM角色
list_active_roles 列出当前提升的角色及其过期时间
list_quick_roles 使用索引显示符合条件的角色+您保存的快速角色
save_quick_roles 将所选角色（按索引）保存为快速角色
activate_quick_roles 激活您保存的快速角色
activate_pim_roles 按名称激活特定角色

库API

核心功能

功能 说明
listEligibleRoles() 返回您可以激活的所有PIM角色
listActiveRoles() 返回当前提升的角色及其过期时间
activateRoles(roles, justification, hours) 激活特定角色
activateQuickRoles(justification?, hours?) 激活您保存的收藏夹

配置功能

功能 说明
loadQuickRolesConfig() 从配置文件或环境中加载快速角色
saveQuickRolesConfig(roles, desc?, justification?) 将快速角色保存到配置
getConfigPath() 返回路径 ~/.pim-me-mcp.json

类型

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

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

运作原理

此MCP服务器使用Azure CLI与Azure PIM REST API进行交互：

  1. 列出符合条件的角色 通过 roleEligibilityScheduleInstances API
  2. 列出活动角色 通过 roleAssignmentScheduleInstances API（过滤至 assignmentType=Activated)
  3. 激活角色 通过 roleAssignmentScheduleRequests API SelfActivate 请求类型

API版本: 2020-10-01

棘手的实施细节

🔑 基于组的角色分配

Azure PIM自动化最棘手的部分是处理 基于组的角色分配当一个角色被分配给一个组（而不是直接分配给用户）时，激活需要特殊的处理。

问题1：主体ID错误

症状: "InsufficientPermissions" 或 "The assignee cannot be found"

原因：The roleEligibilityScheduleInstances API返回 群的 主体ID，但激活API需要 用户的 主体ID。

解决方案：从Azure访问令牌JWT中提取用户的OID：

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
}

问题2：缺少链接计划ID

症状：即使主体ID正确，基于组的角色的激活也会失败

解决方案：对于基于小组的作业，包括 linkedRoleEligibilityScheduleId 在请求正文中。这将激活链接回组的资格计划。

📦 激活请求正文

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

备注: linkedRoleEligibilityScheduleId 对于基于组的作业是必需的，对于直接作业是可选的。

⚠️ 错误处理

错误代码 含义 解决方案
RoleAssignmentExists 角色已激活 视为成功✅
InsufficientPermissions 主体ID错误 使用用户的OID，而不是组的OID
The assignee cannot be found 主体ID不匹配 从访问令牌中提取OID

📋 api参考

端点 方法 目的
/providers/Microsoft.Authorization/roleEligibilityScheduleInstances?$filter=asTarget() GET 列出符合条件的角色
/providers/Microsoft.Authorization/roleAssignmentScheduleInstances?$filter=asTarget() GET 列出活动角色
/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{guid} PUT 激活角色

故障排除

问题 解决方案
“找不到命令‘az’” 安装Azure命令行界面
“请运行‘az登录’” 运行 az login 进行身份验证
找不到角色 使用 list_eligible_roles 查看确切的角色名称和作用域

许可证

麻省理工学院

相关 MCP