New Resources: azuread_application_registration, azuread_application_from_template and others

.github/workflows/golint.yaml

@@ -18,7 +18,7 @@ jobs:
           go-version-file: .go-version
       - uses: golangci/golangci-lint-action@3a919529898de77ec3da873e3063ca4b10e7f5cc # v3.7.0
         with:
-          version: 'v1.50.1'
+          version: 'v1.54.2'
           args: -v
 
   save-artifacts-on-fail:

GNUmakefile

@@ -16,7 +16,7 @@ tools:
 	go install github.com/bflad/tfproviderdocs@latest
 	go install github.com/katbyte/terrafmt@latest
 	go install mvdan.cc/gofumpt@latest
-	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b "$$(go env GOPATH || $$GOPATH)"/bin v1.49.0
+	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b "$$(go env GOPATH || $$GOPATH)"/bin v1.54.2
 
 build: fmtcheck
 	go install

docs/data-sources/application.md

@@ -22,19 +22,19 @@ data "azuread_application" "example" {
 }
 
 output "application_object_id" {
-  value = data.azuread_application.example.id
+  value = data.azuread_application.example.object_id
 }
 ```
 
 ## Argument Reference
 
 The following arguments are supported:
 
-* `application_id` - (Optional) Specifies the Application ID (also called Client ID).
+* `client_id` - (Optional) Specifies the Client ID of the application.
 * `display_name` - (Optional) Specifies the display name of the application.
 * `object_id` - (Optional) Specifies the Object ID of the application.
 
-~> One of `object_id`, `application_id` or `display_name` must be specified.
+~> One of `client_id`, `display_name`, or `object_id` must be specified.
 
 ## Attributes Reference
 
@@ -43,7 +43,7 @@ The following attributes are exported:
 * `api` - An `api` block as documented below.
 * `app_role_ids` - A mapping of app role values to app role IDs, intended to be useful when referencing app roles in other resources in your configuration.
 * `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).
+* `client_id` - The Client ID for the application.
 * `description` - A description of the application, as shown to end users.
 * `device_only_auth_enabled` - Specifies whether this application supports device authentication without a user.
 * `disabled_by_microsoft` - Whether Microsoft has disabled the registered application. If the application is disabled, this will be a string indicating the status/reason, e.g. `DisabledDueToViolationOfServicesAgreement`

docs/data-sources/application_published_app_ids.md

@@ -28,15 +28,15 @@ output "published_app_ids" {
 data "azuread_application_published_app_ids" "well_known" {}
 
 resource "azuread_service_principal" "msgraph" {
-  application_id = data.azuread_application_published_app_ids.well_known.result.MicrosoftGraph
+  application_id = data.azuread_application_published_app_ids.well_known.result["MicrosoftGraph"]
   use_existing   = true
 }
 
 resource "azuread_application" "example" {
   display_name = "example"
 
   required_resource_access {
-    resource_app_id = data.azuread_application_published_app_ids.well_known.result.MicrosoftGraph
+    resource_app_id = data.azuread_application_published_app_ids.well_known.result["MicrosoftGraph"]
 
     resource_access {
       id   = azuread_service_principal.msgraph.app_role_ids["User.Read.All"]

docs/data-sources/service_principal.md

@@ -24,11 +24,11 @@ data "azuread_service_principal" "example" {
 }
 ```
 
-*Look up by application ID (client ID)*
+*Look up by client ID*
 
 ```terraform
 data "azuread_service_principal" "example" {
-  application_id = "00000000-0000-0000-0000-000000000000"
+  client_id = "00000000-0000-0000-0000-000000000000"
 }
 ```
 
@@ -44,23 +44,23 @@ data "azuread_service_principal" "example" {
 
 The following arguments are supported:
 
-* `application_id` - (Optional) The application ID (client ID) of the application associated with this service principal.
+* `client_id` - (Optional) The client ID of the application associated with this service principal.
 * `display_name` - (Optional) The display name of the application associated with this service principal.
 * `object_id` - (Optional) The object ID of the service principal.
 
-~> One of `application_id`, `display_name` or `object_id` must be specified.
+~> One of `client_id`, `display_name` or `object_id` must be specified.
 
 ## Attributes Reference
 
 The following attributes are exported:
 
-* `account_enabled` - Whether or not the service principal account is enabled.
+* `account_enabled` - Whether the service principal account is enabled.
 * `alternative_names` - A list of alternative names, used to retrieve service principals by subscription, identify resource group and full resource ids for managed identities.
-* `application_id` - The application ID (client ID) of the application associated with this service principal.
 * `app_role_assignment_required` - Whether this service principal requires an app role assignment to a user or group before Azure AD will issue a user or access token to the application.
 * `app_role_ids` - A mapping of app role values to app role IDs, as published by the associated application, intended to be useful when referencing app roles in other resources in your configuration.
 * `app_roles` - A list of app roles published by the associated application, as documented below. For more information [official documentation](https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles).
 * `application_tenant_id` - The tenant ID where the associated application is registered.
+* `client_id` - The client ID of the application associated with this service principal.
 * `description` - A description of the service principal provided for internal end-users.
 * `display_name` - The display name of the application associated with this service principal.
 * `features` - A `features` block as described below.

docs/data-sources/service_principals.md

@@ -31,7 +31,7 @@ data "azuread_service_principals" "example" {
 
 ```terraform
 data "azuread_service_principals" "example" {
-  application_ids = [
+  client_ids = [
     "11111111-0000-0000-0000-000000000000",
     "22222222-0000-0000-0000-000000000000",
     "33333333-0000-0000-0000-000000000000",
@@ -55,19 +55,20 @@ data "azuread_service_principals" "example" {
 
 The following arguments are supported:
 
-* `application_ids` - (Optional) A list of application IDs (client IDs) of the applications associated with the service principals.
+* `client_ids` - (Optional) A list of client IDs of the applications associated with the service principals.
 * `display_names` - (Optional) A list of display names of the applications associated with the service principals.
 * `ignore_missing` - (Optional) Ignore missing service principals and return all service principals that are found. The data source will still fail if no service principals are found. Defaults to false.
 * `object_ids` - (Optional) The object IDs of the service principals.
 * `return_all` - (Optional) When `true`, the data source will return all service principals. Cannot be used with `ignore_missing`. Defaults to false.
 
-~> Either `return_all`, or one of `application_ids`, `display_names` or `object_ids` must be specified. These _may_ be specified as an empty list, in which case no results will be returned.
+~> Either `return_all`, or one of `client_ids`, `display_names` or `object_ids` must be specified. These _may_ be specified as an empty list, in which case no results will be returned.
 
 ## Attributes Reference
 
 The following attributes are exported:
 
-* `application_ids` - A list of application IDs (client IDs) of the applications associated with the service principals.
+* `application_ids` - A list of client IDs of the applications associated with the service principals.
+* `client_ids` - A list of client IDs of the applications associated with the service principals.
 * `display_names` - A list of display names of the applications associated with the service principals.
 * `object_ids` - The object IDs of the service principals.
 * `service_principals` - A list of service principals. Each `service_principal` object provides the attributes documented below.
@@ -76,10 +77,10 @@ The following attributes are exported:
 
 `service_principal` object exports the following:
 
-* `account_enabled` - Whether or not the service principal account is enabled.
+* `account_enabled` - Whether the service principal account is enabled.
 * `app_role_assignment_required` - Whether this service principal requires an app role assignment to a user or group before Azure AD will issue a user or access token to the application.
-* `application_id` - The application ID (client ID) of the application associated with this service principal.
 * `application_tenant_id` - The tenant ID where the associated application is registered.
+* `client_ids` - The client ID of the application associated with this service principal.
 * `display_name` - The display name of the application associated with this service principal.
 * `object_id` - The object ID of the service principal.
 * `preferred_single_sign_on_mode` - The single sign-on mode configured for this application. Azure AD uses the preferred single sign-on mode to launch the application from Microsoft 365 or the Azure AD My Apps.

docs/resources/access_package_catalog_role_assignment.md

@@ -57,5 +57,5 @@ In addition to all arguments above, the following attributes are exported:
 Catalog role assignments can be imported using the ID of the assignment, e.g.
 
 ```shell
-terraform import azuread_access_package_catalog_role_assignment.test 00000000-0000-0000-0000-000000000000
+terraform import azuread_access_package_catalog_role_assignment.example 00000000-0000-0000-0000-000000000000
 ```

docs/resources/administrative_unit_member.md

@@ -52,7 +52,7 @@ In addition to all arguments above, the following attributes are exported:
 Administrative unit members can be imported using the object ID of the administrative unit and the object ID of the member, e.g.
 
 ```shell
-terraform import azuread_administrative_unit_member.test 00000000-0000-0000-0000-000000000000/member/11111111-1111-1111-1111-111111111111
+terraform import azuread_administrative_unit_member.example 00000000-0000-0000-0000-000000000000/member/11111111-1111-1111-1111-111111111111
 ```
 
 -> This ID format is unique to Terraform and is composed of the Administrative Unit Object ID and the target Member Object ID in the format `{AdministrativeUnitObjectID}/member/{MemberObjectID}`.

docs/resources/administrative_unit_role_member.md

@@ -56,7 +56,7 @@ In addition to all arguments above, the following attributes are exported:
 Administrative unit role members can be imported using the object ID of the administrative unit and the unique ID of the role assignment, e.g.
 
 ```shell
-terraform import azuread_administrative_unit_role_member.test 00000000-0000-0000-0000-000000000000/roleMember/zX37MRLyF0uvE-xf2WH4B7x-6CPLfudNnxFGj800htpBXqkxW7bITqGb6Rj4kuTuS
+terraform import azuread_administrative_unit_role_member.example 00000000-0000-0000-0000-000000000000/roleMember/zX37MRLyF0uvE-xf2WH4B7x-6CPLfudNnxFGj800htpBXqkxW7bITqGb6Rj4kuTuS
 ```
 
 -> This ID format is unique to Terraform and is composed of the Administrative Unit Object ID and the role assignment ID in the format `{AdministrativeUnitObjectID}/roleMember/{RoleAssignmentID}`.

docs/resources/application.md

@@ -6,15 +6,19 @@ subcategory: "Applications"
 
 Manages an application registration within Azure Active Directory.
 
+For a more lightweight alternative, please see the [azuread_application_registration](application_registration.html) resource. Please note that this resource should not be used together with the `azuread_application_registration` resource when managing the same application.
+
 ## API Permissions
 
 The following API permissions are required in order to use this resource.
 
-When authenticated with a service principal, this resource requires the following application role: `Application.ReadWrite.All`
+When authenticated with a service principal, this resource requires one of the following application roles: `Application.ReadWrite.OwnedBy` or `Application.ReadWrite.All`
+
+-> When using the `Application.ReadWrite.OwnedBy` application role, you should ensure that the principal being used to run Terraform is included in the `owners` property.
 
--> It is usually possible to create applications using this resource with just the `Application.ReadWrite.OwnedBy` application role, provided the principal being used to run Terraform is included in the `owners` property. However, this is not officially supported by the API so if you receive a `403` you need to investigate what API call is failing and add additional permissions as necessary. One commonly needed additional permission is `User.Read.All`, in case you specify additional `owners`.
+Additionally, you may need the `User.Read.All` application role when including user principals in the `owners` property.
 
-When authenticated with a user principal, this resource requires one of the following directory roles: `Application Administrator` or `Global Administrator`
+When authenticated with a user principal, this resource may require one of the following directory roles: `Application Administrator` or `Global Administrator`
 
 ## Example Usage
 
@@ -199,6 +203,9 @@ The following arguments are supported:
 -> **Tags and Features** Azure Active Directory uses special tag values to configure the behavior of applications. These can be specified using either the `tags` property or with the `feature_tags` block. If you need to set any custom tag values not supported by the `feature_tags` block, it's recommended to use the `tags` property. Tag values also propagate to any linked service principals.
 
 * `template_id` - (Optional) Unique ID for a templated application in the Azure AD App Gallery, from which to create the application. Changing this forces a new resource to be created.
+
+-> **Tip for Gallery Applications** This resource can  be used to instantiate a gallery application, however it will also attempt to manage the properties of the resulting application. If this is not desired, consider using the [azuread_application_registration](application_registration.html) resource instead.
+
 * `terms_of_service_url` - (Optional) URL of the application's terms of service statement.
 * `web` - (Optional) A `web` block as documented below, which configures web related settings for this application.
 
@@ -324,7 +331,7 @@ The following arguments are supported:
 In addition to all arguments above, the following attributes are exported:
 
 * `app_role_ids` - A mapping of app role values to app role IDs, intended to be useful when referencing app roles in other resources in your configuration.
-* `application_id` - The Application ID (also called Client ID).
+* `client_id` - The Client ID for the application.
 * `disabled_by_microsoft` - Whether Microsoft has disabled the registered application. If the application is disabled, this will be a string indicating the status/reason, e.g. `DisabledDueToViolationOfServicesAgreement`
 * `logo_url` - CDN URL to the application's logo, as uploaded with the `logo_image` property.
 * `oauth2_permission_scope_ids` - A mapping of OAuth2.0 permission scope values to scope IDs, intended to be useful when referencing permission scopes in other resources in your configuration.
@@ -336,5 +343,5 @@ In addition to all arguments above, the following attributes are exported:
 Applications can be imported using their object ID, e.g.
 
 ```shell
-terraform import azuread_application.test 00000000-0000-0000-0000-000000000000
+terraform import azuread_application.example 00000000-0000-0000-0000-000000000000
 ```

docs/resources/application_api_access.md

@@ -0,0 +1,92 @@
+---
+subcategory: "Applications"
+---
+
+# Resource: azuread_application_api_access
+
+Manages the API permissions for an application registration.
+
+This resource is analogous to the `required_resource_access` block in the `azuread_application` resource. When using these resources together, you should use the `ignore_changes` [lifecycle meta-argument](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle) (see example below).
+
+## API Permissions
+
+The following API permissions are required in order to use this resource.
+
+When authenticated with a service principal, this resource requires one of the following application roles: `Application.ReadWrite.OwnedBy` or `Application.ReadWrite.All`
+
+-> When using the `Application.ReadWrite.OwnedBy` application role, the principal being used to run Terraform must be an owner of the application.
+
+When authenticated with a user principal, this resource may require one of the following directory roles: `Application Administrator` or `Global Administrator`
+
+## Example Usage
+
+```terraform
+data "azuread_application_published_app_ids" "well_known" {}
+
+data "azuread_service_principal" "msgraph" {
+  client_id = data.azuread_application_published_app_ids.well_known.result["MicrosoftGraph"]
+}
+
+resource "azuread_application_registration" "example" {
+  display_name = "example"
+}
+
+resource "azuread_application_api_access" "example_msgraph" {
+  application_id = azuread_application_registration.example.id
+  api_client_id  = data.azuread_application_published_app_ids.well_known.result["MicrosoftGraph"]
+
+  role_ids = [
+    azuread_service_principal.msgraph.app_role_ids["Group.Read.All"],
+    azuread_service_principal.msgraph.app_role_ids["User.Read.All"],
+  ]
+
+  scope_ids = [
+    azuread_service_principal.msgraph.oauth2_permission_scope_ids["User.ReadWrite"],
+  ]
+}
+```
+
+-> **Tip** For managing permissions for an additional API, create another instance of this resource
+
+*Usage with azuread_application resource*
+
+```terraform
+
+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
+  # ...
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+* `api_client_id` - (Required) The client ID of the API to which access is being granted. Changing this forces a new resource to be created.
+* `application_id` - (Required) The resource ID of the application registration. Changing this forces a new resource to be created.
+* `role_ids` - (Optional) A set of role IDs to be granted to the application, as published by the API.
+* `scope_ids` - (Optional) A set of scope IDs to be granted to the application, as published by the API.
+
+-> At least one of `role_ids` or `scope_ids` must be specified.
+
+## Attributes Reference
+
+No additional attributes are exported.
+
+## Import
+
+Application API Access can be imported using the object ID of the application and the client ID of the API, in the following format.
+
+```shell
+terraform import azuread_application_api_access.example /applications/00000000-0000-0000-0000-000000000000/apiAccess/11111111-1111-1111-1111-111111111111
+```