New command: `m365 exchange role assignment add`

MartinM85 commented 5 months ago

Usage

m365 exchange role assignment add [options]

Description

Grants permissions to an application that's accessing data in Exchange Online and specify which mailboxes an app can access.

Options

Option	Description
`--roleDefinitionId [roleDefinitionId]`	Id of a role to be assigned. Specify either `roleDefinitionId` or `roleDefinitionName`, but not both.
`--roleDefinitionName [roleDefinitionName]`	Name of a role to be assigned. Specify either `roleDefinitionId` or `roleDefinitionName`, but not both.
`--principalId [principalId]`	Id of a service principal to which the assignment is granted. Specify either `principalId` or `principalName`, but not both.
`--principalName [principalName]`	Name of a service principal to which the assignment is granted. Specify either `principalId` or `principalName`, but not both.
`--scopeUserId [scopeUserId]`	Id of a user to which the assignment is scoped. Specify either `scopeTenant`, `scopeUserId`, `scopeUserName`, `scopeGroupId`, `scopeGroupName`, `scopeAdministrativeUnitId`, or `scopeAdministrativeUnitName`, but not multiple.
`--scopeUserName [scopeUserName]`	UPN of a user to which the assignment is scoped. Specify either `scopeTenant`, `scopeUserId`, `scopeUserName`, `scopeGroupId`, `scopeGroupName`, `scopeAdministrativeUnitId`, or `scopeAdministrativeUnitName`, but not multiple.
`--scopeGroupId [scopeGroupId]`	Id of a group to which the assignment is scoped. Specify either `scopeTenant`, `scopeUserId`, `scopeUserName`, `scopeGroupId`, `scopeGroupName`, `scopeAdministrativeUnitId`, or `scopeAdministrativeUnitName`, but not multiple.
`--scopeGroupName [scopeGroupName]`	Name of a group to which the assignment is scoped. Specify either `scopeTenant`, `scopeUserId`, `scopeUserName`, `scopeGroupId`, `scopeGroupName`, `scopeAdministrativeUnitId`, or `scopeAdministrativeUnitName`, but not multiple.
`--scopeAdministrativeUnitId [scopeAdministrativeUnitId]`	Id of an administrative unit to which the assignment is scoped. Specify either `scopeTenant`, `scopeUserId`, `scopeUserName`, `scopeGroupId`, `scopeGroupName`, `scopeAdministrativeUnitId`, or `scopeAdministrativeUnitName`, but not multiple.
`--scopeAdministrativeUnitName [scopeAdministrativeUnitName]`	Name of an administrative unit to which the assignment is scoped. Specify either `scopeTenant`, `scopeUserId`, `scopeUserName`, `scopeGroupId`, `scopeGroupName`, `scopeAdministrativeUnitId`, or `scopeAdministrativeUnitName`, but not multiple.
`--scopeTenant`	Specify whether the tenant-wide scope is applied. Specify either `scopeTenant`, `scopeUserId`, `scopeUserName`, `scopeGroupId`, `scopeGroupName`, `scopeAdministrativeUnitId`, or `scopeAdministrativeUnitName`, but not multiple.

Examples

Assign a role specified by id to a service principal specified by id and scope the assignment to the whole tenant

m365 exchange role assignment add --roleDefinitionId 777b752-f9b7-4205-a2b1-5db0d6a0ccfc --principalId 7a2ca997-9461-402e-9882-58088a370889 --scopeTenant

Assign a role specified by id to a service principal specified by id and scope the assignment to a user specified by id

m365 exchange role assignment add --roleDefinitionId 777b752-f9b7-4205-a2b1-5db0d6a0ccfc --principalId 7a2ca997-9461-402e-9882-58088a370889 --scopeUserId a4738dd8-fc0f-4646-87fb-47539f5c651b

Assign a role specified by name to a service principal specified by name and scope the assignment to a group specified by name

m365 exchange role assignment add --roleDefinitionName 'Application Contacts.ReadWrite' --principalName 'ContactsSyncApp' --scopeGroupName 'Marketing'

Assign a role specified by name to a service principal specified by id and scope the assignment to an administrative unit specified by name

m365 exchange role assignment add --roleDefinitionName 'Application Calendars.Read' --principalId fa631c4d-ac9f-4884-a7f5-13c659d177e3 --scopeAdministrativeUnitName 'Equipment - EMEA'

Default properties

No response

Additional Info

Exchange Online RBAC is alternate to application permissions for accessing mailboxes, but without a need to allow application access policy for specific mailboxes via Exchange Online PowerShell.

It simplifies the whole process and admin can avoid to use Exchange Online PowerShell to configure application access policy.

https://learn.microsoft.com/graph/api/rbacapplication-post-roleassignments?view=graph-rest-beta&tabs=http#example-5-create-a-role-assignment-for-exchange-online-provider-with-administrative-unit-scope

https://learn.microsoft.com/exchange/permissions-exo/application-rbac#supported-application-roles

I will work on this

milanholemans commented 5 months ago

Hi @MartinM85

I don't have much expertise in this so I'm just trying to understand how the command would work.

Few remarks:

Let's rename roleId to roleDefinitionId as used in the request. The same goes for roleName.
Let's rename servicePrincipalId to principalId as used in the request. The same goes for servicePrincipalId.
For the other options, I don't really see how these translate to directoryScopeId or appScopeId. Could you clarify this a bit? Is this command only supporting users, groups, and administrative units? When reading the docs, it looks like a lot more is possible. For example applications, attribute sets, ...
Is it currently possible to grant permissions to the entire tenant?

MartinM85 commented 5 months ago

Hi @MartinM85,

Scope is a set of resources that role applies to. The disadvantage here is that the Graph API exposes unified backend model for different types of RBAC providers. Based on the provider, the principal, scope and role have different allowed values. In case of Exchange RBAC provider:

principal is only a service principal.
scope can be
- user - a service principal will be able to access mails/calendars/contacts of a specific user
- group - a service principal will be able to access mails/calendars/contacts of users that are members of a specific group
- administrative unit - a service principal will be able to access mails/calendars/contacts of users that are members of a specific administrative unit
- the entire tenant - a service principal will be able to access mails/calendars/contacts of all users

MartinM85 commented 4 months ago

@pnp/cli-for-microsoft-365-maintainers Any update on this?

MartinM85 commented 3 months ago

@milanholemans @waldekmastykarz Any update on this?

milanholemans commented 3 months ago

Hi @MartinM85, sorry for the late reply. I'm trying to answer all the issues I'm participating in gradually. You say you can use the entire tenant as a scope. How can we do this with this command? Seems like there is not really a straightforward way? Let's add this as an extra example.

MartinM85 commented 1 month ago

Examples updated

MartinM85 commented 1 week ago

Any update on this?

milanholemans commented 5 days ago

Thank you for bringing this back to life @MartinM85, sorry that I lost track of this. Instead of saying that a tenant scope is by default, shouldn't we introduce an option like --scopeTenant or something like that? This way the user will always have to define a scope. This makes sure that he knows where he wants to apply the rule to. Additionally, we don't have to repeat the If no scope is specified, the tenant-wide scope is applied by default. for every option anymore. Does that make sense to you?

MartinM85 commented 4 days ago

scopeTenant option makes sense. Spec updated

milanholemans commented 4 days ago

Ok, I think we're ready then. Should I assign you or open it up?

milanholemans commented 4 days ago

I made a slight edit and updated --scopeEdit [scopeEdit] to a flag.

MartinM85 commented 4 days ago

I will take it

pnp / cli-microsoft365