Merge pull request #373 from hashicorp/feature/enable-microsoft-graph

Initial support for Microsoft Graph with opt-in beta

.gitattributes

@@ -0,0 +1,2 @@
+# Do not mangle vendored files
+vendor/** -text

.gitignore

@@ -39,3 +39,6 @@ website/vendor
 
 # built binary
 terraform-provider-azuread
+
+# terraform version
+.terraform-version

CHANGELOG.md

@@ -1,5 +1,11 @@
 ## 1.5.0 (Unreleased)
 
+NOTES:
+
+* **Support for Microsoft Graph:** This release introduces beta support for [Microsoft Graph](https://docs.microsoft.com/en-us/graph/overview) in a way that is forward (and backward) compatible with the current [Azure Active Directory Graph](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-graph-api) API implementation. We do not recommend enabling this beta _in production_ at this time, but encourage you to try it out in test environments where minimal impact can occur if something doesn't work as expected. See the [Migration Guide](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/guides/microsoft-graph#beta-support-for-microsoft-graph-in-v150) for more details.
+
+* **Deprecations:** This release contains a number of additional deprecations to aid in future upgrades to version 2.0 of this provider. These will be flagged when running Terraform, and are documented in detail in the [Migration Guide](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/guides/microsoft-graph). Existing configurations will continue to work unchanged for any v1.x release, regardless of which API is used.
+
 IMPROVEMENTS:
 
 * `data.azuread_user` - export the `user_type` attribute [GH-406]

GNUmakefile

@@ -100,7 +100,7 @@ docs-lint:
 	@echo "==> Checking documentation spelling..."
 	@misspell -error -source=text -i hdinsight -locale UK docs/
 	@echo "==> Checking documentation for errors..."
-	@tfproviderdocs check -provider-name=azuread -allowed-guide-subcategories=Authentication -enable-contents-check -require-schema-ordering -require-guide-subcategory -require-resource-subcategory
+	@tfproviderdocs check -provider-name=azuread -allowed-guide-subcategories="Authentication,Upgrade Guides" -enable-contents-check -require-schema-ordering -require-guide-subcategory -require-resource-subcategory
 	@sh -c "'$(CURDIR)/scripts/terrafmt-docs.sh'"
 
 teamcity-test:

docs/data-sources/application.md

@@ -22,31 +22,36 @@ output "azure_ad_object_id" {
 
 ## Argument Reference
 
-* `application_id` - (Optional) Specifies the Application ID of the Azure Active Directory Application.
-* `display_name` - (Optional) Specifies the display name of the Application within Azure Active Directory.
-* `object_id` - (Optional) Specifies the Object ID of the Application within Azure Active Directory.
+* `application_id` - (Optional) Specifies the Application ID (also called Client ID).
+* `display_name` - (Optional) Specifies the display name of the application.
+* `object_id` - (Optional) Specifies the Object ID of the application.
 
 ~> **NOTE:** One of `object_id`, `application_id` or `display_name` must be specified.
 
 ## Attributes Reference
 
 The following attributes are exported:
 
-* `app_roles` - A collection of `app_role` blocks as documented below. For more information https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles
-* `application_id` - the Application ID of the Azure Active Directory Application.
-* `available_to_other_tenants` - Is this Azure AD Application available to other tenants?
+* `api` - An `api` block as documented below.
+* `app_roles` - A collection of `app_role` blocks as documented below. For more information see [official documentation on Application Roles](https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles).
+* `application_id` - the Application ID (also called Client ID).
+* `available_to_other_tenants` - (**Deprecated**) Is this Azure AD Application available to other tenants?
+* `display_name` - The display name for the application.
+* `fallback_public_client_enabled` - The fallback application type as public client, such as an installed application running on a mobile device.
 * `group_membership_claims` - The `groups` claim issued in a user or OAuth 2.0 access token that the app expects.
-* `id` - the Object ID of the Azure Active Directory Application.
+* `homepage` - (**Deprecated**) The URL to the application's home page. This property is deprecated and has been replaced by the `homepage_url` property in the `web` block.
 * `identifier_uris` - A list of user-defined URI(s) that uniquely identify a Web application within it's Azure AD tenant, or within a verified custom domain if the application is multi-tenant.
-* `logout_url` - The URL of the logout page.
-* `oauth2_allow_implicit_flow` - Does this Azure AD Application allow OAuth2.0 implicit flow tokens?
-* `oauth2_permissions` - A collection of OAuth 2.0 permission scopes that the web API (resource) app exposes to client apps. Each permission is covered by a `oauth2_permission` block as documented below.
-* `object_id` - the Object ID of the Azure Active Directory Application.
+* `logout_url` - (**Deprecated**) The URL of the logout page. This property is deprecated and has been replaced by the `logout_url` property in the `web` block.
+* `oauth2_allow_implicit_flow` - (**Deprecated**) Does this Azure AD Application allow OAuth2.0 implicit flow tokens?
+* `oauth2_permissions` - (**Deprecated**) A collection of OAuth 2.0 permission scopes that the web API (resource) app exposes to client apps. Each permission is covered by a `oauth2_permission` block as documented below.
+* `object_id` - The application's Object ID.
 * `optional_claims` - A collection of `access_token` or `id_token` blocks as documented below which list the optional claims configured for each token type. For more information see https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims
-* `owners` - A list of User Object IDs that are assigned ownership of the application registration.
-* `public_client` - Is this Azure AD Application available publicly?
-* `reply_urls` - A list of URLs that user tokens are sent to for sign in, or the redirect URIs that OAuth 2.0 authorization codes and access tokens are sent to.
+* `owners` - A list of Object IDs for principals that are assigned ownership of the application.
+* `public_client` - (**Deprecated**) Is this Azure AD Application available publicly? This property is deprecated and has been replaced by the `fallback_public_client_enabled` property.
+* `reply_urls` - (**Deprecated**) A list of URLs that user tokens are sent to for sign in, or the redirect URIs that OAuth 2.0 authorization codes and access tokens are sent to. This property is deprecated and has been replaced by the `redirect_uris` property in the `web` block.
 * `required_resource_access` - A collection of `required_resource_access` blocks as documented below.
+* `sign_in_audience` - The Microsoft account types that are supported for the current application. One of `AzureADMyOrg`, `AzureADMultipleOrgs`, `AzureADandPersonalMicrosoftAccount` or `PersonalMicrosoftAccount`.
+* `web` - A `web` block as documented below.
 
 ---
 
@@ -61,16 +66,35 @@ The following attributes are exported:
 
 `app_role` block exports the following:
 
-* `allowed_member_types` - Specifies whether this app role definition can be assigned to users and groups, or to other applications (that are accessing this application in daemon service scenarios). Possible values are: `User` and `Application`, or both.
-* `description` - Permission help text that appears in the admin app assignment and consent experiences.
-* `display_name` - Display name for the permission that appears in the admin consent and app assignment experiences.
+* `allowed_member_types` - Specifies whether this app role definition can be assigned to users and groups, or to other applications (that are accessing this application in a standalone scenario). Possible values are: `User` and `Application`, or both.
+* `description` - Description of the app role that appears when the role is being assigned and, if the role functions as an application permissions, during the consent experiences.
+* `display_name` - Display name for the app role that appears during app role assignment and in consent experiences.
 * `id` - The unique identifier of the `app_role`.
-* `is_enabled` - Determines if the app role is enabled.
-* `value` - Specifies the value of the roles claim that the application should expect in the authentication and access tokens.
+* `enabled` - Determines if the app role is enabled.
+* `value` - The value that is used for the `roles` claim in ID tokens and OAuth 2.0 access tokens that are authenticating an assigned service or user principal.
 
 ---
 
-`oauth2_permission` block exports the following:
+`implicit_grant` block exports the following:
+
+* `access_token_issuance_enabled` - Whether this web application can request an access token using OAuth 2.0 implicit flow.
+
+---
+
+`oauth2_permission_scope` block exports the following:
+
+* `admin_consent_description` - (Required) Delegated permission description that appears in all tenant-wide admin consent experiences, intended to be read by an administrator granting the permission on behalf of all users.
+* `admin_consent_display_name` - (Required) Display name for the delegated permission, intended to be read by an administrator granting the permission on behalf of all users.
+* `enabled` - (Optional) Determines if the permission scope is enabled.
+* `id` - (Required) The unique identifier of the delegated permission. Must be a valid UUID.
+* `type` - (Required) Whether this delegated permission should be considered safe for non-admin users to consent to on behalf of themselves, or whether an administrator should be required for consent to the permissions. Possible values are `User` or `Admin`.
+* `user_consent_description` - (Optional) Delegated permission description that appears in the end user consent experience, intended to be read by a user consenting on their own behalf.
+* `user_consent_display_name` - (Optional) Display name for the delegated permission that appears in the end user consent experience.
+* `value` - (Optional) The value that is used for the `scp` claim in OAuth 2.0 access tokens.
+
+---
+
+`oauth2_permission` block (deprecated) exports the following:
 
 * `admin_consent_description` - The description of the admin consent
 * `admin_consent_display_name` - The display name of the admin consent
@@ -85,12 +109,22 @@ The following attributes are exported:
 
 `required_resource_access` block exports the following:
 
-* `resource_access` - A collection of `resource_access` blocks as documented below
-* `resource_app_id` - The unique identifier for the resource that the application requires access to.
+* `resource_access` - A collection of `resource_access` blocks as documented below, describing OAuth2.0 permission scopes and app roles that the application requires from the specified resource.
+* `resource_app_id` - The unique identifier for the resource that the application requires access to. This is the Application ID of the target application.
 
 ---
 
 `resource_access` block exports the following:
 
-* `id` - The unique identifier for one of the `OAuth2Permission` or `AppRole` instances that the resource application exposes. 
-* `type` - Specifies whether the id property references an `OAuth2Permission` or an `AppRole`.
+
+* `id` - The unique identifier for one of the `OAuth2Permission` or `AppRole` instances that the resource application exposes.
+* `type` - Specifies whether the `id` property references an `OAuth2Permission` or an `AppRole`. Possible values are `Scope` or `Role`.
+
+---
+
+`web` block exports the following:
+
+* `homepage_url` - Home page or landing page of the application.
+* `implicit_grant` - An `implicit_grant` block as documented above.
+* `logout_url` - The URL that will be used by Microsoft's authorization service to sign out a user using front-channel, back-channel or SAML logout protocols.
+* `redirect_uris` - A list of URLs where user tokens are sent for sign-in, or the redirect URIs where OAuth 2.0 authorization codes and access tokens are sent.

docs/data-sources/groups.md

@@ -12,15 +12,15 @@ Gets Object IDs or Display Names for multiple Azure Active Directory groups.
 
 ```terraform
 data "azuread_groups" "groups" {
-  names = ["group-a", "group-b"]
+  display_names = ["group-a", "group-b"]
 }
 ```
 
 ## Argument Reference
 
 The following arguments are supported:
 
-* `names` - (Optional) The Display Names of the Azure AD Groups.
+* `display_names` - (Optional) The Display Names of the Azure AD Groups.
 * `object_ids` - (Optional) The Object IDs of the Azure AD Groups.
 
 ~> **NOTE:** Either `names` or `object_ids` should be specified. Either of these _may_ be specified as an empty list, in which case no results will be returned.
@@ -29,5 +29,5 @@ The following arguments are supported:
 
 The following attributes are exported:
 
-* `names` - The Display Names of the Azure AD Groups.
+* `display_names` - The Display Names of the Azure AD Groups.
 * `object_ids` - The Object IDs of the Azure AD Groups.

docs/data-sources/service_principal.md

@@ -36,24 +36,24 @@ data "azuread_service_principal" "example" {
 
 The following arguments are supported:
 
-* `app_roles` - A collection of `app_role` blocks as documented below. For more information https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles
 * `application_id` - (Optional) The ID of the Azure AD Application.
 * `display_name` - (Optional) The Display Name of the Azure AD Application associated with this Service Principal.
 * `object_id` - (Optional) The ID of the Azure AD Service Principal.
 
 ~> **NOTE:** At least one of `application_id`, `display_name` or `object_id` must be specified.
 
-* `oauth2_permissions` - A collection of OAuth 2.0 permissions exposed by the associated application. Each permission is covered by a `oauth2_permission` block as documented below.
-
 ## Attributes Reference
 
 The following attributes are exported:
 
-* `id` - The Object ID for the Service Principal.
+* `app_roles` - A collection of `app_roles` blocks as documented below. For more information [official documentation](https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles).
+* `object_id` - The Object ID for the Service Principal.
+* `oauth2_permission_scopes` - A collection of OAuth 2.0 delegated permissions exposed by the associated Application. Each permission is covered by an `oauth2_permission_scopes` block as documented below.
+* `oauth2_permissions` - (**Deprecated**) A collection of OAuth 2.0 permissions exposed by the associated Application. Each permission is covered by an `oauth2_permissions` block as documented below. Deprecated in favour of `oauth2_permission_scopes`.
 
 ---
 
-`app_role` block exports the following:
+`app_roles` block exports the following:
 
 * `allowed_member_types` - Specifies whether this app role definition can be assigned to users and groups, or to other applications (that are accessing this application in daemon service scenarios). Possible values are: `User` and `Application`, or both.
 * `description` - Permission help text that appears in the admin app assignment and consent experiences.
@@ -64,7 +64,20 @@ The following attributes are exported:
 
 ---
 
-`oauth2_permission` block exports the following:
+`oauth2_permission_scopes` block exports the following:
+
+* `admin_consent_description` - The description of the admin consent.
+* `admin_consent_display_name` - The display name of the admin consent.
+* `enabled` - Is this permission enabled?
+* `id` - The unique identifier for one of the `OAuth2Permission`.
+* `type` - The type of the permission.
+* `user_consent_description` - The description of the user consent.
+* `user_consent_display_name` - The display name of the user consent.
+* `value` - The name of this permission.
+
+---
+
+`oauth2_permissions` block exports the following:
 
 * `admin_consent_description` - The description of the admin consent
 * `admin_consent_display_name` - The display name of the admin consent

docs/data-sources/user.md

@@ -38,15 +38,18 @@ The following attributes are exported:
 * `display_name` - The Display Name of the Azure AD User.
 * `given_name` - The given name (first name) of the user.
 * `id` - The Object ID of the Azure AD User.
-* `immutable_id` - The value used to associate an on-premise Active Directory user account with their Azure AD user object.
+* `immutable_id` - (**Deprecated**) The value used to associate an on-premise Active Directory user account with their Azure AD user object. Deprecated in favour of `onpremises_immutable_id`.
 * `job_title` - The user’s job title.
 * `mail_nickname` - The email alias of the Azure AD User.
 * `mail_nickname` - The email alias of the Azure AD User.
 * `mail` - The primary email address of the Azure AD User.
-* `mobile` - The primary cellular telephone number for the user.
+* `mobile` - (**Deprecated**) The primary cellular telephone number for the user. Deprecated in favour of `mobile_phone`.
+* `mobile_phone` - The primary cellular telephone number for the user.
+* `office_location` - The office location in the user's place of business.
+* `onpremises_immutable_id` - The value used to associate an on-premise Active Directory user account with their Azure AD user object.
 * `onpremises_sam_account_name` - The on-premise SAM account name of the Azure AD User.
 * `onpremises_user_principal_name` - The on-premise user principal name of the Azure AD User.
-* `physical_delivery_office_name` - The office location in the user's place of business.
+* `physical_delivery_office_name` - (**Deprecated**) The office location in the user's place of business. Deprecated in favour of `office_location`.
 * `postal_code` - The postal code for the user's postal address. The postal code is specific to the user's country/region. In the United States of America, this attribute contains the ZIP code.
 * `state` - The state or province in the user's address.
 * `street_address` - The street address of the user's place of business.

docs/data-sources/users.md

@@ -42,10 +42,11 @@ ___
 
 * `account_enabled` - `True` if the account is enabled; otherwise `False`.
 * `display_name` - The Display Name of the Azure AD User.
-* `immutable_id` - The value used to associate an on-premises Active Directory user account with their Azure AD user object.
+* `immutable_id` - (**Deprecated**) The value used to associate an on-premises Active Directory user account with their Azure AD user object. Deprecated in favour of `onpremises_immutable_id`.
 * `mail_nickname` - The email alias of the Azure AD User.
 * `mail` - The primary email address of the Azure AD User.
 * `object_id` - The Object ID of the Azure AD User.
+* `onpremises_immutable_id` - The value used to associate an on-premises Active Directory user account with their Azure AD user object.
 * `onpremises_sam_account_name` - The on-premise SAM account name of the Azure AD User.
 * `onpremises_user_principal_name` - The on-premise user principal name of the Azure AD User.
 * `usage_location` - The usage location of the Azure AD User.

docs/guides/azure_cli.md

@@ -3,18 +3,18 @@ page_title: "Authenticating via the Azure CLI"
 subcategory: "Authentication"
 ---
 
-# Azure Active Directory Provider: Authenticating using the Azure CLI
+# Authenticating using the Azure CLI
 
 Terraform supports a number of different methods for authenticating to Azure:
 
 * Authenticating to Azure using the Azure CLI (covered in this guide)
-* [Authenticating to Azure using Managed Service Identity](managed_service_identity.html)
+* [Authenticating to Azure using Managed Identity](managed_service_identity.html)
 * [Authenticating to Azure using a Service Principal and a Client Certificate](service_principal_client_certificate.html)
 * [Authenticating to Azure using a Service Principal and a Client Secret](service_principal_client_secret.html)
 
 ---
 
-We recommend using either a Service Principal or Managed Service Identity when running Terraform non-interactively (such as when running Terraform in a CI server) - and authenticating using the Azure CLI when running Terraform locally.
+We recommend using either a Service Principal or Managed Identity when running Terraform non-interactively (such as when running Terraform in a CI server) - and authenticating using the Azure CLI when running Terraform locally.
 
 ## Important Notes about Authenticating using the Azure CLI