작동 방식

테넌트와 파이프라인에 TerraProvider를 설정하세요.

TerraProvider를 설정하는 엔지니어가 알아야 할 것들: 로그인 방식, 요청하는 권한, 첫 번째 플랜의 모습, 그리고 기존 테넌트를 코드로 관리하는 방법.

terraprovider/microsoft365wp
Terraform and OpenTofu
10개 빌드
버전 0.20.2

설정

4단계로 완성하는 첫 번째 플랜

다른 Azure 프로바이더 설정과 비슷한 수준으로, 로그인 방식이 동일하기 때문입니다.

Entra ID에 앱을 등록합니다.
단일 테넌트, 리디렉션 URI는 필요하지 않습니다. 애플리케이션(클라이언트) ID와 디렉터리(테넌트) ID를 기록해 두세요.
Microsoft Graph 권한을 부여합니다.
관리할 개체에 대한 애플리케이션 권한을 추가하고(아래 표 참조) 관리자 동의를 부여합니다.
03
프로바이더를 선언합니다.
ARM_TENANT_ID와 ARM_CLIENT_ID를 설정하고, 첫 번째 테스트에는 ARM_CLIENT_SECRET도 추가하세요. 파이프라인에서는 대신 OpenID Connect를 사용하세요(아래 참조).
main.tf
```
terraform {  required_providers {    microsoft365wp = {      source = "terraprovider/microsoft365wp"    }  }}provider "microsoft365wp" {}
```

플랜을 실행합니다.

리소스를 하나 작성하고(예: 컴플라이언스 정책), terraform plan 또는 tofu plan을 실행하세요. 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 = {} }  }]}

예시 데이터입니다.

권한

요청하는 Microsoft Graph 권한

관리자 동의가 필요한 애플리케이션 권한입니다. 실제로 관리하는 개체에 해당하는 권한만 부여하세요. 여기에 나열되지 않은 리소스는 해당 문서 페이지에서 필요한 권한을 확인할 수 있습니다.

요청하는 Microsoft Graph 권한
권한	허용 범위
DeviceManagementConfiguration.ReadWrite.All	Intune 디바이스 구성 및 정책
DeviceManagementApps.ReadWrite.All	Intune 앱
DeviceManagementServiceConfig.ReadWrite.All	Intune 서비스 구성(예: 등록)
Policy.ReadWrite.ConditionalAccess	조건부 액세스 정책
Policy.Read.All	조직 정책 읽기
Application.ReadWrite.All	애플리케이션
Directory.ReadWrite.All	디렉터리 데이터
Group.ReadWrite.All	그룹
User.ReadWrite.All	사용자 전체 프로필
CloudPC.ReadWrite.All	Windows 365 구성

출처: 프로바이더 가이드 "Configuring a Service Principal for managing EntraID".

로그인

azuread 프로바이더와 동일한 로그인 설정

프로바이더는 azuread 프로바이더와 동일한 ARM_* 설정을 읽습니다. ARM_TENANT_ID와 ARM_CLIENT_ID를 설정한 후 인증 방법을 선택하세요.

azuread 프로바이더와 동일한 로그인 설정
방법	적합한 상황	활성화 방법
OpenID Connect, GitHub Actions	저장된 시크릿 없이 실행되는 워크플로	`ARM_USE_OIDC=true`
OpenID Connect, Azure DevOps	서비스 연결이 있는 파이프라인	`ARM_USE_OIDC=true` `ARM_ADO_PIPELINE_SERVICE_CONNECTION_ID`
OpenID Connect, any issuer	ID 토큰을 발급하는 기타 CI 시스템	`ARM_USE_OIDC=true` `ARM_OIDC_TOKEN / ARM_OIDC_TOKEN_FILE_PATH`
Client certificate	인증서를 보유한 러너	`ARM_CLIENT_CERTIFICATE / ARM_CLIENT_CERTIFICATE_PATH`
Client secret	초기 테스트, 랩 환경	`ARM_CLIENT_SECRET / ARM_CLIENT_SECRET_FILE_PATH`
Managed identity	Azure에서 실행되는 러너	`ARM_USE_MSI=true`
AKS workload identity	Azure의 Kubernetes에서 실행되는 러너	`ARM_USE_AKS_WORKLOAD_IDENTITY=true`
Azure CLI	로컬 노트북	기본적으로 활성화되어 있으며, `ARM_USE_CLI=false`로 비활성화할 수 있습니다.

각 설정은 프로바이더 인수(use_oidc, client_certificate_path 등)로도 지정할 수 있습니다. 프로바이더의 OpenID Connect 가이드에서 Entra ID가 GitHub 리포지토리를 신뢰하도록 구성하는 방법을 확인할 수 있습니다. 한 줄 요약: OpenID Connect(GitHub Actions, Azure DevOps, 모든 OIDC 토큰), 클라이언트 인증서, 클라이언트 시크릿, 관리 ID, AKS 워크로드 ID, Azure CLI.

4개의 클라우드

environment 또는 ARM_ENVIRONMENT를 설정하면 프로바이더가 해당 클라우드의 Microsoft Graph 엔드포인트에 연결합니다: 글로벌, US Government L4, US Government L5(DoD), 중국.

환경

global (also public): 상용 클라우드, 기본값
usgovernmentl4 (also usgovernment): US Government L4
usgovernmentl5 (also dod): US Government L5 (DoD)
china: 중국의 Microsoft 클라우드
사용자 지정 엔드포인트: metadata_host or ARM_METADATA_HOSTNAME

드리프트

플랜이 감시하는 것

Terraform은 작성한 구성과 테넌트가 보고하는 실제 상태를 비교합니다. TerraProvider는 이 비교를 개체 전체로 확장합니다. 설정하지 않은 모든 속성에는 기본값이 적용되는데, 이 기본값은 Microsoft 포털에서 동일한 개체를 생성할 때 반환되는 값을 기준으로 합니다. 따라서 포털에서 정책에 추가된 제외 항목, Intune 관리 센터에서 변경된 토글, 스크립트로 수정된 설정은 파일에 명시되어 있든 아니든 다음 플랜에 나타납니다.

지정하지 않은 컬렉션은 기본적으로 빈 상태가 되므로, 추가된 멤버, 제외 항목 또는 앱이 플랜에 표시됩니다.
상태가 지정되지 않은 새 조건부 액세스 정책은 enabledForReportingButNotEnforced로 생성됩니다.
각 속성의 기본값은 리소스 문서 페이지에서 프로바이더 기본값으로 표시됩니다.

반대의 경우도 있습니다. 포털에서 켰다가 다시 끈 설정이 미설정 상태 대신 false로 돌아와 변경 사항으로 한 번 표시될 수 있습니다. apply를 한 번 실행하면 정리됩니다.

포털에서: 마지막 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"]  }}

예시 데이터.

기존 테넌트

기존 테넌트를 두 단계로 내보내고 가져오기

quickstart 리포지토리에는 모듈, GitHub Actions 워크플로, PowerShell 내보내기가 포함된 참조 구성이 있습니다. 정책이 그룹과 필터를 참조하기 때문에 내보내기는 두 단계로 진행됩니다.

그룹, 필터, 알림 템플릿을 내보냅니다.
각 유형별 매핑 파일과 함께 quickstart 모듈에 기록됩니다. 메일 사용 가능 그룹은 명시적으로 요청하지 않는 한 제외됩니다.
가져옵니다.
도구가 Terraform 또는 OpenTofu를 호출하여 내보낸 모든 개체를 상태로 가져옵니다.
컴플라이언스 정책과 구성 정책을 내보냅니다.
Settings catalog 및 엔드포인트 보안 정책은 구성 정책으로 분류됩니다. 각 내보내기에는 Microsoft Graph가 반환한 원시 JSON 덤프도 함께 저장됩니다.
가져옵니다.
동일한 도구, 두 번째 단계입니다.
플랜을 실행합니다.
플랜에는 아직 차이가 있는 항목이 표시됩니다. 모든 속성을 내보낼 수 있는 것은 아니므로, 첫 번째 클린 플랜 전에 간단한 정리 작업이 필요합니다.

개체 하나씩 처리하기

내보내기로 처리되지 않는 항목에 대해서는, 소형 스크립트가 지정한 id를 기반으로 임의의 리소스 유형에서 개체 하나에 대한 Terraform 파일을 생성합니다. Terraform 자체의 구성 생성 기능을 사용하므로, 파일에는 프로바이더가 테넌트에서 직접 읽은 값이 담깁니다.

GitHub의 quickstart

앱

하나의 리소스에 앱, 패키지, 할당을 모두 담기

microsoft365wp_mobile_app은 21가지 앱 유형을 지원합니다. .intunewin, MSI, APPX/MSIX, DMG, PKG가지 패키지 유형의 경우 프로바이더가 파일을 암호화하여 Intune에 업로드하며, source_sha256이 변경될 때만 다시 업로드합니다. 할당은 동일한 리소스 안에 포함되며, 모든 디바이스, 라이선스가 있는 모든 사용자, 그룹 또는 제외 그룹을 포함 또는 제외 필터와 함께 지정할 수 있습니다.

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.

예시 데이터.

Windows
Win32(.intunewin), MSI, APPX/MSIX, Microsoft Store(신규, WinGet 경유), Microsoft Store(레거시), Microsoft Edge, Microsoft 365 Apps, 웹 링크.
macOS
DMG, PKG, Microsoft Edge, Microsoft Defender, Microsoft 365 Apps, 웹 클립.
iOS 및 iPadOS
App Store 앱, 관리형 iOS 스토어 앱, 웹 클립.
Android
Google Play 스토어 앱, 관리형 Google Play 앱, 관리형 Android 스토어 앱.
모든 플랫폼
웹 링크.

테넌트

하나의 리포지토리에서 여러 테넌트 관리하기

프로바이더 블록 하나가 테넌트 하나에 로그인합니다. 여러 테넌트를 관리하려면 테넌트마다 별칭과 tenant_id를 지정한 블록을 선언하고, 베이스라인을 모듈로 작성하여 테넌트별로 한 번씩 호출하세요. 각 블록은 독립적으로 로그인하므로, 테넌트마다 고유한 권한을 가진 서비스 주체를 사용할 수 있습니다.

테넌트 간 차이는 모듈 변수로 표현되며, 리뷰 단계에서 확인할 수 있습니다.
새 테넌트를 추가하려면 프로바이더 블록 하나, 모듈 호출 하나, 플랜 하나면 충분합니다.

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}

예시 데이터.

Microsoft Graph 스로틀링 처리 방식

Microsoft Graph는 클라이언트가 보낼 수 있는 요청 수를 제한하며, 대형 테넌트에 대한 플랜은 요청이 많습니다. 프로바이더는 자체적으로 대기하고 재시도합니다.

재시도

요청당 재시도 횟수: 최대 10회
재시도 간격: 3~60초
Retry-After가 0인 경우: 백오프 값으로 늘려 처리합니다. Graph가 이 방식으로 응답하는 경우가 많으며, 즉시 재시도는 거의 효과가 없기 때문입니다.

quickstart부터 시작하세요.

리포지토리를 클론하고 테스트 테넌트에 연결한 후 플랜을 실행하세요. Community Edition은 사용자 수 99명 이하 조직에 무료로 제공됩니다.

빠른 시작 열기 문서 열기

테넌트와 파이프라인에 TerraProvider를 설정하세요.

4단계로 완성하는 첫 번째 플랜

Entra ID에 앱을 등록합니다.

Microsoft Graph 권한을 부여합니다.

프로바이더를 선언합니다.

플랜을 실행합니다.

요청하는 Microsoft Graph 권한

azuread 프로바이더와 동일한 로그인 설정

4개의 클라우드

환경

플랜이 감시하는 것

기존 테넌트를 두 단계로 내보내고 가져오기

그룹, 필터, 알림 템플릿을 내보냅니다.

가져옵니다.

컴플라이언스 정책과 구성 정책을 내보냅니다.

가져옵니다.

플랜을 실행합니다.

개체 하나씩 처리하기

하나의 리소스에 앱, 패키지, 할당을 모두 담기

Windows

macOS

iOS 및 iPadOS

Android

모든 플랫폼

하나의 리포지토리에서 여러 테넌트 관리하기

Microsoft Graph 스로틀링 처리 방식

재시도

quickstart부터 시작하세요.