docs(entra): adds Permissions sections for entra app role add/list/remove

[AlejandroGispert]

Closes #6925

Author: Alejandro Gispert  
Second-time contributor to cli-microsoft365

---

## Summary

This PR adds the Permissions section to the documentation for the following commands:

- m365 entra app role add

- m365 entra app role list

- m365 entra app role remove

The goal is to document the minimal delegated and application permissions required to manage app roles on Entra application registrations, and to keep the docs consistent with the existing Entra app permission commands.

---

## Changes

### 1. entra app role add

- File: docs/docs/cmd/entra/app/app-role-add.mdx

- Change: Added ## Permissions section immediately before ## Examples.

- Permissions documented:

  Delegated:   Application.ReadWrite.All
  Application: Application.ReadWrite.All

• Rationale:

• The Microsoft Graph docs for Update application state that updating an application (including appRoles) requires:

• Delegated: Application.ReadWrite.All

• Application: Application.ReadWrite.OwnedBy or Application.ReadWrite.All

• Because the CLI can target arbitrary app registrations (not necessarily “owned by” the CLI app), the minimal safe permission is Application.ReadWrite.All for both delegated and application.

• In practice, the signed-in user also needs an appropriate directory role (e.g. Application Administrator / Cloud Application Administrator), but that is a role requirement, not an OAuth scope, so the docs focus on the minimal Graph permissions.

---

2. entra app role list

• File: docs/docs/cmd/entra/app/app-role-list.mdx

• Change: Added ## Permissions section immediately before ## Examples.

• Permissions documented:

  Delegated:   Application.Read.All
  Application: Application.Read.All

• Rationale:

• The Microsoft Graph permissions reference for listing/reading applications uses Application.Read.All as the minimal read permission (with broader alternatives like Directory.Read.All).

• The existing entra app permission list command already documents Application.Read.All as the minimal permission for reading application permissions.

• Using Application.Read.All for entra app role list keeps behavior and documentation consistent across app-related read operations.

---

3. entra app role remove

• File: docs/docs/cmd/entra/app/app-role-remove.mdx

• Change: Added ## Permissions section immediately  before ## Examples.

• Permissions documented:

  Delegated:   Application.ReadWrite.All
  Application: Application.ReadWrite.All

• Rationale:

• Removing an app role is implemented as an update to the application’s appRoles array, the same Graph operation as in entra app role add.

• As with app role add, the Graph Update application docs require:

• Delegated: Application.ReadWrite.All

• Application: Application.ReadWrite.OwnedBy or Application.ReadWrite.All

• To keep the docs simple and safe for arbitrary applications, Application.ReadWrite.All is documented for both delegated and application permissions.

---

---

Testing

Setup:

• Created a Microsoft Entra app registration with:

• Application.Read.All

• Application.ReadWrite.All

• Granted admin consent for these permissions.

• Logged in to CLI with this app using device code flow.

Commands exercised:

• m365 entra app role list --appObjectId

• Succeeds and returns [] when no roles exist; lists roles once they are present.

• m365 entra app role add --appObjectId  --name ... --description ... --allowedMembers usersGroups --claim managers

• Requires both:

• Application.ReadWrite.All on the CLI app

• A sufficient directory role (e.g. Application Administrator) for the signed-in user; otherwise Graph returns Insufficient privileges to complete the operation.

• m365 entra app role remove --appObjectId  --name "Managers" --force

• Same permission and role requirement pattern as app role add.

These behaviors are consistent with the Microsoft Graph documentation for the underlying applications endpoints and with the permissions documented in the new Permissions sections.

---

Notes

• The Permissions sections document minimal Graph scopes. Some operations also require the signed-in user to have specific Microsoft Entra roles (Application Administrator, Cloud Application Administrator, etc.); those role requirements depend on tenant configuration and are not encoded as OAuth scopes.

• This PR only touches docs for the three app role commands; no runtime behavior has been changed.

[milanholemans]

Thanks @AlejandroGispert, we'll try to review it ASAP!

[MartinM85]

Only a few minor notes related to the formatting, great job @AlejandroGispert otherwise!

[AlejandroGispert]

@MartinM85 I have fixed the formatting issues and squashed the commits. Ready for another look when you have time.
Feel free to assign me another task if you would like becuaseI have time to work on something over the weekend.

[MartinM85]

Approved. Thank you for the contribution.

I will merge it later.

[MartinM85]

@MartinM85 I have fixed the formatting issues and squashed the commits. Ready for another look when you have time. Feel free to assign me another task if you would like becuaseI have time to work on something over the weekend.

Hi @AlejandroGispert, it's up to you which ticket you take next time. I can only recommend it. You can try a similar ticket with minimal permissions.

https://github.com/pnp/cli-microsoft365/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22%20label%3A%22help%20wanted%22

In the comment of the given ticket, mention that you are taking it and we will assign you the ticket.

[AlejandroGispert]

Hi @milanholemans, its fixed now

[AlejandroGispert]

Hi @milanholemans does this PR need any more fixing?

[MartinM85]

Approved