New command: 'm365 entra pim role assignment remove' - Request deactivation of an Entra role assignment

[martinlingstuyl]

Usage

m365 entra pim role assignment remove [options]

Description

Request deactivation of an Entra ID role assignment for a user or group.

Options

Option	Description
-n, --roleDefinitionName [roleDefinitionName]	Name of the role definition. Specify either roleDefinitionName or roleDefinitionId but not both.
-i, --roleDefinitionId [roleDefinitionId]	Id of the role definition. Specify either roleDefinitionName or roleDefinitionId but not both.
--userId [userId]	Id of the user. Specify either userId, userName, groupId or groupName. If not specified, the current user will be used.
--userName [userName]	UPN of the user. Specify either userId, userName, groupId or groupName. If not specified, the current user will be used.
--groupId [groupId]	Id of the group. Specify either userId, userName, groupId or groupName. If not specified, the current user will be used.
--groupName [groupName]	Display name of the group. Specify either userId, userName, groupId or groupName. If not specified, the current user will be used.
--directoryScopeId [directoryScopeId]	Id of the directory object representing the scope.
--ticketNumber [ticketNumber]	Optional ticket number value to communicate with the request.
--ticketSystem [ticketSystem]	Optional ticket system to communicate with the request.

Examples

Request deactivation of the SharePoint Administrator Entra ID role assignment for the current user.

m365 entra pim role assignment remove --roleDefinitionName 'SharePoint Administrator'

Request deactivation of an Entra ID role assignment for a specified user.

m365 entra pim role assignment remove --roleDefinitionId 'f1417aa3-bf0b-4cc5-a845-a0b2cf11f690' --userId '3488d6b8-6b2e-41c3-9583-1991205323c2'

Response

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
    "id": "911bab8a-6912-4de2-9dc0-2648ede7dd6d",
    "status": "Granted",
    "createdDateTime": "2022-04-13T08:52:32.6485851Z",
    "completedDateTime": "2022-04-14T00:00:00Z",
    "approvalId": null,
    "customData": null,
    "action": "selfActivate",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": "911bab8a-6912-4de2-9dc0-2648ede7dd6d",
    "justification": "I need access to the Attribute Administrator role to manage attributes to be assigned to restricted AUs",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "071cc716-8147-4397-a5ba-b2105951cc0b"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2022-04-14T00:00:00Z",
        "recurrence": null,
        "expiration": {
            "type": "afterDuration",
            "endDateTime": null,
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Normal-67890",
        "ticketSystem": "MS Project"
    }
}

Additional information

The value of the 'action' property of the request object should be either adminRemove or selfDeactivate, depending on if any of the userId, userName etc options are used.

Needs Entra permission scopes "RoleAssignmentSchedule.ReadWrite.Directory" and/or "RoleManagement.Read.Directory" OR "Directory.ReadWrite.All" which we already may have.

https://learn.microsoft.com/en-us/graph/api/rbacapplication-post-roleassignmentschedulerequests?view=graph-rest-1.0&tabs=http

If --roleDefinitionName is used, the CLI should search for the role definition by name using the endpoint:

https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions?$filter=displayName eq 'SharePoint Administrator'&$select=id

[MartinM85]

From previous ticket #5766, appScopeId is not needed. From testing endDateTime and duration options don't have effect for adminRemove or selfDeactive. Removing/deactivating should be performed immediately on server.

[martinlingstuyl]

Thanks @MartinM85, I'll update the specs!

[milanholemans]

Nice spec! Few comments from my side:

• In the description directoryScopeId, you mention a constraint with appScopeId which doesn't exist
• I don't like the repetition of for which the assignment will be revoked in every option description, IMO it's quite verbose since the command is called Request deactivation of an Entra ID role assignment for a user or group..
• For the implementation of the command, maybe let's include 1-2 more examples to make it clearer. E.g. when using directoryScopeId.

[martinlingstuyl]

Thanks @milanholemans !

@MartinM85, would you have an example of the directoryScopeId part? You're the most into this...

[MartinM85]

There are three possible values for directoryScopeId

• / - tenant wide scope
• /administrativeUnits/{unit_id} - scope limited to a specific administrative unit
• /{appObjectId} - scope limited to a specific service principal

[MartinM85]

@martinlingstuyl Can I take it or do you plan to update the spec?

[martinlingstuyl]

By all means!