Skip to main content
This is not an official U.S. federal government website. The Federal Modernization Workbook is independent technical analysis. It does not represent the position of, and has not been reviewed or endorsed by, any federal agency.

Federal Modernization Workbook · Book 19

Book 19 — Building the Attribute-Driven Migration

Why the Attribute-Driven Migration needs code with tests, not only runbooks: the HR middleware, Graph clients for the government clouds, validation kit checks, dynamic rules as code, Lifecycle Workflows extensions, Group Policy and machine configuration as code, Ansible beside Arc, and drift pipelines that hand evidence to the ISSO

Book 19 of the Federal Modernization Workbook: a developer workbook for the Attribute-Driven Migration project, a code-first companion for the developers who build its middleware, automation, checks and pipelines. Each chapter builds on runnable code in the repository’s examples folder, runs a lab against fixtures with no tenant, then a step in a test tenant, and lists the verified Graph and Azure facts, the dangers and a checklist.

A developer workbook for the Attribute-Driven Migration project

ImportantStatus: approved

All ten chapters are written, and the owner had approved every page by November 3, 2026. A page that changes after its approval goes back on the weekly source watch list until it is approved again. Chapters 01 to 09 each have a narrated deck and video, listed under Narrated chapter tours. Every external claim was checked against Microsoft Learn or a workbook chapter between October 30 and November 2, 2026 and carries a note, 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 Attribute-Driven Migration moves an agency from Active Directory to Microsoft Entra ID by placing every person, device and server in policy through attributes instead of OU placement. Its operator material already exists: the companion guide, the implementation guide with its ten gates, the project plan and the narrated decks. Those tell an operator what to do and how to prove it was done. They don’t teach anyone to build the software the migration runs on: the middleware between the HR system and Entra ID, the Graph clients, the checks that prove each gate, the rule library, the workflow extensions, and the pipelines that catch drift and hand evidence to the ISSO.

This workbook is for the developers who build those pieces. It is code first. Each chapter starts from working code in the repository’s examples folder, extends it where the chapter needs to, and adds 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. Each lists the Graph and Azure facts the code depends on (endpoints, the least-privileged permission, availability in the US Government clouds), footnoted to Microsoft Learn with the date the page was read, then the dangers and a checklist.

This workbook or the implementation guide?

The project has two long documents, and they do different jobs. Attribute-Driven Migration: An Implementation Guide is for the people who run the migration. This workbook is for the people who build the software the migration runs on.

The implementation guide and the developer workbook
The implementation guide This developer workbook
Reader Operators, migration leads and ISSOs Developers and platform engineers
Question it answers What has to be true at each gate, and how do I prove it? How do I build, test and ship the code that makes it true?
Shape Ten gates, from reading the OU tree (Gate 0) to keeping attributes true (Gate 9). Each has prerequisites, steps, a Validate step, rollback and evidence Nine code chapters, each starting from code in the examples folder, with a lab against fixtures, a test-tenant step, verified Graph and Azure facts, dangers and a checklist
You finish with A migrated estate and the evidence package for each gate Middleware, Graph clients, validation checks, rule libraries, workflow extensions and drift pipelines, with passing tests
Download attribute-driven-migration-implementation-guide.docx attribute-driven-migration-code.zip

They meet at the Validate step. Each gate in the guide names a validation kit check, and Chapter 03 teaches how to write one. Read the guide first if you need to know what the migration has to achieve, and the workbook when you have to build part of it.

The pieces and how they connect

Six boxes. The project plan, top left, sets the gates of the implementation guide, top center, which runs the migration as ten gates from reading the OU tree to keeping attributes true. An arrow from the guide down to this developer workbook, center, is labeled what each gate needs built; the workbook's nine chapters are code first. An arrow from the workbook down to the code, bottom center, the repository's examples folder with its kits and pinned Microsoft samples, is labeled chapters build on it, with tests. A line from the guide around the left side to the code is labeled each gate's Validate step runs a validation kit check. On the right, presentations, decks and narrated videos, receive arrows from the guide, decks follow the gates, and from the workbook, a tour per chapter. The code points right to one download, attribute-driven-migration-code.zip, every folder with its tests.
Figure 1: The pieces of the Attribute-Driven Migration project and how they connect.
Piece What it is Where
Project plan The phases, owners, dates and exit criteria the gates are scheduled against Attribute-Driven Migration project plan
Implementation guide The operator’s guide: ten gates, each with steps, a Validate step, rollback and evidence. It says what has to be true at each gate; this workbook builds the software that makes it true Attribute-Driven Migration: An Implementation Guide
Developer workbook This workbook: nine code chapters, each building on code in the repository, with labs and tests, and a deployment runbook Chapters below
Presentations The two-part technical deep dive and the three-part deeper dive follow the guide’s gates. Chapters 01 to 09 also have a narrated tour: a deck and a video Presentations · Narrated chapter tours
Code The examples folders the chapters build on, and the Microsoft samples they start from, pinned unmodified under third_party with their licenses examples on GitHub
Code download Every folder the nine code chapters use, in one zip, with its tests and fixtures. Each script also has a .txt copy for mail systems that block scripts attribute-driven-migration-code.zip

The zip holds hcm-entra (Chapters 01, 02 and 09), ms-automation (02), validation-kit (02, 03, 04, 06 and 09), dynamic-rules (02, 04 and 09), lifecycle-extensions (05), group-policy-as-code (06), machine-configuration (07 and 09), ansible (08) and drift-pipeline (09), and the pinned samples each chapter starts from.

How each chapter is built

Section What it holds
Goal and audience What you will build, and who should read it
The code The example it builds on, what this chapter adds, 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

# Chapter Builds on What you build Status
01 The HR-to-Entra middleware Microsoft’s CSV2SCIM sample (pinned in examples/third_party/csv2scim), then examples/hcm-entra Start from Microsoft’s sample, then add what it leaves to you: validation that fails closed, quarantine, ordering, a mass-disable hold, pacing, the US Government clouds, least privilege, and a provenance manifest Approved
02 Graph clients for the government clouds Microsoft’s Graph SDK national cloud snippets (pinned in examples/third_party/msgraph-snippets-python), then examples/ms-automation One client pattern for worldwide, GCC, GCC High and DoD: GCC on the worldwide endpoints with commercial Resource Manager, the token authority and hosts per cloud, every call declared with its least-privileged permission and checked against the token, paging with @odata.nextLink, Retry-After, and beta calls the run doesn’t depend on Approved
03 Writing a validation kit check examples/validation-kit A new check, VK-SYNC-02, from the catalog entry through pass and fail fixtures and Pester tests to the GET-only safety rule, and what to do when the read needs a privileged role Approved
04 Dynamic rules as code Learn’s dynamic membership processing samples (pinned in examples/third_party/dynamic-membership-samples), then examples/dynamic-rules A rule library in Git: one file per group with tests, an offline evaluator and a linter for the guards every user rule needs, a shadow diff in the pull request, comparison with the beta evaluateDynamicMembership action (VK-DG-03), and an incident path that resumes only what it paused Approved
05 Lifecycle Workflows custom extensions Learn’s Logic App definition for custom task extensions (pinned in examples/third_party/lifecycle-workflows-logic-app), then examples/lifecycle-extensions Start from Learn’s definition, then add what it leaves to you: one reusable Logic App per integration with its own managed identity, a checked callback path, a callback on failure, the Graph host for each US cloud, idempotency, retries inside the callback timeout, proof-of-possession authorization from a reviewed registry, and Book 03’s leaver order Approved
06 Moving Group Policy as code Microsoft’s settings catalog samples (pinned in examples/third_party/mggraph-intune-samples), examples/validation-kit (VK-INT-07), then examples/group-policy-as-code Read Group Policy analytics (beta) into a per-setting move plan, keep settings catalog policies as reviewed JSON with an owner and decisions, lint them, diff them against the tenant, and create only what is missing, with least privilege per call and a host per cloud Approved
07 Machine configuration packages Learn’s GuestConfiguration procedure and Microsoft’s samples (pinned in examples/third_party/guest-configuration-samples), then examples/machine-configuration Follow Learn’s cmdlets from DSC configuration to policy definition, then add what they leave to you: a MOF free of build-host data that compiles to the same bytes every time, package and definition checks against a release registry, the owner tag filter, Arc scope, and a provenance manifest Approved
08 Ansible beside Arc Microsoft’s azure_arc role (pinned in examples/third_party/azure-arc-role), then examples/ansible Start from Microsoft’s role, then add what it leaves to you: the patch_owner column and a CMDB inventory that reads both owners into the ConfigOwner and PatchOwner tags, a wave plan before every run, a dry run the role can’t do, canary batches, and commercial Azure for a GCC estate Approved
09 Drift pipelines and evidence to the ISSO Learn’s Azure Login OIDC sample workflows (pinned in examples/third_party/azure-login-oidc-sample), then the kits’ run outputs in examples/drift-pipeline Start from Learn’s sample, then add what it leaves to you: a schedule, pinned actions, sign-in and Graph hosts for GCC, GCC High and DoD, a comparison of each run with the last that never treats a failed read as a fix, findings opened and closed by fingerprint without names, and an evidence package with a SHA-256 per file, the other kits’ provenance and a hash chain Approved
10 Deploying to test and production examples/drift-pipeline/deploy, and the commands of Chapters 01 to 09 A runbook in exact commands from the chapters’ test-tenant steps to a live test environment, then production in waves: one settings file per stage with no secrets, a pre-flight check, a smoke test that says go or no-go, a recorded rollback, and the evidence the ISSO keeps. Not run against a live tenant Approved

Chapter 02 is the foundation the other chapters lean on: read it before you build a new Graph or Azure client of your own. Chapters 01, 03 and 04 were written first, because their code already existed.

Changes from the first outline

  • Chapter 01 starts from Microsoft’s sample. Microsoft publishes CSV2SCIM for this integration and documents it on Learn. The chapter runs it first, on the same HR fixture, and builds the hardened client only for what the sample leaves out. The repository keeps a pinned copy so the labs stay stable.
  • Chapter 03’s worked example is a new check. The outline proposed walking through an existing check. The chapter builds VK-SYNC-02 instead, because its live read needs Global Administrator, which makes it the clearest case for the kit’s rule that a read-only check still has to ask for the least privilege it can.
  • Chapter 04 is written without the agents’ user account clause. Learn says an agent’s user account is evaluated by user-based membership rules like any other user, and that a rule can exclude such accounts, but its rule property tables, read again on October 30, 2026, don’t name the property to use.1 The chapter says so instead of guessing; the clause, and VK-DG-01’s and DR-03’s guards, follow when Learn documents it. The chapter also starts from Learn’s dynamic membership processing samples, the only Microsoft samples for this area.
  • Chapter 07 follows Learn’s procedure and checks between its steps. The outline had the chapter build its own pipeline around the cmdlets. Running Learn’s commands showed the gaps sit between the steps, not in them, so the build calls the cmdlets in Learn’s order and checks each output. Signing stays Learn’s procedure, unwrapped, and the agent-side test runs on a disposable server in Lab 2, because Learn says it installs the agent and needs elevation.
  • Chapter 08 added one input first. The Ansible guide names a patch_owner field in the CMDB, which the sample CMDB export in examples/ansible didn’t carry. The chapter added the column, with tests, before relying on it.

Narrated chapter tours

Chapters 01 to 09 each have 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 (Chapters 07 and 08 on October 31, 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 The HR-to-Entra Middleware ▶ Watch · MP4 11 min DW_ADM_01_HR_Entra_Middleware.pptx Narrated
02 Graph Clients for the Government Clouds ▶ Watch · MP4 11 min DW_ADM_02_Graph_Clients.pptx Narrated
03 Writing a Validation Kit Check ▶ Watch · MP4 11 min DW_ADM_03_Validation_Kit_Check.pptx Narrated
04 Dynamic Rules as Code ▶ Watch · MP4 11 min DW_ADM_04_Dynamic_Rules.pptx Narrated
05 Lifecycle Workflows Custom Extensions ▶ Watch · MP4 12 min DW_ADM_05_Lifecycle_Extensions.pptx Narrated
06 Moving Group Policy as Code ▶ Watch · MP4 11 min DW_ADM_06_Group_Policy_as_Code.pptx Narrated
07 Machine Configuration Packages ▶ Watch · MP4 11 min DW_ADM_07_Machine_Configuration.pptx Narrated
08 Ansible Beside Arc ▶ Watch · MP4 11 min DW_ADM_08_Ansible_Beside_Arc.pptx Narrated
09 Drift Pipelines and Evidence to the ISSO ▶ Watch · MP4 11 min DW_ADM_09_Drift_Pipelines_Evidence.pptx Narrated

Reading paths

  • Developers new to the migration: the companion guide first, then Chapter 01.
  • Developers extending the validation kit: Chapter 03, then Chapter 04.
  • Platform and pipeline engineers: Chapter 07, then 08 and 09.
  • ISSOs and reviewers of the code: the checklists at the end of each chapter, and Chapter 09.

Where this workbook sits

This is Book 19 of the Federal Modernization Workbook: the developer workbook for the Attribute-Driven Migration project. The developer workbooks for other projects are under Projects. The HR side of the migration, its schema and its lifecycle rules are Book 03. The directory, sync and matching are Book 02. Devices, Intune and Azure Arc are Book 05. Change control, provenance and the drift engine are Book 13. The gates each chapter’s code proves are in the implementation guide.

New and revised procedures in this workbook follow the workbook’s implementation conventions (control states, the How-section template, authority labels, the evidence checklist, change safety and the Zero Trust mapping block), defined once in Book 00, Appendix D.

Chapters

Title Description
Chapter 01 — The HR-to-Entra Middleware Building the middleware between an HR extract and Microsoft Entra ID’s API-driven inbound provisioning, starting from Microsoft’s own CSV2SCIM sample (pinned in the repository) and adding only what a federal deployment needs on top: validation that fails closed, quarantine, leaver-first and manager-first ordering, a mass-disable hold, pacing within the documented limits, all three US clouds, least privilege, and a provenance manifest, with labs against fixtures and a test tenant.
Chapter 02 — Graph Clients for the Government Clouds One Microsoft Graph client pattern for worldwide, GCC, GCC High and DoD, starting from Microsoft’s own Graph SDK snippets for national clouds (pinned in the repository) and adding what they leave to you: a cloud table with the token authority, Graph host and Resource Manager host for each, least-privileged permissions declared per call and checked against the token, paging with @odata.nextLink, Retry-After, and beta calls the run doesn’t depend on, with labs against fixtures and a test tenant.
Chapter 03 — Writing a Validation Kit Check How to add a check to the read-only validation kit, built end to end on a new check, VK-SYNC-02 (soft match and hard match takeover blocking): the catalog entry, the data read, findings and outcome, pass and fail fixtures, Pester tests, the GET-only safety rule, and what to do when even a read needs Global Administrator, with labs against fixtures and a test tenant.
Chapter 04 — Dynamic Rules as Code Keeping dynamic membership rules in Git as code: one file per group with an owner and membership tests, a parser and offline evaluator for the rule syntax Learn documents, a linter for the guards every access rule needs, a shadow diff on every change, and an incident path built on Learn’s own pause and resume samples (pinned in the repository) with the record they leave out, with labs against fixtures and a test tenant.
Chapter 05 — Lifecycle Workflows Custom Extensions Building the Logic Apps that Lifecycle Workflows custom task extensions call: start from Learn’s Logic App definition (pinned in the repository), then add what it leaves to you: one reusable Logic App per integration with its own managed identity, a checked callback path, a callback on failure as well as success, the right Graph host for each US cloud, idempotency, bounded retries inside the callback timeout, proof-of-possession authorization built from a reviewed registry, and Book 03’s leaver order, with labs against fakes and a test tenant.
Chapter 06 — Moving Group Policy as Code Moving Group Policy settings to Intune settings catalog policies as code: read Intune’s Group Policy analytics (Graph beta) into a per-setting move plan, keep each policy as reviewed JSON in Git with its owner and decision records, lint it, diff it against the tenant, and create only what is missing, starting from Microsoft’s own settings catalog samples (pinned in the repository), with least privilege per call, the US Government clouds, and labs against fixtures and a test tenant.
Chapter 07 — Machine Configuration Packages Building Azure Machine Configuration content from Learn’s own procedure and Microsoft’s pinned samples, then adding only what a federal pipeline needs on top: a MOF free of build-host data that compiles to the same bytes every time, a package and policy definition checked against a reviewed release registry, the owner tag that keeps two tools off one setting, Arc and Azure Government scope, and a provenance manifest, with labs offline and in a test subscription.
Chapter 08 — Ansible Beside Arc Onboarding servers to Azure Arc with Ansible while keeping one owning tool per setting: start from Microsoft’s own azure_arc role (pinned in the repository), then add what it leaves to you: a CMDB-driven inventory that reads config_owner and the new patch_owner column, mirrors them to the ConfigOwner and PatchOwner tags, plans each wave before anything runs, gives the role a dry run it can’t do itself, and keeps a GCC estate on commercial Azure, with labs offline and in a test subscription.
Chapter 09 — Drift Pipelines and Evidence to the ISSO A scheduled GitHub Actions pipeline that signs in with a federated credential and no secret, runs the validation kit read-only, compares each run with the last, opens findings for what is new, changed or unverified, and packages the run with the other kits’ provenance, a SHA-256 per file and a hash chain for the ISSO. It starts from Learn’s Azure Login sample workflows (pinned in the repository), checks them offline, and builds only what they leave out, with labs against fixtures and a test tenant.
Chapter 10 — Deploying to Test and Production The runbook that takes the Attribute-Driven Migration kits past the chapters’ test-tenant steps: one settings file per stage with no secrets, pre-flight checks, a live test stage in an Entra test tenant, an Azure test subscription with Arc-enabled test servers and a test AD forest, a go/no-go record, then production in waves, with a smoke test, first-week drift monitoring, rollback and the evidence the ISSO keeps at each stage. Every step is a command block or an exact admin center path, tied to the implementation guide’s gate it fulfils.
No matching items

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.

Versions of this book, newest first
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); Approve Book 19’s index and the Source Register; settle the sweep’s judgment calls (#365); Book 19: fix confirmed crosswalk errors (#377); Book 19 Ch 09: OSCAL export lab step (#401); Apply the open-choice decisions: text, plans, training, reference, register (#416); Book 19: fix inconsistency findings (#439); Decisions fix pass for Books 13 to 19: Book 18 gates and roles, Db2 spelling, Book 15 approvers, Book 16 criteria, Book 17 roles, Book 13 drift mapping (#456); and 6 more (all changes)
1.5 2026.11.4 2026-11-05 Sweep stale wording, and link sources on every deck (#361)
1.4 2026.11.3 2026-11-05 Review gate: Mike’s approval of the 53 pages in the November 2 review packet (#334); Review gate: cover the guides and training; document the VK-DG-03 exception (#336); Review gate: Mike’s approval of four pages changed on November 3 (#341)
1.3 2026.11.2 2026-11-02 HR-Driven Identity labs: exact commands for every step, real output, commands lists (#293); Book 19 and Microsoft Automation labs: exact commands for every step, real output, commands lists (#296); Tours: HR-Driven Identity’s seven chapter tours, and the Privileged Access, Non-Person Identity and Book 19 tours with real kit output (#297); Book 19: federal requirements and evidence for every scripted kit action (#306); Book 19, Chapter 10: deploying to test and production (#307)
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 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 (18 merged changes since the workbook began)

  1. Microsoft Learn, “Manage rules for dynamic membership groups in Microsoft Entra ID,” https://learn.microsoft.com/entra/identity/users/groups-dynamic-membership (accessed Oct 30, 2026).↩︎

Back to top