Terraform Provider
Manage governed Microsoft Entra application registrations as code through the dedicated AZExecute Terraform API. The provider supports tenant approval, metadata policy, API-permission requests, selected registration settings, import, drift reads, and controlled deletion without bypassing AZExecute governance.
What You Can Manage
Application requests and lifecycle
Submit idempotent application requests, track PendingApproval, Provisioning, NeedsAttention, Ready, and Rejected, read Entra identifiers after provisioning, import existing Terraform-managed requests, and delete resources when tenant policy allows it.
Tenant-controlled metadata
Manage business justification, project and department ownership, environment, criticality, intended audience, go-live date, technical and data requirements, compliance notes, elevated-permission context, and contact details.
Registration configuration
Manage sign-in audience, identifier URIs, web, SPA and public-client redirect URIs, home and logout URLs, implicit token issuance, fallback public-client behavior, and requested access-token version.
API-permission requests
Submit external API or internal AZExecute application requests for app roles, delegated scopes, or authorized-client access. Permission handling follows the tenant's separate Terraform permission approval setting.
Policy and application reads
Read the live Terraform capabilities, included and required metadata fields, approval settings, and an application's current request status and identifiers through provider data sources.
State-safe operations
Use stable provider-generated UUIDs for retry safety, import by that UUID, and migrate from the synchronous resource to the approval-aware resource without recreating the remote application.
Before You Begin
1. Assign the calling user or service principal User, Operator, or TenantAdmin on the customer tenant's AZExecute enterprise application.
2. In Tenant administration → Application Configuration → Terraform, enable the Terraform API and application creation.
3. Decide whether application creation and permission requests require their normal approval flows.
4. Configure the metadata fields that Terraform callers may use and which of those fields are required.
5. Enable registration configuration, API-permission requests, and application deletion only for workflows that need them.
A User identity can manage only Terraform resources it created. Operator and TenantAdmin identities can manage Terraform resources across the tenant. Terraform never grants a broader role.
Choose the Correct Resource
Use azexecute_application_request for new configurations. It supports both approval-based and automatic tenants. Both resources use the same AZExecute request and provisioning flow and manage the application after it becomes ready.
| Behavior | azexecute_application | azexecute_application_request (recommended) |
|---|---|---|
| Automatic provisioning | Supported | Supported |
| Tenant requires human approval | Refuses creation | Supported |
| Waits for provisioning | Always | Optional; returns immediately by default |
| Wait controls | poll_interval_seconds and create_timeout_minutes | Same controls, enabled by wait_for_completion = true |
| Manages the application after provisioning | Yes | Yes |
| Waits for downstream API approval or consent | No | No |
Optional request waiting requires provider 0.12.0 or later; it is not available in 0.11.7 or earlier. With wait_for_completion = true, create/update waits for approval and provisioning to reach Ready, polling every 5 seconds for up to 60 minutes by default. Terraform holds its state lock during that wait. Leave waiting disabled when approval happens outside the pipeline.
Neither resource approves requests or bypasses tenant policy. NeedsAttention and Rejected stop waiting and report the reason; failures and timeouts retain the request identity. Use azexecute_application only for automatic tenants that require its existing always-waiting behavior.
Approval and Repeated Pipeline Runs
1. Terraform plan reads the live tenant capabilities and validates the requested operations and metadata.
2. Apply submits one idempotent application request.
3. With the request resource's default asynchronous behavior, apply succeeds with PendingApproval, Provisioning, or Ready. Optional waiting keeps apply running until the request reaches a final outcome or the timeout expires.
4. A tenant administrator approves or rejects a pending request in AZExecute. Terraform cannot approve itself.
5. AZExecute provisions approved applications through its durable background workflow.
6. If apply returned before completion, refresh Terraform to read the final status and identifiers. AZExecute applies creation-time registration settings before reporting Ready; no second apply is required to provision those settings.
Dynamic Metadata Requirements
Only display_name is always required by the Terraform resource. All tenant-controlled metadata fields are optional in the provider schema. During planning, the provider reads the tenant's live required_metadata_fields and reports a clear error when a currently required value is missing. The API validates the same policy again before creating anything, so invalid input does not leave an approval request behind.
Use the azexecute_capabilities data source to inspect whether creation, deletion, permission requests, registration configuration and approval flows are enabled, and which metadata fields are included or required.
Authentication and CI/CD
The provider requests a token for https://api.azexecute.com/.default in the customer tenant. It supports a pre-acquired token, OIDC workload identity federation, certificates, client secrets, managed identity, Azure workload identity, Azure CLI, Azure Developer CLI, Azure PowerShell, and supported developer credentials.
For GitHub Actions and Azure DevOps, use workload identity federation. In Azure DevOps, an Azure Resource Manager service connection can expose a short-lived OIDC assertion to both the Azure Blob Terraform backend and the AZExecute provider. Each exchanges it for its own access token; no stored client secret or long-lived AZExecute token is needed.
Blob access on the state storage account and an AZExecute application role are separate requirements. One does not grant the other.
Permissions, Registration, and Boundaries
Permission requests
Terraform can request permissions for an external Microsoft Entra API by application/client ID or an internal AZExecute application by application entity UUID. Supported grant types are app role, delegated scope, and authorized client. The tenant decides whether those permission requests wait for normal approval or are applied automatically with configured tenant-admin authority.
Registration settings
Set configure_registration = true only when the tenant enables Terraform registration configuration. Registration updates occur after the application is ready and use concurrency protection to avoid overwriting unrelated changes.
Owners and drift
Set owner_object_ids to the complete desired set of customer-managed Entra owner object UUIDs. Terraform adds missing owners and removes AZExecute-managed owners that are no longer configured. Manual owner changes made in AZExecute appear in the next plan. Graph-only operational owners required by AZExecute are preserved. Registered automation identities for the original requester and current caller are maintained automatically and repaired during authorized updates. You may include them explicitly, but they are not required in this set and do not count toward the human-owner minimum. Use the matching updated API and provider to exclude implicit automation ownership from drift.
For modular ownership, omit owner_object_ids and use one azexecute_application_owner resource per owner. Choose inline, individual, or unmanaged ownership for each application; do not combine inline and individual modes. Terraform's standard lifecycle.ignore_changes can leave selected inline metadata, registration, owner, or permission-request fields under manual control.
Intentionally outside the provider
The provider does not manage app-role definitions, exposed OAuth scopes, pre-authorized client definitions, secrets, certificates, integrations, or tenant settings. Continue to manage those through the dedicated AZExecute experiences and workflows.
State, Import, Migration, and Destroy
• The provider generates a stable UUID and the API enforces it per tenant, making retries safe after timeouts or lost responses.
• Import uses the stable Terraform resource UUID, not an Entra client ID, object ID, numeric request ID, or AZExecute application entity UUID.
• A Terraform moved block can move from azexecute_application to azexecute_application_request without recreating the application.
• Destroying a pending or rejected request cancels it without application-deletion permission.
• Destroying a provisioned application requires Allow Application Deletion in the tenant Terraform settings.