HOE HET WERKT

Stel TerraProvider in voor je tenant en pipeline.

Wat de engineer die TerraProvider inricht moet weten: hoe de aanmelding werkt, welke machtigingen worden aangevraagd, hoe het eerste plan eruitziet en hoe je een bestaande tenant onder code brengt.

terraprovider/microsoft365wp
Terraform and OpenTofu
10 builds
versie 0.20.2

SETUP

Je eerste plan in vier stappen

Vergelijkbaar met het instellen van een andere Azure-provider, want de aanmelding werkt op dezelfde manier.

Registreer een app in Entra ID.
Enkele tenant, geen redirect-URI nodig. Noteer de application (client) ID en de directory (tenant) ID.
Ken Graph-machtigingen toe.
Voeg de applicatiemachtigingen toe voor de objecten die je wilt beheren (zie de tabel hieronder) en verleen admin consent.
03
Declareer de provider.
Stel ARM_TENANT_ID en ARM_CLIENT_ID in, plus ARM_CLIENT_SECRET voor een eerste test. Gebruik in een pipeline OpenID Connect (zie hieronder).
main.tf
```
terraform {  required_providers {    microsoft365wp = {      source = "terraprovider/microsoft365wp"    }  }}provider "microsoft365wp" {}
```

Plan.

Schrijf één resource, bijvoorbeeld een compliance policy, en voer terraform plan of tofu plan uit. Er verandert niets in de tenant totdat je apply uitvoert.

compliance.tf

resource "microsoft365wp_device_compliance_policy" "windows_defender" {  display_name = "Windows - Defender for Endpoint"  windows10 = {    device_threat_protection_enabled = true  }  scheduled_actions_for_rule = [{    scheduled_action_configurations = [{      action_type        = "block"      grace_period_hours = 6    }]  }]  assignments = [{    target = { all_licensed_users = {} }  }]}

Voorbeelddata.

MACHTIGINGEN

De Graph-machtigingen die worden aangevraagd

Applicatiemachtigingen, verleend met admin consent. Ken alleen de machtigingen toe voor de objecten die je beheert; een resource die hier niet staat, vermeldt zijn machtigingen op de bijbehorende documentatiepagina.

De Graph-machtigingen die worden aangevraagd
Machtiging	Wat het toestaat
DeviceManagementConfiguration.ReadWrite.All	Intune apparaatconfiguratie en beleid
DeviceManagementApps.ReadWrite.All	Intune apps
DeviceManagementServiceConfig.ReadWrite.All	Intune serviceconfiguratie, zoals inschrijving
Policy.ReadWrite.ConditionalAccess	Conditional Access-beleid
Policy.Read.All	Het beleid van je organisatie lezen
Application.ReadWrite.All	Applicaties
Directory.ReadWrite.All	Directorygegevens
Group.ReadWrite.All	Groepen
User.ReadWrite.All	Volledige profielen van gebruikers
CloudPC.ReadWrite.All	Windows 365-configuratie

Bron: de handleiding van de provider "Configuring a Service Principal for managing EntraID".

AANMELDEN

Dezelfde aanmeldinstellingen als de azuread-provider

De provider leest dezelfde ARM_* instellingen als de azuread-provider. Stel ARM_TENANT_ID en ARM_CLIENT_ID in en kies vervolgens een methode.

Dezelfde aanmeldinstellingen als de azuread-provider
Methode	Waar het past	Inschakelen
OpenID Connect, GitHub Actions	Workflows zonder opgeslagen secret	`ARM_USE_OIDC=true`
OpenID Connect, Azure DevOps	Pipelines met een serviceverbinding	`ARM_USE_OIDC=true` `ARM_ADO_PIPELINE_SERVICE_CONNECTION_ID`
OpenID Connect, elke issuer	Andere CI-systemen die een ID-token uitdelen	`ARM_USE_OIDC=true` `ARM_OIDC_TOKEN / ARM_OIDC_TOKEN_FILE_PATH`
Client certificate	Runners met een certificaat	`ARM_CLIENT_CERTIFICATE / ARM_CLIENT_CERTIFICATE_PATH`
Client secret	Een eerste test, een lab	`ARM_CLIENT_SECRET / ARM_CLIENT_SECRET_FILE_PATH`
Managed identity	Runners op Azure	`ARM_USE_MSI=true`
AKS workload identity	Runners op Kubernetes in Azure	`ARM_USE_AKS_WORKLOAD_IDENTITY=true`
Azure CLI	Je laptop	standaard ingeschakeld; `ARM_USE_CLI=false` schakelt het uit

Elke instelling bestaat ook als provider-argument (use_oidc, client_certificate_path enzovoort). De OpenID Connect-handleiding van de provider laat zien hoe je Entra ID een GitHub-repository kunt laten vertrouwen. In één regel: OpenID Connect (GitHub Actions, Azure DevOps, elke OIDC-token), client certificate, client secret, managed identity, AKS workload identity, Azure CLI.

Vier clouds

Stel environment of ARM_ENVIRONMENT in. De provider communiceert vervolgens met het Microsoft Graph-eindpunt van die cloud: global, US Government L4, US Government L5 (DoD), China.

Omgeving

global (ook public): De commerciële cloud, de standaard
usgovernmentl4 (ook usgovernment): US Government L4
usgovernmentl5 (ook dod): US Government L5 (DoD)
china: De cloud van Microsoft in China
Je eigen eindpunt: metadata_host or ARM_METADATA_HOSTNAME

DRIFT

Wat het plan bijhoudt

Terraform vergelijkt je configuratie met wat de tenant rapporteert. TerraProvider zorgt ervoor dat die vergelijking het hele object omvat: elke attribuut die je niet instelt krijgt een standaardwaarde, afgeleid van wat de Microsoft-portals terugsturen wanneer je hetzelfde object daar aanmaakt. Zo is een uitsluiting die in de portal aan een beleid is toegevoegd, een schakelaar die in het Intune-beheercentrum is omgezet of een instelling die door een script is gewijzigd, zichtbaar in het volgende plan, ongeacht of je bestand er melding van maakt.

Collecties die je weglaat krijgen standaard de waarde leeg, waardoor een toegevoegd lid, uitsluiting of app zichtbaar is.
Een nieuw Conditional Access-beleid zonder status wordt aangemaakt als enabledForReportingButNotEnforced.
De standaardwaarde van elk attribuut staat op de documentatiepagina van de resource, aangeduid als de provider default.

De keerzijde: een instelling die iemand in een portal aan en weer uit heeft gezet, kan terugkomen als false in plaats van niet-ingesteld, en verschijnt eenmalig als wijziging. Één apply lost dat op.

In de portal: Geen wijzigingen sinds de laatste apply.

microsoft365wp_conditional_access_policy.require_mfa_admins: Refreshing state... [id=2b7f9c3e-8d41-4f6a-b0e2-5c9a1d7e3f80]No changes. Your infrastructure matches the configuration.

resource "microsoft365wp_conditional_access_policy" "require_mfa_admins" {  display_name = "Require MFA for admins"  state        = "enabled"  conditions = {    users = {      include_roles = ["62e90394-69f5-4237-9190-012177145e10"]    }    applications = {      include_applications = ["All"]    }  }  grant_controls = {    operator          = "OR"    built_in_controls = ["mfa"]  }}

Voorbeelddata.

BESTAANDE TENANT

Een bestaande tenant exporteren en importeren in twee fasen

De quickstart-repository bevat een referentieconfiguratie met modules, GitHub Actions-workflows en een PowerShell-export. De export werkt in twee fasen, omdat beleid verwijst naar groepen en filters.

Exporteer groepen, filters en meldingssjablonen.
Ze worden weggeschreven naar de modules van de quickstart, met een mappingbestand per type. Groepen met e-mail zijn niet inbegrepen, tenzij je daar expliciet om vraagt.
Importeer ze.
Het hulpprogramma roept Terraform of OpenTofu aan om elk geëxporteerd object in de state te importeren.
Exporteer compliance- en configuratiebeleid.
Settings catalog- en endpoint security-beleidsregels tellen als configuratiebeleid. Elke export bewaart ook een onbewerkte JSON-dump van wat Graph heeft teruggestuurd.
Importeer ze.
Hetzelfde hulpprogramma, tweede fase.
Plan.
Het plan toont wat nog verschilt. Niet elk attribuut kan worden geëxporteerd, dus reken op een korte opschoning voordat het eerste schone plan er is.

Eén object tegelijk

Voor alles wat de export niet dekt, schrijft een klein script een Terraform-bestand voor één object van een willekeurig resourcetype, op basis van het id. Het maakt gebruik van de eigen configuratiegeneratie van Terraform, zodat het bestand bevat wat de provider zelf uit de tenant uitleest.

De quickstart op GitHub

APPS

Eén resource bevat de app, het pakket en de toewijzingen

microsoft365wp_mobile_app ondersteunt 21 app-typen. Voor .intunewin, MSI, APPX/MSIX, DMG, PKG pakketten versleutelt de provider het bestand en uploadt het naar Intune, en doet dat opnieuw alleen wanneer source_sha256 wijzigt. Toewijzingen staan in dezelfde resource: alle apparaten, alle gelicentieerde gebruikers, een groep of een uitsluitingsgroep, elk met een include- of exclude-filter.

locals {  agent_package = "${path.module}/packages/contoso-agent-4.2.1.intunewin"  agent_meta    = provider::microsoft365wp::parse_intunewin_metadata(local.agent_package)}resource "microsoft365wp_mobile_app" "contoso_agent" {  display_name = "Contoso Agent"  publisher    = "Contoso"  win32_lob = {    file_name              = local.agent_meta.file_name    setup_file_path        = local.agent_meta.setup_file    install_command_line   = "setup.exe /quiet"    uninstall_command_line = "setup.exe /uninstall /quiet"    detection_rules = [{      filesystem = {        detection_type      = "exists"        path                = "C:\\Program Files\\Contoso\\Agent"        file_or_folder_name = "agent.exe"      }    }]    source_file   = local.agent_package    source_sha256 = filesha256(local.agent_package)  }  assignments = [{    target   = { group = { group_id = "3d9b2f61-7a4e-4c18-9e05-6f2a8b1c4d93" } }    settings = { win32_lob = {} }  }]}

microsoft365wp_mobile_app.contoso_agent: Refreshing state... [id=5e0c8a17-2d94-4b6f-a3e1-9c7d0f2b8a46]No changes. Your infrastructure matches the configuration.

  # microsoft365wp_mobile_app.contoso_agent will be updated in-place  ~ resource "microsoft365wp_mobile_app" "contoso_agent" {      ~ win32_lob = {          ~ source_file   = "./packages/contoso-agent-4.2.1.intunewin" -> "./packages/contoso-agent-4.3.0.intunewin"          ~ source_sha256 = "9f2c41d0…" -> "b71e05aa…"            # (6 unchanged attributes hidden)        }        # (4 unchanged attributes hidden)    }Plan: 0 to add, 1 to change, 0 to destroy.

Voorbeelddata.

Windows
Win32 (.intunewin), MSI, APPX/MSIX, Microsoft Store (nieuw, via WinGet), Microsoft Store (legacy), Microsoft Edge, Microsoft 365 Apps, weblinks.
macOS
DMG, PKG, Microsoft Edge, Microsoft Defender, Microsoft 365 Apps, webclips.
iOS en iPadOS
App Store-apps, beheerde iOS Store-apps, webclips.
Android
Google Play Store-apps, beheerde Google Play-apps, beheerde Android Store-apps.
Elk platform
Weblinks.

TENANTS

Meerdere tenants vanuit één repository

Een provider-block meldt zich aan bij één tenant. Voor meerdere tenants declareer je per tenant één block met een alias en het bijbehorende tenant_id, schrijf je de baseline als een module en roep je die één keer per tenant aan. Elk block meldt zich zelfstandig aan, zodat elke tenant zijn eigen service principal met eigen machtigingen kan hebben.

Verschillen tussen tenants zijn modulevariabelen, zichtbaar in de review.
Een nieuwe tenant is één provider-block, één module-aanroep en één plan.

main.tf

provider "microsoft365wp" {  alias     = "contoso"  tenant_id = "8a1f3c2e-5b7d-4e90-a6c4-2d9e7f1b0c35"}provider "microsoft365wp" {  alias     = "fabrikam"  tenant_id = "e4c27b91-0d3a-4f86-b5e2-7a1c9d0f6b48"}module "baseline_contoso" {  source    = "./baseline"  providers = { microsoft365wp = microsoft365wp.contoso }}module "baseline_fabrikam" {  source     = "./baseline"  providers  = { microsoft365wp = microsoft365wp.fabrikam }  allow_byod = true}

Voorbeelddata.

Hoe Graph-throttling wordt afgehandeld

Microsoft Graph beperkt het aantal verzoeken dat een client mag sturen, en een plan over een grote tenant stuurt er veel. De provider wacht en probeert het zelf opnieuw.

Pogingen

Pogingen per verzoek: tot 10
Wachttijd tussen pogingen: 3 tot 60 seconden
Een Retry-After van nul: Opgerekt naar de backoff, omdat Graph vaak zo antwoordt en een directe nieuwe poging zelden helpt

Begin met de quickstart.

Clone de repository, wijs hem naar een testtenant en voer een plan uit. De Community Edition is gratis voor organisaties met maximaal 99 gebruikers.

Quickstart openen Documentatie openen

Stel TerraProvider in voor je tenant en pipeline.

Je eerste plan in vier stappen

Registreer een app in Entra ID.

Ken Graph-machtigingen toe.

Declareer de provider.

Plan.

De Graph-machtigingen die worden aangevraagd

Dezelfde aanmeldinstellingen als de azuread-provider

Vier clouds

Omgeving

Wat het plan bijhoudt

Een bestaande tenant exporteren en importeren in twee fasen

Exporteer groepen, filters en meldingssjablonen.

Importeer ze.

Exporteer compliance- en configuratiebeleid.

Importeer ze.

Plan.

Eén object tegelijk

Eén resource bevat de app, het pakket en de toewijzingen

Windows

macOS

iOS en iPadOS

Android

Elk platform

Meerdere tenants vanuit één repository

Hoe Graph-throttling wordt afgehandeld

Pogingen

Begin met de quickstart.