Documentation: access rights for azuread_group and administrative units.

[ghjklw]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritise this request
• Please do not leave "+1" or "me too" comments, they generate extra noise for issue followers and do not help prioritise the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

Terraform (and AzureAD Provider) Version

2.53.0

Affected Resource(s)

• azuread_group

Terraform Configuration Files

resource "azuread_group" "example" {
  display_name            = "example"
  administrative_unit_ids = [ var.administrative_unit_id ]
  security_enabled        = true
}

Output

│ Error: Creating group in administrative unit with ID "xxxxx", "example"
│ 
│   with azuread_group.example,
│   on main.tf line 2, in resource "azuread_group" "example":
│   2: resource "azuread_group" "example" {
│ 
│ AdministrativeUnitsClient.BaseClient.Post(): unexpected status 403 with
│ OData error: Authorization_RequestDenied: Insufficient privileges to
│ complete the operation.

Expected Behavior

This is not an unexpected behaviour but a permission issue: to create a group within an administrative, the API permission Group.ReadWrite.All is not sufficient: AdministrativeUnit.Read.All is also required. Likewise Groups Administrator role is not sufficient.

In addition, I find the following wording slightly confusing:

When authenticated with a service principal, this resource requires one of the following application roles: Group.ReadWrite.All or Directory.ReadWrite.All.` [...] When authenticated with a user principal, this resource requires one of the following directory roles: Groups Administrator, User Administrator or Global Administrator

Combined with the lack of documentation for the AdministrativeUnit.Read.All requirement, this wording gave me the false impressions that directory roles could only be used with user principals and only API permissions could be used with service principals.

Actual Behavior

I think a slight rewording of the documentation would be helpful. Maybe extending the paragraph dedicated to the case where one want to create a group within an administrative unit, clarifying:

• The need for the user to have read access to the administrative units, for example through the AdministrativeUnit.Read.All API permission or Directory Readers role (although much this one has much wider permissions than necessary)
• The fact that API permissions cannot be scoped down to an administrative unit, and that if you want to restrict the permissions to this administrative unit, you should use the Groups Administrator role scoped on it, even if you're using a service principal