documentation for azuread_application_app_role

docs/resources/application_api_access.md

@@ -6,20 +6,7 @@ subcategory: "Applications"
 
 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), for example:
-
-```terraform
-
-resource "azuread_application" "example" {
-  display_name = "example"
-
-  lifecycle {
-    ignore_changes = [
-      required_resource_access,
-    ]
-  }
-}
-```
+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
 
@@ -59,14 +46,34 @@ resource "azuread_application_api_access" "example_msgraph" {
 }
 ```
 
--> Tip: For managing permissions for an additional API, create another instance of this resource
+-> **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:
 
-* `application_id` - (Required) The resource ID of the application registration.
 * `api_client_id` - (Required) The client ID of the API to which access is being granted.
+* `application_id` - (Required) The resource ID of the application registration.
 * `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.
 

docs/resources/application_app_role.md

@@ -0,0 +1,89 @@
+---
+subcategory: "Applications"
+---
+
+# Resource: azuread_application_app_role
+
+Manages an app role for an application registration.
+
+This resource is analogous to the `app_role` 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
+resource "azuread_application_registration" "example" {
+  display_name = "example"
+}
+
+resource "random_uuid" "example_administrator" {}
+
+resource "azuread_application_app_role" "example_administer" {
+  application_id = azuread_application_registration.example.id
+  role_id        = random_uuid.example_administrator.id
+
+  allowed_member_types = ["User"]
+  description          = "My role description"
+  display_name         = "Administer"
+  value                = "admin"
+}
+```
+
+-> **Tip** For managing more app roles, create additional instances of this resource
+
+*Usage with azuread_application resource*
+
+```terraform
+
+resource "azuread_application" "example" {
+  display_name = "example"
+
+  lifecycle {
+    ignore_changes = [
+      app_role,
+    ]
+  }
+}
+
+resource "azuread_application_app_role" "example_administer" {
+  application_id = azuread_application.example.id
+  # ...
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+* `allowed_member_types` - (Required) A set of values to specify whether this app role definition can be assigned to users and groups by setting to `User`, or to other applications by setting to `Application`, or to both.
+* `application_id` - (Required) The resource ID of the application registration.
+* `description` - (Required) 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` - (Required) Display name for the app role that appears during app role assignment and in consent experiences.
+* `role_id` - (Required) The unique identifier of the app role. Must be a valid UUID.
+
+-> **Tip** Use the `random_uuid` resource to generate UUIDs and save them to state for app roles within your Terraform configuration
+
+* `value` - (Optional) 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.
+
+-> **Roles and Permission Scopes** In Azure Active Directory, application roles (`app_role`) and permission scopes (`oauth2_permission_scope`) exported by an application share the same namespace and cannot contain duplicate values.
+
+## Attributes Reference
+
+No additional attributes are exported.
+
+## Import
+
+Application App Roles can be imported using the object ID of the application and the ID of the app role, in the following format.
+
+```shell
+terraform import azuread_application_app_role.example /applications/00000000-0000-0000-0000-000000000000/appRoles/11111111-1111-1111-1111-111111111111
+```