COME FUNZIONA

Configura TerraProvider nel tuo tenant e nella tua pipeline.

Tutto quello che chi configura TerraProvider deve sapere: come avviene l'autenticazione, quali permessi richiede, come si presenta il primo plan e come portare un tenant esistente sotto controllo del codice.

terraprovider/microsoft365wp
Terraform and OpenTofu
10 build
versione 0.20.2

SETUP

Il tuo primo plan in quattro passi

Richiede più o meno lo stesso tempo di qualsiasi altro provider Azure, perché l'autenticazione funziona allo stesso modo.

Registra un'app in Entra ID.
Single tenant, senza redirect URI. Annota l'application (client) ID e il directory (tenant) ID.
Concedi i permessi Graph.
Aggiungi i permessi applicazione per gli oggetti che vuoi gestire (vedi la tabella qui sotto) e concedi il consenso amministratore.
03
Dichiara il provider.
Imposta ARM_TENANT_ID e ARM_CLIENT_ID, più ARM_CLIENT_SECRET per un primo test. In una pipeline, usa invece OpenID Connect (vedi sotto).
main.tf
```
terraform {  required_providers {    microsoft365wp = {      source = "terraprovider/microsoft365wp"    }  }}provider "microsoft365wp" {}
```

Plan.

Scrivi una risorsa, ad esempio una compliance policy, ed esegui terraform plan o tofu plan. Nel tenant non cambia nulla finché non esegui l'apply.

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 = {} }  }]}

Dati di esempio.

PERMESSI

I permessi Graph richiesti

Permessi applicazione, concessi con il consenso amministratore. Concedi solo quelli relativi agli oggetti che gestisci; una risorsa non elencata qui indica i propri permessi nella relativa pagina di documentazione.

I permessi Graph richiesti
Permesso	Cosa consente
DeviceManagementConfiguration.ReadWrite.All	Configurazione dispositivi e policy Intune
DeviceManagementApps.ReadWrite.All	App Intune
DeviceManagementServiceConfig.ReadWrite.All	Configurazione del servizio Intune, ad esempio l'enrollment
Policy.ReadWrite.ConditionalAccess	Policy di Conditional Access
Policy.Read.All	Lettura delle policy dell'organizzazione
Application.ReadWrite.All	Applicazioni
Directory.ReadWrite.All	Dati della directory
Group.ReadWrite.All	Gruppi
User.ReadWrite.All	Profili completi degli utenti
CloudPC.ReadWrite.All	Configurazione di Windows 365

Fonte: la guida del provider "Configuring a Service Principal for managing EntraID".

AUTENTICAZIONE

Le stesse impostazioni di autenticazione del provider azuread

Il provider legge le stesse impostazioni ARM_* del provider azuread. Imposta ARM_TENANT_ID e ARM_CLIENT_ID, poi scegli un metodo.

Le stesse impostazioni di autenticazione del provider azuread
Metodo	Adatto per	Come attivarlo
OpenID Connect, GitHub Actions	Workflow senza secret memorizzati	`ARM_USE_OIDC=true`
OpenID Connect, Azure DevOps	Pipeline con una service connection	`ARM_USE_OIDC=true` `ARM_ADO_PIPELINE_SERVICE_CONNECTION_ID`
OpenID Connect, qualsiasi issuer	Altri sistemi CI che emettono un ID token	`ARM_USE_OIDC=true` `ARM_OIDC_TOKEN / ARM_OIDC_TOKEN_FILE_PATH`
Client certificate	Runner che dispongono di un certificato	`ARM_CLIENT_CERTIFICATE / ARM_CLIENT_CERTIFICATE_PATH`
Client secret	Un primo test, un ambiente di laboratorio	`ARM_CLIENT_SECRET / ARM_CLIENT_SECRET_FILE_PATH`
Managed identity	Runner su Azure	`ARM_USE_MSI=true`
AKS workload identity	Runner su Kubernetes in Azure	`ARM_USE_AKS_WORKLOAD_IDENTITY=true`
Azure CLI	Il tuo laptop	attivo per impostazione predefinita; `ARM_USE_CLI=false` lo disattiva

Ogni impostazione esiste anche come argomento del provider (use_oidc, client_certificate_path e così via). La guida OpenID Connect del provider mostra come far sì che Entra ID consideri attendibile un repository GitHub. In sintesi: OpenID Connect (GitHub Actions, Azure DevOps, qualsiasi token OIDC), client certificate, client secret, managed identity, AKS workload identity, Azure CLI.

Quattro cloud

Imposta environment o ARM_ENVIRONMENT. Il provider comunicherà con l'endpoint Microsoft Graph del cloud corrispondente: global, US Government L4, US Government L5 (DoD), China.

Environment

global (anche public): Il cloud commerciale, quello predefinito
usgovernmentl4 (anche usgovernment): US Government L4
usgovernmentl5 (anche dod): US Government L5 (DoD)
china: Il cloud Microsoft in Cina
Endpoint personalizzato: metadata_host or ARM_METADATA_HOSTNAME

DRIFT

Cosa monitora il plan

Terraform confronta la tua configurazione con quanto riporta il tenant. TerraProvider estende questo confronto all'intero oggetto: ogni attributo che non imposti riceve un valore predefinito, ricavato da ciò che i portali Microsoft restituiscono quando crei lo stesso oggetto lì. Così un'esclusione aggiunta a una policy nel portale, un'opzione modificata nell'Intune admin center o un'impostazione cambiata da uno script compare nel plan successivo, indipendentemente dal fatto che il tuo file ne faccia menzione.

Le raccolte che ometti hanno come valore predefinito il set vuoto, quindi un membro, un'esclusione o un'app aggiunta risulta visibile.
Una nuova policy di Conditional Access priva di stato viene creata come enabledForReportingButNotEnforced.
Il valore predefinito di ogni attributo è indicato nella pagina di documentazione della risorsa, contrassegnato come provider default.

Il rovescio della medaglia: un'impostazione attivata e poi disattivata nel portale può ricomparire come false invece che come non impostata, e viene segnalata una volta come modifica. Un apply la stabilizza.

Nel portale: Nessuna modifica dall'ultimo 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"]  }}

Dati di esempio.

TENANT ESISTENTE

Esporta e importa un tenant esistente in due fasi

Il repository quickstart include una configurazione di riferimento con moduli, workflow GitHub Actions e un export PowerShell. L'export si svolge in due fasi, perché le policy fanno riferimento a gruppi e filtri.

Esporta gruppi, filtri e template di notifica.
Vengono scritti nei moduli del quickstart, con un file di mapping per ogni tipo. I gruppi abilitati alla posta vengono esclusi a meno che tu non li richieda esplicitamente.
Importali.
Lo strumento chiama Terraform o OpenTofu per importare ogni oggetto esportato nello state.
Esporta le policy di compliance e configurazione.
Il settings catalog e le policy di endpoint security rientrano nelle policy di configurazione. Ogni export conserva anche un dump JSON grezzo di quanto restituito da Graph.
Importali.
Stesso strumento, seconda fase.
Plan.
Il plan mostra le differenze ancora presenti. Non tutti gli attributi possono essere esportati, quindi prima del primo plan pulito è normale attendersi una breve fase di pulizia.

Un oggetto alla volta

Per tutto ciò che l'export non copre, un piccolo script genera un file Terraform per un singolo oggetto di qualsiasi tipo di risorsa, dato il suo id. Usa la generazione di configurazione nativa di Terraform, quindi il file contiene esattamente ciò che il provider stesso legge dal tenant.

Il quickstart su GitHub

APP

Un'unica risorsa contiene l'app, il pacchetto e gli assignment

microsoft365wp_mobile_app copre 21 tipi di app. Per .intunewin, MSI, APPX/MSIX, DMG, PKG pacchetti il provider cifra il file e lo carica su Intune, operazione che viene ripetuta solo quando cambia source_sha256. Gli assignment si trovano nella stessa risorsa: tutti i dispositivi, tutti gli utenti con licenza, un gruppo o un gruppo di esclusione, ciascuno con un filtro di inclusione o esclusione.

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.

Dati di esempio.

Windows
Win32 (.intunewin), MSI, APPX/MSIX, Microsoft Store (nuovo, tramite WinGet), Microsoft Store (legacy), Microsoft Edge, Microsoft 365 Apps, web link.
macOS
DMG, PKG, Microsoft Edge, Microsoft Defender, Microsoft 365 Apps, web clip.
iOS e iPadOS
App dell'App Store, managed iOS store app, web clip.
Android
App del Google Play store, managed Google Play app, managed Android store app.
Qualsiasi piattaforma
Web link.

TENANT

Più tenant da un unico repository

Un blocco provider si autentica su un solo tenant. Per più tenant, dichiara un blocco per ciascuno con un alias e il relativo tenant_id, scrivi la baseline come modulo e chiamala una volta per ogni tenant. Ogni blocco si autentica in modo indipendente, quindi ogni tenant può avere il proprio service principal con i propri permessi.

Le differenze tra tenant diventano variabili del modulo, visibili in fase di review.
Aggiungere un nuovo tenant richiede un blocco provider, una chiamata al modulo e un 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}

Dati di esempio.

Come gestisce il throttling di Graph

Microsoft Graph limita il numero di richieste che un client può inviare, e un plan su un tenant di grandi dimensioni ne genera molte. Il provider attende e riprova autonomamente.

Retry

Retry per richiesta: fino a 10
Attesa tra i retry: da 3 a 60 secondi
Un Retry-After pari a zero: Esteso al backoff, perché Graph risponde spesso così e un retry immediato raramente risolve

Inizia con il quickstart.

Clonalo, puntalo su un tenant di test ed esegui un plan. La Community Edition è gratuita per le organizzazioni con un massimo di 99 utenti.

Apri la guida rapida Apri la documentazione

Configura TerraProvider nel tuo tenant e nella tua pipeline.

Il tuo primo plan in quattro passi

Registra un'app in Entra ID.

Concedi i permessi Graph.

Dichiara il provider.

Plan.

I permessi Graph richiesti

Le stesse impostazioni di autenticazione del provider azuread

Quattro cloud

Environment

Cosa monitora il plan

Esporta e importa un tenant esistente in due fasi

Esporta gruppi, filtri e template di notifica.

Importali.

Esporta le policy di compliance e configurazione.

Importali.

Plan.

Un oggetto alla volta

Un'unica risorsa contiene l'app, il pacchetto e gli assignment

Windows

macOS

iOS e iPadOS

Android

Qualsiasi piattaforma

Più tenant da un unico repository

Come gestisce il throttling di Graph

Retry

Inizia con il quickstart.