# Azure Rbac Role Matching

> Recommend the least-privilege Azure built-in RBAC roles for one or more requested operations. Use this whenever users ask what role to assign, how to minimize Azure permissions, or which built-in role is the smallest safe match for a service principal, managed identity, app, or operator workflow.

- Skill: `kdcllc/azure-rbac-role-matching` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add kdcllc/azure-rbac-role-matching`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kdcllc/azure-rbac-role-matching/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: kdcllc (https://skillmd.com/u/kdcllc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kdcllc/azure-rbac-role-matching

---


## Use When

Use this skill when you need least-privilege **built-in** Azure RBAC role candidates from a set of requested operations and can work from checked-in snapshot data.

- Find the smallest built-in role that covers one or more exact operations.
- Validate or compare least-privilege role recommendations before assignment.
- Recommend role candidates for service principals, managed identities, automation, or CI/CD jobs.
- Explain why a broad role appears and surface smaller non-privileged alternatives first.

## Do Not Use When

- You need custom role JSON generation.
- You need live scope reasoning (resource group vs subscription), PIM, ABAC, or deny assignment analysis.
- You need runtime authorization validation against Azure APIs.

## Inputs

- one or more Azure permission strings, such as `Microsoft.Support/services/read`

## Workflow

1. Load `references/data/roles-extended.json` and `references/data/permissions.json`.
2. Evaluate each requested permission with wildcard allow/deny logic:
   - `actions`
   - `notActions`
   - `dataActions`
   - `notDataActions`
3. Use the permission metadata to keep control-plane and data-plane checks separate.
4. Keep only roles that grant **every** requested permission.
5. Rank matches by `matchingPermissionsTotal` ascending, while treating `0` as an unknown-coverage edge case and pushing those candidates later.
6. Flag roles as privileged when they also grant `Microsoft.Authorization/roleAssignments/write`.

The canonical implementation seam is `scripts/lib/rbac.js`. The sample CLI wrapper is `scripts/match-roles.js`.

## Install and Run

### Copilot CLI plugin (primary path)

```bash
/plugin install kdcllc/azure-rbac-role-matching-skill
```

After installation, invoke the skill directly from the Copilot CLI agent. The skill runs entirely offline — no live Azure API calls are made at install time or at match time.

### npm (library / CLI path)

Use when integrating the matcher into your own scripts or Node.js tooling:

```bash
npm install azure-rbac-role-matching-skill
npx azure-rbac-role-match Microsoft.Support/services/read
```

For a global install:

```bash
npm install -g azure-rbac-role-matching-skill
azure-rbac-role-match Microsoft.Support/services/read
```

## Agent Integration

Use the shared matcher directly when integrating this skill into another agent flow:

```javascript
const {
   loadExtendedRolesPayload,
   loadPermissionIndex,
   rankRoles,
} = require('azure-rbac-role-matching-skill');

const [payload, permissionIndex] = await Promise.all([
   loadExtendedRolesPayload(),
   loadPermissionIndex(),
]);

const matches = rankRoles(
   ['Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'],
   payload.roles,
   permissionIndex
);
```

## Outputs

- ranked built-in role candidates
- `matchingPermissionsTotal` for each candidate
- privileged-role flag
- custom-role guidance when no built-in role covers every requested permission

## Boundaries

- The corpus is snapshot-based, not live.
- Shipping through a root `plugin.json` does not change runtime behavior — the matcher always runs offline against checked-in snapshot data.
- This skill covers Azure built-in roles only. Custom role JSON generation is out of scope.
- This repo does not validate scope-specific access behavior.
- This repo does not handle deny assignments, PIM, ABAC, or broader governance logic.
- `matchingPermissionsTotal` is a size heuristic, not a security score.
- The result list is recommendation guidance, not an enforcement decision.

## Validation

```bash
npm run validate
npm run match -- Microsoft.Support/services/read
npm pack --dry-run
```

## References

- `README.md` — package overview
- `references/ALGORITHM.md` — matcher and ranking details
- `references/DATA-REFRESH.md` — snapshot refresh process
- `references/OPERATOR-GUIDE.md` — human workflow and interpretation guidance