Update docs for remaining resources/data sources, update service prin…

…cipals - Document new fields and deprecations - Improve test coverage for azuread_service_principal - oauth2_permissions -> oauth2_permission_scopes deprecation for service principal resource and data source
hashicorp · May 11, 2021 · 4bfce61 · 4bfce61
1 parent dab1031
commit 4bfce61
Show file tree

Hide file tree

Showing 22 changed files with 236 additions and 64 deletions.
diff --git a/.gitignore b/.gitignore
@@ -39,3 +39,6 @@ website/vendor
 
 # built binary
 terraform-provider-azuread
+
+# terraform version
+.terraform-version
diff --git a/docs/data-sources/groups.md b/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.
diff --git a/docs/data-sources/service_principal.md b/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

diff --git a/docs/data-sources/user.md b/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.

diff --git a/docs/data-sources/users.md b/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.

diff --git a/docs/resources/service_principal.md b/docs/resources/service_principal.md
@@ -40,13 +40,39 @@ The following arguments are supported:
 
 In addition to all arguments above, the following attributes are exported:
 
+* `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).
 * `display_name` - The Display Name of the Application associated with this Service Principal.
-* `oauth2_permissions` - A collection of OAuth 2.0 permissions exposed by the associated Application. Each permission is covered by an `oauth2_permission` block as documented below.
+* `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`.
 * `object_id` - The Object ID of the Service Principal.
 
 ---
 
-`oauth2_permission` 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.
+* `display_name` - Display name for the permission that appears in the admin consent and app assignment 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.
+
+---
+
+`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 (deprecated) exports the following:
 
 * `admin_consent_description` - The description of the admin consent.
 * `admin_consent_display_name` - The display name of the admin consent.

diff --git a/docs/resources/service_principal_password.md b/docs/resources/service_principal_password.md
@@ -31,7 +31,8 @@ resource "azuread_service_principal_password" "example" {
 
 The following arguments are supported:
 
-* `description` - (Optional) A description for the Password.
+* `description` - (Optional, **Deprecated**) A description for the Password. Deprecated in favour of `display_name`.
+* `display_name` - (Optional) The display name for the password.
 
 -> **NOTE:** `description` maps to the `CustomKeyIdentifier` property of the `PasswordCredentials` API resource.
 

diff --git a/docs/resources/user.md b/docs/resources/user.md
@@ -31,12 +31,15 @@ The following arguments are supported:
 * `display_name` - (Required) The name to display in the address book for the user.
 * `force_password_change` - (Optional) `true` if the User is forced to change the password during the next sign-in. Defaults to `false`.
 * `given_name` - (Optional) The given name (first name) of the user.
-* `immutable_id` - (Optional) The value used to associate an on-premise Active Directory user account with their Azure AD user object. This must be specified if you are using a federated domain for the user's userPrincipalName (UPN) property when creating a new user account. 
+* `immutable_id` - (Optional, **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` - (Optional) The user’s job title.
 * `mail_nickname` - (Optional) The mail alias for the user. Defaults to the user name part of the User Principal Name.
-* `mobile` - (Optional) The primary cellular telephone number for the user.
+* `mobile` - (Optional, **Deprecated**) The primary cellular telephone number for the user. Deprecated in favour of `mobile_phone`.
+* `mobile_phone` - (Optional) The primary cellular telephone number for the user.
+* `office_location` - (Optional) The office location in the user's place of business.
+* `onpremises_immutable_id` - (Optional) The value used to associate an on-premise Active Directory user account with their Azure AD user object. This must be specified if you are using a federated domain for the user's userPrincipalName (UPN) property when creating a new user account.
 * `password` - (Required) The password for the User. The password must satisfy minimum requirements as specified by the password policy. The maximum length is 256 characters.
-* `physical_delivery_office_name` - (Optional) The office location in the user's place of business.
+* `physical_delivery_office_name` - (Optional, **Deprecated**) The office location in the user's place of business. Deprecated in favour of `office_location`.
 * `postal_code` - (Optional) 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` - (Optional) The state or province in the user's address.
 * `street_address` - (Optional) The street address of the user's place of business.

diff --git a/internal/helpers/aadgraph/application.go b/internal/helpers/aadgraph/application.go
@@ -120,6 +120,30 @@ func FlattenOauth2Permissions(in *[]graphrbac.OAuth2Permission) []map[string]int
 	return result
 }
 
+func ApplicationFlattenOAuth2PermissionScopes(in *[]graphrbac.OAuth2Permission) []map[string]interface{} {
+	oauth2Permissions := FlattenOauth2Permissions(in)
+
+	if len(oauth2Permissions) == 0 {
+		return []map[string]interface{}{}
+	}
+
+	result := make([]map[string]interface{}, 0)
+	for _, p := range oauth2Permissions {
+		result = append(result, map[string]interface{}{
+			"admin_consent_description":  p["admin_consent_description"],
+			"admin_consent_display_name": p["admin_consent_display_name"],
+			"id":                         p["id"],
+			"enabled":                    p["is_enabled"],
+			"type":                       p["type"],
+			"user_consent_description":   p["user_consent_description"],
+			"user_consent_display_name":  p["user_consent_display_name"],
+			"value":                      p["value"],
+		})
+	}
+
+	return result
+}
+
 func ApplicationAllOwners(ctx context.Context, client *graphrbac.ApplicationsClient, appId string) ([]string, error) {
 	owners, err := client.ListOwnersComplete(ctx, appId)
 

diff --git a/internal/services/applications/application_data_source.go b/internal/services/applications/application_data_source.go
@@ -81,8 +81,9 @@ func applicationDataSource() *schema.Resource {
 
 									// TODO: v2.0 remove this
 									"is_enabled": {
-										Type:     schema.TypeBool,
-										Computed: true,
+										Type:       schema.TypeBool,
+										Computed:   true,
+										Deprecated: "[NOTE] This attribute has been renamed to `enabled` and will be removed in version 2.0 of the AzureAD provider",
 									},
 
 									"type": {
@@ -208,9 +209,10 @@ func applicationDataSource() *schema.Resource {
 
 			// TODO: v2.0 remove this block
 			"oauth2_permissions": {
-				Type:     schema.TypeList,
-				Optional: true,
-				Computed: true,
+				Type:       schema.TypeList,
+				Optional:   true,
+				Computed:   true,
+				Deprecated: "[NOTE] The `oauth2_permissions` block has been renamed to `oauth2_permission_scopes` and moved to the `api` block. `oauth2_permissions` will be removed in version 2.0 of the AzureAD provider.",
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
 						"admin_consent_description": {
@@ -233,11 +235,9 @@ func applicationDataSource() *schema.Resource {
 							Computed: true,
 						},
 
-						// TODO: v2.0 remove this
 						"is_enabled": {
-							Type:       schema.TypeBool,
-							Computed:   true,
-							Deprecated: "[NOTE] This attribute will be renamed to `enabled` in version 2.0 of the AzureAD provider",
+							Type:     schema.TypeBool,
+							Computed: true,
 						},
 
 						"type": {

diff --git a/internal/services/applications/application_data_source_aadgraph.go b/internal/services/applications/application_data_source_aadgraph.go
@@ -91,7 +91,7 @@ func applicationDataSourceReadAadGraph(ctx context.Context, d *schema.ResourceDa
 
 	api := []map[string]interface{}{
 		{
-			"oauth2_permission_scope": applicationFlattenOAuth2PermissionScopes(app.Oauth2Permissions),
+			"oauth2_permission_scope": aadgraph.ApplicationFlattenOAuth2PermissionScopes(app.Oauth2Permissions),
 		},
 	}
 	tf.Set(d, "api", api)

diff --git a/internal/services/applications/application_resource.go b/internal/services/applications/application_resource.go
@@ -267,7 +267,7 @@ func applicationResource() *schema.Resource {
 				Optional:   true,
 				Computed:   true,
 				ConfigMode: schema.SchemaConfigModeAttr,
-				Deprecated: "[NOTE] The `oauth2_permissions` block has been renamed to `oauth2_permission_scopes` and moved to the `api` block. `oauth2_permissions` will be removed in version 2.0 of the AzureAD provider.",
+				Deprecated: "[NOTE] The `oauth2_permissions` block has been renamed to `oauth2_permission_scope` and moved to the `api` block. `oauth2_permissions` will be removed in version 2.0 of the AzureAD provider.",
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
 						"id": {

diff --git a/internal/services/applications/application_resource_aadgraph.go b/internal/services/applications/application_resource_aadgraph.go
@@ -342,7 +342,7 @@ func applicationResourceReadAadGraph(ctx context.Context, d *schema.ResourceData
 
 	api := []map[string]interface{}{
 		{
-			"oauth2_permission_scope": applicationFlattenOAuth2PermissionScopes(app.Oauth2Permissions),
+			"oauth2_permission_scope": aadgraph.ApplicationFlattenOAuth2PermissionScopes(app.Oauth2Permissions),
 		},
 	}
 	tf.Set(d, "api", api)
@@ -711,27 +711,3 @@ func expandApplicationOAuth2PermissionsAad(i interface{}) *[]graphrbac.OAuth2Per
 	}
 	return &result
 }
-
-func applicationFlattenOAuth2PermissionScopes(in *[]graphrbac.OAuth2Permission) []map[string]interface{} {
-	oauth2Permissions := aadgraph.FlattenOauth2Permissions(in)
-
-	if len(oauth2Permissions) == 0 {
-		return []map[string]interface{}{}
-	}
-
-	result := make([]map[string]interface{}, 0)
-	for _, p := range oauth2Permissions {
-		result = append(result, map[string]interface{}{
-			"admin_consent_description":  p["admin_consent_description"],
-			"admin_consent_display_name": p["admin_consent_display_name"],
-			"id":                         p["id"],
-			"enabled":                    p["is_enabled"],
-			"type":                       p["type"],
-			"user_consent_description":   p["user_consent_description"],
-			"user_consent_display_name":  p["user_consent_display_name"],
-			"value":                      p["value"],
-		})
-	}
-
-	return result
-}
diff --git a/internal/services/applications/application_resource_test.go b/internal/services/applications/application_resource_test.go
@@ -648,6 +648,22 @@ resource "azuread_application" "test" {
     }
   }
 
+  app_role {
+    allowed_member_types = ["User"]
+    description          = "Admins can manage roles and perform all task actions"
+    display_name         = "Admin"
+    is_enabled           = true
+    value                = ""
+  }
+
+  app_role {
+    allowed_member_types = ["User"]
+    description          = "ReadOnly roles have limited query access"
+    display_name         = "ReadOnly"
+    is_enabled           = true
+    value                = "User"
+  }
+
   optional_claims {
     access_token {
       name = "myclaim"