DOCSEARCHbyAlgolia
Submit Docs

Terraform Provider for Azure Active Directory (AzureAD)

repository·main·Indexed 19 days ago

https://github.com/hashicorp/terraform-provider-azuread

The Terraform Provider for Azure Active Directory (AzureAD) enables the management of Azure AD resources, including applications, service principals, users, and domains, using Terraform configuration files. It supports authentication via Service Principals or the Azure CLI and provides resources such as azuread_application, azuread_service_principal, and azuread_user, as well as data sources like azuread_access_package_catalog.

Tokens
98.1K
Snippets
248
Records
468
Agent score
66%

What's inside terraform-provider-azuread

  1. Manage Azure AD Access Package Assignment Policies

    main

    The azuread_access_package_assignment_policy resource manages assignment policies for an access package within Azure Active Directory Identity Governance. These policies define how users request access, who approves requests, and how access is reviewed periodically.

    resource "azuread_access_package_assignment_policy" "example" {
  access_package_id = azuread_access_package.example.id
  display_name      = "assignment-policy"
  description       = "My assignment policy"
  duration_in_days  = 90

  requestor_settings {
    scope_type = "AllExistingDirectoryMemberUsers"
  }

  approval_settings {
    approval_required = true

    approval_stage {
      approval_timeout_in_days = 14

      primary_approver {
        object_id    = azuread_group.example.object_id
        subject_type = "groupMembers"
      }
    }
  }

  assignment_review_settings {
    enabled                        = true
    review_frequency               = "weekly"
    duration_in_days               = 3
    review_type                    = "Self"
    access_review_timeout_behavior = "keepAccess"
  }

  question {
    text {
      default_text = "hello, how are you?"
    }
  }
}

  2. What is a Managed Identity?

    main

    Managed identities allow Azure resources to authenticate to Azure Active Directory without storing credentials on the resource itself. They work via the Azure Instance Metadata Service (IMDS) endpoint, which the client uses to request access tokens.

    There are two types of managed identities:

    1. System-assigned: Tied to the lifecycle of a specific resource. It is created when the resource is created and automatically removed when the resource is deleted.
    2. User-assigned: A standalone identity resource that can be allocated to one or more resources.

    Limitations:

    • You can only manage resources in the tenant where the corresponding service principal is homed. For multi-tenant management, use Service Principal authentication with a client certificate or client secret instead.
    • Not all Azure services support managed identities.

  3. Configure the azuread_invitation message block

    main

    The message block allows you to customize the invitation email sent to the user. If this block is omitted, no message is sent.

    Important Constraints:

    • You can specify either language OR body, but not both.
    • additional_recipients supports only 1 additional recipient per Azure limitations.

    Arguments:

    • additional_recipients (Optional): A list of email addresses to receive the invitation message.
    • body (Optional): A custom message body. Cannot be used with language.
    • language (Optional): The ISO 639 language code for the default message (e.g., en-US). Cannot be used with body.
    resource "azuread_invitation" "example" {
  user_email_address = "bbobson@hashicorp.com"
  redirect_url       = "https://portal.azure.com"

  message {
    additional_recipients = ["aaliceberg@hashicorp.com"]
    body                  = "Hello there! You are invited to join my Azure tenant!"
  }
}

  4. Manage application identifier URIs with azuread_application_identifier_uri

    main

    The azuread_application_identifier_uri resource manages a single Identifier URI for an application registration.

    Important: Avoiding Conflicts with azuread_application

    This resource is analogous to the identifier_uris property within the azuread_application resource. If you manage identifier URIs using both the azuread_application resource and this standalone resource, you must use the ignore_changes lifecycle meta-argument on the azuread_application resource to prevent Terraform from attempting to revert changes made by this resource.

    Required API Permissions

    Depending on your authentication method, the following permissions are required:

    Service Principal Authentication: Requires one of the following application roles:

    • Application.ReadWrite.OwnedBy (The principal must also be an owner of the application)
    • Application.ReadWrite.All

    User Principal Authentication: Requires one of the following directory roles:

    • Application Administrator
    • Global Administrator
    resource "azuread_application" "example" {
  display_name = "example"

  lifecycle {
    ignore_changes = [
      identifier_uris,
    ]
  }
}

resource "azuread_application_identifier_uri" "example" {
  application_id = azuread_application.example.id
  identifier_uri = "https://app.example.com"
}

  5. Manage API permissions with azuread_application_api_access

    main

    The azuread_application_api_access resource manages the API permissions (roles and scopes) for an application registration.

    Relationship with azuread_application

    This resource is functionally analogous to the required_resource_access block within the azuread_application resource. To avoid configuration conflicts when using both, you must use the Terraform lifecycle meta-argument to ignore_changes on the required_resource_access attribute of the azuread_application resource.

    Required Permissions

    Depending on your authentication method, the following permissions are required:

    • Service Principal: Requires the Application.ReadWrite.OwnedBy or Application.ReadWrite.All application roles. If using Application.ReadWrite.OwnedBy, the principal must be an owner of the application.
    • User Principal: Requires the Application Administrator or Global Administrator directory roles.
    resource "azuread_application" "example" {
  display_name = "example"

  lifecycle {
    ignore_changes = [
      required_resource_access,
    ]
  }
}

resource "azuread_application_api_access" "example" {
  application_id = azuread_application.example.id
  # ...
}

  6. Manage Group ownership requirements

    main

    Due to Microsoft Graph constraints, Microsoft 365 groups must have at least one owner that is a user principal (not a service principal).

    When managing groups in Terraform, you should explicitly assign at least one user as an owner. This requirement may also affect newly created 'traditional' security groups. If managing groups with a user principal, it is recommended to assign the directory role Groups Administrator.

  7. Understand the structure of a Service Package

    main

    Each Service Package within the SDK is composed of several key components designed to work together in a strongly-typed fashion:

    • Client: A reference to the SDK Client used for interacting with Azure.
    • ID Parsers, Formatters, and/or Validators: Components that provide a canonical ID for each Resource.
    • Validation functions: Service-specific validation logic (e.g., validating a Name).

    By tying these components together, the SDK enforces several conventions to prevent common bugs:

  8. Manage application owners with azuread_application_owner

    main

    The azuread_application_owner resource manages a single owner for an application registration.

    Important Compatibility Note: This resource is incompatible with the azuread_application resource. You must use it in conjunction with the azuread_application_registration resource instead.

    resource "azuread_application_registration" "example" {
  display_name = "example"
}

resource "azuread_user" "jane" {
  user_principal_name = "jane.fischer@example.com"
  display_name        = "Jane Fischer"
  password            = "Ch@ngeMe"
}

resource "azuread_application_owner" "example_jane" {
  application_id  = azuread_application_registration.example.id
  owner_object_id = azuread_user.jane.object_id
}

  9. Handling passwords for azuread_user

    main

    When managing users with Terraform, keep the following password behaviors in mind:

    • Changing vs Clearing: Passwords can be changed, but they cannot be cleared. Removing the password argument or setting it to a blank string will not remove the password from the user.
    • Importing: When importing an existing user, Terraform will not reset the password unless you explicitly change the value in your configuration.

  10. Activate an Azure AD Directory Role

    main

    The azuread_directory_role resource is used to activate built-in Directory Roles (also known as Administrator Roles) within an Azure Active Directory tenant.

    Important Lifecycle Note: Directory Roles are immutable and built-in. By default, most roles are not activated in a tenant (except for the Global Administrator role). This resource ensures a role is activated from its associated template. Once a role is activated, it cannot be deactivated; therefore, this resource performs no actions on destroy.

    resource "azuread_directory_role" "example" {
  template_id = "00000000-0000-0000-0000-000000000000"
}

  11. Understanding the use_existing argument

    main

    The use_existing argument is useful for managing service principals that are already present in your tenant (e.g., Microsoft-published APIs).

    • When true: Terraform will automatically import any existing service principal linked to the same application. This allows you to manage them via Terraform.
    • When false: Terraform will raise an error if a service principal already exists.

    Caveat on Deletion: When use_existing is true, Terraform will still attempt to delete the service principal on destroy. However, it will not raise an error if the deletion fails (which is common for first-party Microsoft applications).

  12. Understand the structure of app_roles and oauth2_permission_scopes

    main

    When using azuread_service_principal, the exported app_roles and oauth2_permission_scopes lists contain detailed objects:

    app_roles attributes:

    • id: Unique identifier of the app role.
    • value: The value used for the roles claim in ID tokens and OAuth 2.0 access tokens.
    • allowed_member_types: Can be User, Application, or both.
    • display_name and description: Metadata for assignment and consent.
    • enabled: Boolean indicating if the role is active.

    oauth2_permission_scopes attributes:

    • id: Unique identifier of the delegated permission.
    • value: The value used for the scp claim in OAuth 2.0 access tokens.
    • type: Indicates if consent requires an administrator (Admin) or can be granted by a user (User).
    • admin_consent_display_name / user_consent_display_name: Display names for different consent experiences.
    • admin_consent_description / user_consent_description: Descriptions for different consent experiences.
    • enabled: Boolean indicating if the scope is active.