New command: 'm365 entra pim role request list' - Retrieves a list of PIM requests for roles

[martinlingstuyl]

An important part of the PIM space is checking if you've already requested a roleassignment request and if that request has been approved. We need to have a command to list pim requests.

I've not added the roleassignment noun here on purpose, as the request list can encompass requests for multiple types of requests.

Usage

m365 entra pim role request list [options]

Description

Retrieves a list of PIM requests for roles.

Options

Option	Description
--userId [userId]	Id of the user for which to list requests. Specify either userId, userName, groupId or groupName. If not specified, all requests will be listed.
--userName [userName]	UPN of the user for which to list requests. Specify either userId, userName, groupId or groupName. If not specified, all requests will be listed.
--groupId [groupId]	Id of the group for which to list requests. Specify either userId, userName, groupId or groupName. If not specified, all requests will be listed.
--groupName [groupName]	Display name of the group for which to list requests. Specify either userId, userName, groupId or groupName. If not specified, all requests will be listed.
-c, --createdDateTime [createdDateTime]	An optional ISO 8601 formatted date filter to search from.
-s, --status [status]	An optional value to filter the list of requests. Allowed values are: Canceled, Denied, Failed, Granted, PendingAdminDecision, PendingApproval, PendingProvisioning, PendingScheduleCreation, Provisioned, Revoked, and ScheduleCreated.
--includePrincipalDetails	An optional flag to include details of the principals.

Examples

Get a list of all PIM requests for roles.

m365 entra pim role request list

Get a list of PIM requests for the current user.

m365 entra pim role request list --userId '@meID'

Get a list of PIM requests for a specified user since the first of January 2024

m365 entra pim role request list --userName '[email protected]' --startDateTime 2024-01-01T00:00:00Z

Get a list of PIM requests with principal details

m365 entra pim role request list --includePrincipalDetails

Response

 [
        {
            "id": "95c690fb-3eb3-4942-a03f-4524aed6f31e",
            "status": "Provisioned",
            "createdDateTime": "2022-04-11T11:50:05.95Z",
            "completedDateTime": "2022-04-11T11:50:06Z",
            "approvalId": null,
            "customData": null,
            "action": "adminAssign",
            "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
            "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
            "directoryScopeId": "/",
            "appScopeId": null,
            "isValidationOnly": false,
            "targetScheduleId": "95c690fb-3eb3-4942-a03f-4524aed6f31e",
            "justification": "Assign Groups Admin to IT Helpdesk group",
            "createdBy": {
                "application": null,
                "device": null,
                "user": {
                    "displayName": null,
                    "id": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5"
                }
            },
            "scheduleInfo": {
                "startDateTime": "2022-04-11T11:50:05.9999343Z",
                "recurrence": null,
                "expiration": {
                    "type": "noExpiration",
                    "endDateTime": null,
                    "duration": null
                }
            },
            "ticketInfo": {
                "ticketNumber": null,
                "ticketSystem": null
            }
        },
        "roleDefinition": {
            "displayName": "Global Administrator"
        }
]

Response with details of the principal

 [
        {
            "id": "95c690fb-3eb3-4942-a03f-4524aed6f31e",
            "status": "Provisioned",
            "createdDateTime": "2022-04-11T11:50:05.95Z",
            "completedDateTime": "2022-04-11T11:50:06Z",
            "approvalId": null,
            "customData": null,
            "action": "adminAssign",
            "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
            "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
            "directoryScopeId": "/",
            "appScopeId": null,
            "isValidationOnly": false,
            "targetScheduleId": "95c690fb-3eb3-4942-a03f-4524aed6f31e",
            "justification": "Assign Groups Admin to IT Helpdesk group",
            "createdBy": {
                "application": null,
                "device": null,
                "user": {
                    "displayName": null,
                    "id": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5"
                }
            },
            "scheduleInfo": {
                "startDateTime": "2022-04-11T11:50:05.9999343Z",
                "recurrence": null,
                "expiration": {
                    "type": "noExpiration",
                    "endDateTime": null,
                    "duration": null
                }
            },
            "ticketInfo": {
                "ticketNumber": null,
                "ticketSystem": null
            }
        },
        "roleDefinition": "Global Administrator",
        "principal":  {
		"@odata.type": "#microsoft.graph.user",
		"id": "6be4b305-b75e-4efc-bfcc-31bd3b53a5f8",
		"displayName": "Alex Wilber",
		"userPrincipalName": "[email protected]",
		"mail": "[email protected]",
		"businessPhones": [],
		"givenName": null,
		"jobTitle": null,
		"mobilePhone": null,
		"officeLocation": null,
		"preferredLanguage": null,
		"surname": null
	}
]

The roleDefinitionName property will need to be added to the objects, based on the expanded property roleDefinition.

Default properties

From the response output in text mode we'll show id, roleDefinitionName and principalId

Additional information

Needs Entra permission scopes "RoleAssignmentSchedule.ReadWrite.Directory" and/or "RoleManagement.Read.Directory" OR "Directory.ReadWrite.All" which we already may have. (I'm using ReadWrite, as we're also writing in other subcommands of pim.)

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

By default, we need to expand/request the displayName of the role definition when calling the endpoint, using ?$expand=roleDefinition($select=displayName)

[waldekmastykarz]

Since this is a list command, which properties are we going to display by default? Also, do we need to do any additional work to handle the nested objects in non-JSON outputs?

[MartinM85]

Compared to similar ones, looks good. I will take it once is reviewed by other maintainers

[martinlingstuyl]

Any comments before we open this up @pnp/cli-for-microsoft-365-maintainers?

[Jwaegebaert]

Looks good to me! I'll assign you @MartinM85.

[MartinM85]

@martinlingstuyl Do you want to allow filtering by scheduleInfo/startDateTime or createdDateTime?

What about an option status to allow filter by the status of the role assignment request? Seems to me it can be useful.

https://learn.microsoft.com/en-us/graph/api/resources/request?view=graph-rest-1.0

But the option status can be added later.

[martinlingstuyl]

Do you want to allow filtering by scheduleInfo/startDateTime or createdDateTime?

Good question.. I now see that its not at alle clear...

I think it's more logical to be able to filter from the creation of the request. What about you?

Let's rename the option to createdDateTime!

What about an option status to allow filter by the status of the role assignment request? Seems to me it can be useful.

I really like this one, yes... You need to be able to filter requests that have not been approved yet. I'll add it to the specs. Can you review?

[martinlingstuyl]

I've updated the specs.

We'll need a clear example though, to show how to list requests that need approval. Or something like that.

[MartinM85]

I would also prefer createdDateTime. Spec looks good now. I will add clear examples into the doc