From 8a5bb41a75c05699bd14e0ba1cd83558f35145e7 Mon Sep 17 00:00:00 2001 From: Tom Bamford Date: Wed, 16 Jun 2021 14:37:38 +0100 Subject: [PATCH] Prepare v2.0 Migration Guide for release --- docs/guides/microsoft-graph.md | 174 +++++++++++++++++++++++---------- 1 file changed, 122 insertions(+), 52 deletions(-) diff --git a/docs/guides/microsoft-graph.md b/docs/guides/microsoft-graph.md index 0448de1e08..df43d7f489 100644 --- a/docs/guides/microsoft-graph.md +++ b/docs/guides/microsoft-graph.md @@ -5,11 +5,11 @@ subcategory: "Upgrade Guides" # AzureAD v2.0 and Microsoft Graph -From version 2.0 the AzureAD provider will use [Microsoft Graph](https://docs.microsoft.com/en-us/graph/overview) to connect to Azure Active Directory and will cease to connect using the [Azure Active Directory Graph API](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-graph-api). +From version 2.0 the AzureAD provider exclusively uses [Microsoft Graph](https://docs.microsoft.com/en-us/graph/overview) to connect to Azure Active Directory and has ceased to support using the [Azure Active Directory Graph API](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-graph-api). -Due to differences between the two APIs, some schema deprecations have already been introduced and several fields will be renamed, removed or otherwise changed. Please consult the following guide to determine any configuration changes you will need to make in order to upgrade to the upcoming version 2.0. +Due to differences between the two APIs, some schema deprecations have already been introduced prior to v2.0 and several fields have been renamed, removed or otherwise changed in v2.0. Please consult the following guide to determine any configuration changes you will need to make in order to upgrade to version 2.0. -We take semantic versioning very seriously which is why these changes are being introduced in a new major version of the provider. You can read up the background behind the API migration and proposed development path in [this GitHub issue](https://github.com/hashicorp/terraform-provider-azuread/issues/323), and follow along with the work being done for v2.0 in the [GitHub milestone](https://github.com/hashicorp/terraform-provider-azuread/milestone/16) +We take semantic versioning very seriously which is why these changes have been introduced in a new major version of the provider. You can read up the background behind the API migration and proposed development path in [this GitHub issue](https://github.com/hashicorp/terraform-provider-azuread/issues/323), and follow along with the work being done for v2.0 in the [GitHub milestone](https://github.com/hashicorp/terraform-provider-azuread/milestone/16) In version 1.5.0 or later of the AzureAD provider, limited beta support for Microsoft Graph can be enabled. See [Beta support for Microsoft Graph](#beta-support-for-microsoft-graph-in-v150) for more details. @@ -24,7 +24,7 @@ terraform { required_providers { azuread = { source = "hashicorp/azuread" - version = "= 1.5.0" + version = "= 1.5.1" } } } @@ -56,7 +56,9 @@ This will enable you to upgrade to version 2.0 at your convenience, by simply ad Existing authentication methods will continue to work unchanged, whether you authenticate with a service principal ([client certificate](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/guides/service_principal_client_certificate) or [client secret](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/guides/service_principal_client_secret)), [managed identity](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/guides/managed_service_identity), or using [Azure CLI](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/guides/azure_cli). -For users connecting to national clouds (e.g. germany, china and usgovernment), these are all supported using the existing provider configuration property `environment`, or the environment variable `ARM_ENVIRONMENT`. The usgovernment environment has been split into two environments usgovernmentl4 and usgovernmentl5 - see [this post](https://developer.microsoft.com/en-us/office/blogs/new-microsoft-graph-endpoints-in-us-government-cloud/) for more information. Specifying the `usgovernment` environment will use the `usgovernmentl4` cloud. +However, you may need to assign new API permissions depending on your configuration and authentication scenario. + +For users connecting to national clouds (e.g. germany, china and usgovernment), these are all supported using the existing provider configuration property `environment`, or the environment variable `ARM_ENVIRONMENT`. The "usgovernment" environment has been split into two environments "usgovernmentl4" and "usgovernmentl5" - see [this post](https://developer.microsoft.com/en-us/office/blogs/new-microsoft-graph-endpoints-in-us-government-cloud/) for more information. Specifying the "usgovernment" environment will use the "usgovernmentl4" cloud. ## New API permissions @@ -68,7 +70,7 @@ Microsoft Graph is a different web service to Azure Active Directory Graph, and If you are using directory roles to assign effective permissions to your authenticated principal, you may not necessarily need to assign new API permissions. -Whilst assigning directory roles is the recommended approach for user principals, if you are authenticating using a service principal, we recommend assigning permissions using app roles as detailed below. Note that this differs from our advice for earlier v1.x releases, where we recommend the use of directory roles for service principals due to bugs previously encountered with Azure Active Directory Graph that do not occur with Microsoft Graph. +Whilst assigning directory roles is the recommended approach for user principals, if you are authenticating using a service principal, we recommend assigning permissions using app roles as detailed below. Note that this differs from our advice for earlier (v0.x and v1.x) releases, where we recommend the use of directory roles for service principals due to bugs previously encountered with Azure Active Directory Graph that do not occur with Microsoft Graph. ### Assigning new API permissions for a service principal @@ -76,7 +78,7 @@ To assign permissions to your Application for use with Service Principal authent Go to the API Permissions pane for the Application and click the "Add a permission" button. In the pane that opens, select **Microsoft Graph**. -Choose "Application Permissions" for the permission type, and check the permissions you would like to assign. The permissions you need will depend on which directory objects you wish to manage with Terraform. The following table shows the required permissions by resource: +Choose "Application Permissions" for the permission type, and check the permissions you would like to assign. The permissions you need will depend on which directory objects you wish to manage with Terraform. The following table shows the required permissions by each resource: Resource(s) | Role Name(s) -------- | --------------- @@ -90,125 +92,137 @@ Resource(s) | Role Name(s) Depending on the configuration of your AAD tenant, you may also need to grant the Directory.Read.All and/or Directory.ReadWrite.All roles. -After assigning permissions, you will need to grant consent for the service principal to utilise them. The easiest way to do this is by clicking the Grant Admin Consent button in the same API Permissions pane. +After assigning permissions, you will need to grant consent for the service principal to utilise them. The easiest way to do this is by clicking the Grant Admin Consent button in the same API Permissions pane, which will create the necessary app role assignments for the Service Principal. + +## New required fields + +### Resource: `azuread_group` + +The `mail_enabled` and `security_enabled` fields are no longer read-only, and at least one of these fields must be set to `true` in order to create a new group. ## Removal of deprecated fields -The following attributes/properties have been deprecated in the AzureAD provider, and will be removed in version 2.0. +The following attributes/properties have been deprecated in the AzureAD provider, and has been removed in version 2.0. ~> **Compatibility Note** You will need to update your Terraform configuration in the latest v1.x release to use the new fields, prior to upgrading to 2.0. +### Provider + +The deprecated field `metadata_host` is no longer used and has been removed. + ### Data source: `azuread_application` -The deprecated field `name` has been replaced by the `display_name` field and will be removed. +The deprecated field `name` has been replaced by the `display_name` field and has been removed. -The deprecated field `is_enabled` in the `app_roles` block has been replaced by the `enabled` field and will be removed. +The deprecated field `is_enabled` in the `app_roles` block has been replaced by the `enabled` field and has been removed. -The deprecated field `available_to_other_tenants` has been replaced by the `sign_in_audience` field and will be removed. +The deprecated field `available_to_other_tenants` has been replaced by the `sign_in_audience` field and has been removed. -The deprecated field `homepage` has been replaced by the `homepage_url` field in the `web` block and will be removed. +The deprecated field `homepage` has been replaced by the `homepage_url` field in the `web` block and has been removed. -The deprecated field `logout_url` has been replaced by the `logout_url` field in the `web` block and will be removed. +The deprecated field `logout_url` has been replaced by the `logout_url` field in the `web` block and has been removed. -The deprecated field `oauth2_allow_implicit_flow` has been replaced by the `access_token_issuance_enabled` field in the `implicit_grant` block and will be removed. +The deprecated field `oauth2_allow_implicit_flow` has been replaced by the `access_token_issuance_enabled` field in the `implicit_grant` block and has been removed. -The deprecated `oauth2_permissions` block has been replaced by the `oauth2_permission_scopes` block within the `api` block and will be removed. +The deprecated `oauth2_permissions` block has been replaced by the `oauth2_permission_scopes` block within the `api` block and has been removed. -The deprecated field `reply_urls` has been replaced by the `redirect_uris` field in the `web` block and will be removed. +The deprecated field `reply_urls` has been replaced by the `redirect_uris` field in the `web` block and has been removed. -The legacy `type` field is deprecated and will be removed. +The legacy `type` field is deprecated and has been removed. ### Data source: `azuread_group` -The deprecated field `name` has been replaced by the `display_name` field and will be removed. +The deprecated field `name` has been replaced by the `display_name` field and has been removed. ### Data source: `azuread_groups` -The deprecated field `names` has been replaced by the `display_names` field and will be removed. +The deprecated field `names` has been replaced by the `display_names` field and has been removed. ### Data source: `azuread_user` -The deprecated field `immutable_id` has been replaced by the `onpremises_immutable_id` field and will be removed. +The deprecated field `immutable_id` has been replaced by the `onpremises_immutable_id` field and has been removed. -The deprecated field `physical_delivery_office_name` has been replaced by the `office_location` field and will be removed. +The deprecated field `physical_delivery_office_name` has been replaced by the `office_location` field and has been removed. -The deprecated field `mobile` has been replaced by the `mobile_phone` field and will be removed. +The deprecated field `mobile` has been replaced by the `mobile_phone` field and has been removed. ### Data source: `azuread_users` -The deprecated field `immutable_id` in the `users` block has been replaced by the `onpremises_immutable_id` field and will be removed. +The deprecated field `immutable_id` in the `users` block has been replaced by the `onpremises_immutable_id` field and has been removed. ### Resource: `azuread_application` -The deprecated field `name` has been replaced by the `display_name` field and will be removed. +The deprecated field `name` has been replaced by the `display_name` field and has been removed. -The deprecated field `is_enabled` in the `app_role` block has been replaced by the `enabled` field and will be removed. +The deprecated field `is_enabled` in the `app_role` block has been replaced by the `enabled` field and has been removed. -The deprecated field `available_to_other_tenants` has been replaced by the `sign_in_audience` field and will be removed. +The deprecated field `available_to_other_tenants` has been replaced by the `sign_in_audience` field and has been removed. -The deprecated field `homepage` has been replaced by the `homepage_url` field in the `web` block and will be removed. +The deprecated field `homepage` has been replaced by the `homepage_url` field in the `web` block and has been removed. -The deprecated field `logout_url` has been replaced by the `logout_url` field in the `web` block and will be removed. +The deprecated field `logout_url` has been replaced by the `logout_url` field in the `web` block and has been removed. -The deprecated field `oauth2_allow_implicit_flow` has been replaced by the `access_token_issuance_enabled` field in the `implicit_grant` block and will be removed. +The deprecated field `oauth2_allow_implicit_flow` has been replaced by the `access_token_issuance_enabled` field in the `implicit_grant` block and has been removed. -The deprecated field `is_enabled` in the `app_role` block has been replaced by the `enabled` field and will be removed. +The deprecated field `is_enabled` in the `app_role` block has been replaced by the `enabled` field and has been removed. -The deprecated `oauth2_permissions` block has been replaced by the `oauth2_permission_scope` block within the `api` block and will be removed. +The deprecated `oauth2_permissions` block has been replaced by the `oauth2_permission_scope` block within the `api` block and has been removed. -> In the new `oauth2_permission_scope` block, the `is_enabled` field has been renamed to `enabled` and the `id` field is now **required**. See the [New required UUID fields](#new-required-uuid-fields) section below for more information. -The deprecated field `public_client` has been replaced by the `fallback_public_client_enabled` field and will be removed. +The deprecated field `public_client` has been replaced by the `fallback_public_client_enabled` field and has been removed. -The deprecated field `reply_urls` has been replaced by the `redirect_uris` field in the `web` block and will be removed. +The deprecated field `reply_urls` has been replaced by the `redirect_uris` field in the `web` block and has been removed. -The legacy `type` field is deprecated and will be removed. +The legacy `type` field is deprecated and has been removed. ### Resource: `azuread_application_app_role` -The deprecated field `is_enabled` has been replaced by the `enabled` field and will be removed. +The deprecated field `is_enabled` has been replaced by the `enabled` field and has been removed. ### Resource: `azuread_application_oauth2_permission` This resource has been renamed to `azuread_application_oauth2_permission_scope`. -The deprecated field `is_enabled` has been replaced by the `enabled` field and will be removed. +The deprecated field `is_enabled` has been replaced by the `enabled` field and has been removed. ### Resource: `azuread_application_password` -The deprecated field `description` has been replaced by the `display_name` field and will be removed. +The deprecated field `description` has been replaced by the `display_name` field and has been removed. -> The following also applies when the Microsoft Graph beta is enabled in version 1.5 or later -The `key_id` field will become read-only as Azure Active Directory no longer allows user-specified key IDs for passwords. This also means that the `azuread_application_password` resource no longer supports importing in version 2.0 of the provider. +The `key_id` field has become read-only as Azure Active Directory no longer allows user-specified key IDs for passwords. This also means that the `azuread_application_password` resource no longer supports importing in version 2.0 of the provider. -The `value` field will become read-only as Azure Active Directory no longer accepts user-supplied password values. Passwords will instead be auto-generated by Azure and will be exported as attributes by the resource. +The `value` field has become read-only as Azure Active Directory no longer accepts user-supplied password values. Passwords are instead auto-generated by Azure and exported with the `value` attribute by the resource. ### Resource: `azuread_group` -The deprecated field `name` has been replaced by the `display_name` field and will be removed. +The deprecated field `name` has been replaced by the `display_name` field and has been removed. ### Resource: `azuread_service_principal_password` -The deprecated field `description` has been replaced by the `display_name` field and will be removed. +The deprecated field `description` has been replaced by the `display_name` field and has been removed. -> The following also applies when the Microsoft Graph beta is enabled in version 1.5 or later -The `key_id` field will become read-only as Azure Active Directory no longer allows user-specified key IDs for passwords. This also means that the `azuread_service_principal_password` resource no longer supports importing in version 2.0 of the provider. +The `display_name`, `start_date` and `end_date` fields are no longer respected by the API and have been made read-only. Accordingly the `end_date_relative` field has been removed. + +The `key_id` field has become read-only as Azure Active Directory no longer allows user-specified key IDs for passwords. This also means that the `azuread_service_principal_password` resource no longer supports importing in version 2.0 of the provider. -The `value` field will become read-only as Azure Active Directory no longer accepts user-supplied password values. Passwords will instead be auto-generated by Azure and will be exported as attributes by the resource. +The `value` field has become read-only as Azure Active Directory no longer accepts user-supplied password values. Passwords are instead auto-generated by Azure and exported with the `value` attribute by the resource. ### Resource: `azuread_user` -The deprecated field `immutable_id` has been replaced by the `onpremises_immutable_id` field and will be removed. +The deprecated field `immutable_id` has been replaced by the `onpremises_immutable_id` field and has been removed. -The deprecated field `physical_delivery_office_name` has been replaced by the `office_location` field and will be removed. +The deprecated field `physical_delivery_office_name` has been replaced by the `office_location` field and has been removed. -The deprecated field `mobile` has been replaced by the `mobile_phone` field and will be removed. +The deprecated field `mobile` has been replaced by the `mobile_phone` field and has been removed. ## New required UUID fields -Several fields that were previously optional or read-only will be required in version 2.0. Currently, these fields are optionally (or always) autogenerated by the provider, as not all users need to be able to set these fields to specific values. +Several fields that were previously optional or read-only are now required in version 2.0. Currently, these fields are optionally (or always) autogenerated by the provider, as not all users need to be able to set these fields to specific values. In v2.0, you can achieve the same behaviour by using the [Random provider](https://registry.terraform.io/providers/hashicorp/random/latest/docs), for example: @@ -225,17 +239,73 @@ resource "azuread_application" "example" { } ``` -Requiring these properties will enable more predictable management of app roles and OAuth 2.0 permission scopes such that existing roles/scopes will not be overwritten to accommodate changes in an application's configuration. +Requiring these properties will enable more predictable and less disruptive management of app roles and OAuth 2.0 permission scopes such that existing roles/scopes will not be disabled or overwritten to accommodate changes in an application's configuration. ### Resource: `azuread_application` -The `id` field in the `app_role` block is currently Computed (read-only) but will be Required. +The `id` field in the `app_role` block was previously currently Computed (read-only) but is now Required. + +The `id` field in the deprecated `oauth2_permissions` block was previously Computed (read-only) but its replacement field `id` in the `oauth2_permission_scope` block is Required. + +## Computed fields + +In previous version of the provider, many fields were introduced as Optional + Computed fields. This meant that omitting such fields would cause Terraform to ignore them and not attempt to manage them. However, this approach has many side effects including the inability to unset or clear these fields, and sometimes being forced to accept an undesired default value. + +To resolve these issues, many of these fields are no longer Computed in version 2.0 of the provider. This means that Terraform will manage these fields and if you do not specify their values in your configuration, they will be unset or set to their zero values. It's also appropriate in some cases for a field to be Computed, particularly where it helps prevent disruption to services or users. + +Accordingly, in version 2.0 of the provider the following fields have changed. + +### Resource: `azuread_application` + +The `app_role` block is no longer Computed, omitting this block will cause Terraform to remove any app roles published by an application. + +The `value` field in the `app_role` block is no longer Computed, omitting this field will cause Terraform to clear this field for an app role. + +The `fallback_public_client_enabled` field is no longer Computed, omitting this field will cause Terraform to default this value to `false`. + +The `identifier_uris` field is no longer Computed, omitting this field will cause Terraform to remove any identifier URIs configured for an application. + +The `oauth2_permission_scope` block is no longer Computed, omitting this block will cause Terraform to remove any OAuth2 permission scopes published by an application. + +The `owners` field is no longer Computed, omitting this field will cause Terraform remove any owners for an application. It's recommended to specify the object ID of the authenticated principal running Terraform, to ensure sufficient permissions that the application can be subsequently updated. + +The `sign_in_audience` field is no longer Computed, omitting this field will cause Terraform to default this value to `AzureADMyOrg`. + +The `web` block is no longer Computed, omitting this field will cause Terraform to remove all field values contained in this block, including the `homepage_url`, `logout_url`, `redirect_uris` and `access_token_issuance_enabled` fields. + +## Resource: `azuread_user` + +The `password` field is now Optional + Computed, which makes it possible to import existing users without forcibly resetting their password. + +The `city` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `company_name` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `country` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `department` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `given_name` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `job_title` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `mobile_phone` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `office_location` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `postal_code` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `state` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `street_address` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. + +The `surname` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. -The `id` field in the deprecated `oauth2_permissions` block is currently Computed (read-only) but its replacement field `id` in the `oauth2_permission_scope` block will be Required. +The `usage_location` field is no longer Computed, omitting this field will cause Terraform to remove this value for a user. ### Avoiding diffs for already-published applications -In order to determine the value of a given UUID-type property where you had previously not defined one, you can use the `terraform state show` command to inspect your existing application(s), and then add the current value to your configuration. +In order to determine the assigned value of a given UUID-type property where you had previously not defined one, you can use the `terraform state show` command to inspect your existing application(s), and then add the current value to your configuration. ```shell $ terraform state show azuread_application.example