Projects · Developer workbook
Building Privileged Access
A developer workbook for the Privileged Access & Administrative Identity project
A developer workbook for the Privileged Access & Administrative Identity project
All nine chapters are written and approved. Narrated tours were recorded on November 2, 2026 for Chapters 01 to 08. Chapter 09, the deployment runbook, hasn’t been run against a live tenant. An approved page that changes goes back on the weekly source watch issue’s list for review. Every external claim carries a note and a read date against Microsoft Learn or a workbook chapter, and each chapter keeps its verification log in the repository. The code is illustrative. Its tests pass against fixtures, but it has not been run against a production tenant.
The Privileged Access & Administrative Identity project builds the privileged half of Book 04: emergency access first, then PIM self-request with approval for one role class, then every tier, then the evidence and the residual risk. Its operator material already exists: Book 04’s privileged tiers, the PIM build, the role settings reference, the reviews and access as code, and the project plan with its gates. Those tell an operator what to configure and how to prove it. They don’t teach anyone to build the software that reads the privileged estate, holds its settings as reviewed code, and hands the ISSO evidence a reviewer can check.
This workbook is for the developers who build that software. It is code first, and it starts from Microsoft. Each chapter begins with Microsoft Learn’s own procedure or sample, runs it offline against fakes, and builds only what it leaves out, in the repository’s examples folder, with tests. Each has a lab that runs on a laptop against fixtures with no tenant at all, then a short step in a test tenant with a way to back it out. Each lists the Graph and Azure facts the code depends on (endpoints, the least-privileged permission, availability in the US Government clouds, release stage), footnoted to Microsoft Learn with the date the page was read, then the dangers and a checklist. The last chapter is a runbook: it takes the kit from the labs to a live test tenant, then to production, with the same commands and one settings file per environment.
The target estate is Microsoft 365 GCC (Moderate) with commercial Azure. GCC uses the worldwide endpoints: login.microsoftonline.com, graph.microsoft.com and management.azure.com. GCC High and DoD have separate hosts.1 Every chapter says so where an endpoint matters.
How each chapter is built
| Section | What it holds |
|---|---|
| Goal and audience | What you will build, and who should read it |
| Start with Microsoft’s sample | What Learn or Microsoft’s sample gives you, the pinned copy, and what it leaves to you, as a table of gaps pinned by tests |
| The code | The example it builds, what it adds to Microsoft’s sample, and the tests |
| Lab 1: fixtures, no tenant | Steps you can run anywhere, with the expected output |
| Lab 2: test tenant | The smallest change a test tenant needs, and how to back it out |
| Verified facts | Endpoints, least-privileged permissions, national cloud availability and release stage, each footnoted |
| Dangers | What breaks in production, and the guard the code has for it |
| Checklist | What a reviewer checks before the code ships |
Design guidance in this workbook is marked as such: it is the program’s position, not a vendor statement. Preview and beta features carry their stage wherever they appear.
Chapters
The outline follows the project plan’s phases and Book 04, Chapter 08’s build order, which the plan calls fixed: emergency access first, then the activation policy, then the role settings, “because switching on approval before the emergency accounts exist is the one sequence that locks the agency out.”
| # | Chapter | Plan phase | Starts from | What you build | Status |
|---|---|---|---|---|---|
| 01 | Privileged inventory as code | Phase 0, A0.1, A0.2, Gate 0 | Learn’s samples for listing Microsoft Entra role assignments (pinned in examples/third_party/entra-role-assignments-page), then examples/privileged-access |
One read of every privileged assignment: Entra roles active and eligible, groups expanded to members, Azure role assignment and eligibility schedules, each row given a tier, findings for standing privilege, direct assignments, unnamed groups, unclassified roles, too many Global Administrators or subscription owners, and a manifest with a hash per file | Written |
| 02 | Emergency access accounts as code | Phase 0, A0.4; Phase 1, A1.1 | Learn’s emergency access standard and its alert queries (pinned in examples/third_party/entra-emergency-access-page), then examples/privileged-access |
A check of each account against the standard (cloud-only, permanent active Global Administrator, phishing-resistant methods only, excluded from every enforced policy, validated within 90 days), and the alert as an ARM template that also sees non-interactive sign-ins and audit events | Written |
| 03 | Conditional Access for administrators and the activation gate | Phase 1, A1.5; Phase 2, A2.3, A2.5 to A2.6 | Microsoft’s Conditional Access template for administrators as Graph JSON (pinned in examples/third_party/conditional-access-template-page), then examples/privileged-access |
Authentication contexts c1 and c2, the privileged strength and the administrator policies as reviewed JSON; a pre-merge check (PA-CA-01 to PA-CA-09) including the emergency exclusion; a diff against the tenant and a dry run, with every new policy created report-only and enforcement only with -AllowEnforce |
Written |
| 04 | PIM for Microsoft Entra roles as code | Phase 1, A1.6; Phase 2, A2.1 to A2.2; Phase 3, A3.1 | Learn’s Update rules in PIM samples and PIM role-assignment tutorial (pinned in examples/third_party/graph-pim-rules-pages), then examples/privileged-access |
Appendix B as one reviewed JSON file per role, applied through roleManagementPolicies rules with a diff and a dry run, read and write permissions split by task, conversion of standing assignments after confirmed activation, a guard against the documented lockout, a back-out from before.json, active assignments capped at 15 days, and rollout waves starting with Tier 1 |
Written |
| 05 | PIM for Groups and the PRV groups | Phase 2, A2.1; Phase 3, A3.3 | Microsoft’s PIM for Groups request samples (pinned in examples/third_party/graph-pim-for-groups-pages), then examples/privileged-access |
The PRV role-assignable groups, their member and owner schedules and two PIM policies as reviewed JSON; a read first, findings PA-PG-01 to -09, a plan with a diff, a dry run unless -Apply, guards G1 to G7 and least privilege per call; access packages deferred |
Written |
| 06 | PIM for Azure resources | Phase 3, A3.2 | Learn’s PIM for Azure resources REST walkthroughs and Microsoft’s REST examples (pinned in examples/third_party/azure-pim-rest-examples), then examples/privileged-access |
Role management policies by tier at every management group, subscription and resource group; eligible assignments as reviewed JSON with a diff, a dry run and -Apply; standing Owner, Contributor and User Access Administrator found and converted to eligible; Reader to read, User Access Administrator to apply |
Written |
| 07 | Access reviews of privileged roles | Phase 2, A2.7; Phase 3, A3.7 | Learn’s access reviews API tutorial for administrative roles (pinned in examples/third_party/graph-access-reviews-roles-tutorial), then examples/privileged-access |
Review series for Entra roles (users), each PRV group’s membership, and Azure roles (preview) as reviewed JSON, checked (including the guard that keeps the emergency accounts’ Global Administrator on silence), a dry run and diff before -Apply, least privilege per task, and the decisions read back as evidence |
Written |
| 08 | Evidence and drift for the ISSO | Phase 3, A3.6; Phase 4, A4.3 | Learn’s PIM audit history queries (pinned in examples/third_party/entra-pim-audit-page), then the first workbook’s drift pipeline |
A scheduled run of Chapter 01’s inventory, Chapter 02’s check and the PIM audit evidence from Graph, a comparison by fingerprint that treats Tier 0 drift as an incident and keeps names out of the tracker, packages with a SHA-256 per file, the tenant ID and a hash chain, and a period summary for Gate 4 | Written |
| 09 | Deploying to test and production | Phases 1 to 4, Gates 1 to 4 | Learn’s PIM deployment plan (pilot, testing and rollback), then Chapters 02 to 08’s entry scripts | A runbook of exact commands: one settings file per environment with no secrets; pre-flight checks that verify the emergency access accounts and their exclusion from every Conditional Access policy first (PA-DEP-01 to -06, -08 and -09); Stage 1 in a live test tenant in a lockout-safe order, a smoke test with a synthetic administrator and a rehearsed rollback; go/no-go criteria; Stage 2 in production with conversion in waves and a first week of drift; the evidence the ISSO keeps. Not yet run against a live tenant | Written |
Microsoft Entra ID Governance, which PIM and access reviews use, is available in GCC, GCC High and DoD.2
Narrated chapter tours
Every chapter from 01 to 08 has a narrated tour: a deck in Why, What, Who and How order, a self-running edition with captions, and a video. The tours were recorded on November 2, 2026 from the approved chapters, and a tour is re-recorded when its chapter changes. All of them are also on the Watch page.
| # | Chapter | Watch | Length | Deck | Narrated deck |
|---|---|---|---|---|---|
| 01 | Privileged Inventory as Code | ▶ Watch · MP4 | 11 min | DW_PA_01_Privileged_Inventory.pptx | Narrated |
| 02 | Emergency Access Accounts as Code | ▶ Watch · MP4 | 10 min | DW_PA_02_Emergency_Access.pptx | Narrated |
| 03 | Conditional Access for Administrators and the Activation Gate | ▶ Watch · MP4 | 11 min | DW_PA_03_CA_Activation_Gate.pptx | Narrated |
| 04 | PIM for Microsoft Entra Roles as Code | ▶ Watch · MP4 | 11 min | DW_PA_04_PIM_Entra_Roles.pptx | Narrated |
| 05 | PIM for Groups and the PRV Groups | ▶ Watch · MP4 | 11 min | DW_PA_05_PIM_for_Groups.pptx | Narrated |
| 06 | PIM for Azure Resources | ▶ Watch · MP4 | 12 min | DW_PA_06_PIM_Azure_Resources.pptx | Narrated |
| 07 | Access Reviews of Privileged Roles | ▶ Watch · MP4 | 12 min | DW_PA_07_Access_Reviews.pptx | Narrated |
| 08 | Evidence and Drift for the ISSO | ▶ Watch · MP4 | 12 min | DW_PA_08_Evidence_Drift.pptx | Narrated |
Reading paths
- Developers new to the project: Book 04, Chapter 04 for the tiers, then Chapter 01.
- Developers building the foundation (the plan’s Phase 1): Chapter 02 before anything else, then Chapters 03 and 04, in that order.
- Platform engineers for Azure: Chapter 01’s “The rows” section and Lab 1’s Azure scopes, then Chapter 06.
- ISSOs and reviewers of the code: the checklists at the end of each chapter, and the manifests the runs write.
- Operators deploying the kit: Chapter 09, after Lab 2 of Chapters 02 to 08.
- Operators and ISSOs running the rollout: the Privileged Access implementation guide, which takes Chapters 01 to 08 as eight gates, emergency access first, each with its federal requirements, a read-only check from the kit and rollback.
- Learners: the Privileged Access learning path, one module for each of Chapters 01 to 08, each ending with a knowledge check.
Where this workbook sits
This is the developer workbook for the Privileged Access & Administrative Identity project, one of the developer workbooks under Projects in the Federal Modernization Workbook. The privileged model, the build and its evidence are Book 04, Chapters 04 to 10 and Appendix B. The Graph client pattern every chapter follows, one cloud table, a declared call list with its least-privileged permission and no default cloud, is the first workbook’s Chapter 02. The drift and evidence pipeline Chapter 08 extends is the first workbook’s Chapter 09. The learning path teaches Chapters 01 to 08 as eight modules, each with the chapter’s Lab 1 as an exercise and a knowledge check.
Chapters
| Title | Description |
|---|---|
| Chapter 01 — Privileged Inventory as Code | Read every privileged assignment in the estate as code, starting from Learn’s own samples for listing Microsoft Entra role assignments (pinned in the repository) and adding what they leave to you: eligible as well as active assignments, role-assignable groups expanded to their members, Azure role assignment and eligibility schedules through Resource Manager, a tier for every row, findings for standing privilege, and a manifest the ISSO can check, with labs against fixtures and a test tenant. |
| Chapter 02 — Emergency Access Accounts as Code | Check the emergency access accounts against Learn’s standard as code, and write the alert on their use as a reviewed ARM template, starting from Learn’s own emergency access page and its sample alert queries (pinned in the repository) and adding what they leave to you: a check of every account, its methods, its Global Administrator assignment, the exclusion group and every enforced Conditional Access policy, and an alert that also sees non-interactive sign-ins and audit events, with labs against fixtures and a test tenant. |
| Chapter 03 — Conditional Access for Administrators and the Activation Gate | Hold the Conditional Access policies for administrators as reviewed JSON, starting from Microsoft’s own template for administrators as Graph returns it (pinned in the repository) and adding what it leaves to you: the emergency access exclusion, the phishing-resistant authentication strength, the PIM activation gate through authentication context c1, a pre-merge check, a diff against the tenant and a dry run, with every new policy created report-only, with labs against fixtures and a test tenant. |
| Chapter 04 — PIM for Microsoft Entra Roles as Code | Hold PIM role settings for Microsoft Entra roles as one reviewed JSON file per role, starting from Learn’s own samples for updating PIM rules and assigning eligibility (pinned in the repository) and adding what they leave to you: the authentication context, approver groups, a diff against the tenant, a dry run before any write, the least-privileged permission for each read and write, eligibility for the PRV groups, the conversion of standing assignments, a guard against the documented lockout, and the plan’s order of one role class first, then every tier, with labs against fixtures and a test tenant. |
| Chapter 05 — PIM for Groups and the PRV Groups | Hold the PRV role-assignable groups, their PIM for Groups member and owner schedules and their two role management policies as reviewed JSON, starting from Microsoft’s own PIM for Groups request samples (pinned in the repository) and adding what they leave to you: a read of the tenant first, checks against Learn’s limits and the program’s tiers, a plan with a diff, a dry run by default, guards that refuse unsafe changes, and least privilege per call, with labs against fixtures and a test tenant. |
| Chapter 06 — PIM for Azure Resources | Hold PIM for Azure resources as reviewed code through the Resource Manager API, starting from Learn’s REST walkthroughs and Microsoft’s own request and response examples (pinned in the repository) and adding what they leave to you: role management policies set by tier at every management group, subscription and resource group, eligible assignments as reviewed JSON with a diff, a dry run and an explicit apply, and standing Owner, Contributor and User Access Administrator found and converted to eligible, with labs against fixtures and a test tenant. |
| Chapter 07 — Access Reviews of Privileged Roles | Hold the access reviews of privileged roles as reviewed JSON and apply them through Microsoft Graph and Resource Manager, starting from Learn’s own access reviews tutorial for administrative roles (pinned in the repository) and adding what it leaves to you: one series per Microsoft Entra role, PIM for Groups group and Azure role, reviewer groups with fallbacks, the program’s cadence, auto-apply and no-response default with a guard against removing the emergency accounts, a dry run and diff before an explicit -Apply, least privilege per call, and the review results read back as evidence, with labs against fixtures and a test tenant. |
| Chapter 08 — Evidence and Drift for the ISSO | Run the privileged inventory and the emergency access check on a schedule with the PIM activation and audit evidence, compare each run with the last by fingerprint so no names reach the tracker, treat Tier 0 drift as an incident, and package each run with a SHA-256 per file, the tenant ID and a hash chain, then assemble the period the identity governance officer signs and the ISSO receives for the plan’s Phase 4 gate. It starts from Learn’s PIM audit queries (pinned in the repository), runs them offline, and builds on the first workbook’s drift pipeline for what they leave out, with labs against fixtures and a test tenant. |
| Chapter 09 — Deploying to Test and Production | A runbook that takes the kit from the labs to a live test tenant and subscription, then to production, with the same commands and one settings file per environment: roles, approvals and the change record; a settings file with no secrets; pre-flight checks that verify the emergency access accounts and their exclusion from every Conditional Access policy before anything else; a stage order that prevents lockout; a smoke test with a synthetic administrator; go/no-go criteria; production waves; first-week monitoring with drift; rollback; and the evidence the ISSO keeps. Every step is a command or an exact portal path. Nobody has run it against a live tenant yet. |
Version and revision history
Version 2.0, in edition 2026.11.5 (November 8, 2026). Every edition is kept on the Archive page; every change between editions is in the commit history.
| Version | Edition | Date | Changes |
|---|---|---|---|
| 2.0 | 2026.11.5 | 2026-11-08 | Release 2.0, the baseline: checked against every other book; Draft becomes Baseline; Edition 2026.11.4: record the edition and point deck links at it (#362); Privileged access workbook: fix confirmed crosswalk errors (#408); Privileged access workbook: fix 22 inconsistency findings (#448); Approve 116 gated pages (Nov 7); fix RMF map stale-review test (#457); Decisions of Nov 8, items 1-9 (Books 00-08) (#486); Approve 15 gated pages (Nov 8, after the consistency read) (#490); Release 2.0: Draft becomes Baseline (#491) |
| 1.5 | 2026.11.4 | 2026-11-05 | Deck and audio links point at edition 2026.11.4 |
| 1.4 | 2026.11.3 | 2026-11-05 | Privileged Access: fixes found preparing a live test-tenant run (#332); PIM alert check: a refused role policy read is a Finding, not the end of the run (#333); Review gate: Mike’s approval of the 53 pages in the November 2 review packet (#334) |
| 1.3 | 2026.11.2 | 2026-11-02 | HR-Driven Identity labs: exact commands for every step, real output, commands lists (#293); Privileged Access labs: exact commands for every step, real output, commands lists (#294); Non-Person Identity labs: exact commands for every step, real output, commands lists (#295); Tours: HR-Driven Identity’s seven chapter tours, and the Privileged Access, Non-Person Identity and Book 19 tours with real kit output (#297); Lab command lists: the cleanup after the last step is labeled “After the steps”, not with the step before it (#300); Privileged Access workbook: federal requirements and evidence for chapters 01-08 (#312); Building Privileged Access, Chapter 09: deploying to test and production (#311); Privileged Access learning path: eight modules (#322); and 3 more (all changes) |
| 1.2 | 2026.11.1 | 2026-11-01 | Edition 2026.11: record the edition, and publish the four gate-level decks and videos (#282) |
| 1.1 | 2026.11 | 2026-11-01 | Move the decks and narration audio out of git, onto edition 2026.10 (#260); Restore the developer workbook as Book 19, and the ADM implementation guide to Books > Guides (#270) |
| 1.0 | 2026.10 | 2026-10-31 | First edition (12 merged changes since the workbook began) |
Footnotes
Microsoft Learn, “Microsoft Graph national cloud deployments,” https://learn.microsoft.com/graph/deployments (accessed Oct 30, 2026).↩︎
Microsoft Learn, “Microsoft Entra feature availability,” other Microsoft Entra products, https://learn.microsoft.com/entra/identity/authentication/feature-availability (accessed Oct 30, 2026).↩︎