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

martinlingstuyl · 2024-01-16T12:54:20Z

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 'admin-john@contoso.com' --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": "alexw@contoso.com",
		"mail": "alexw@contoso.com",
		"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)

The text was updated successfully, but these errors were encountered:

waldekmastykarz · 2024-01-21T09:42:56Z

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 · 2024-04-10T09:09:43Z

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

martinlingstuyl · 2024-04-13T05:14:24Z

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

Jwaegebaert · 2024-04-16T07:02:27Z

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

MartinM85 · 2024-04-19T10:42:14Z

@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 · 2024-04-19T10:46:51Z

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 · 2024-04-19T10:49:49Z

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 · 2024-04-19T10:55:11Z

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

martinlingstuyl mentioned this issue Jan 16, 2024

Add commands for PIM (Privileged Identity Management) in the context of users activating Microsoft Entra Roles #5669

Open

11 tasks

martinlingstuyl added new feature needs peer review Needs second pair of eyes to review the spec or PR labels Jan 16, 2024

martinlingstuyl added enhancement good first issue and removed needs peer review Needs second pair of eyes to review the spec or PR labels Feb 4, 2024

martinlingstuyl changed the title ~~New command: 'm365 entra pim roleassignment request list' - Retrieves a list of role assignment requests for a user or group~~ New command: 'm365 entra pim request list' - Retrieves a list of PIM requests Feb 10, 2024

martinlingstuyl changed the title ~~New command: 'm365 entra pim request list' - Retrieves a list of PIM requests~~ New command: 'm365 entra pim roles request list' - Retrieves a list of PIM requests for roles Feb 13, 2024

martinlingstuyl added the needs design label Feb 13, 2024

martinlingstuyl changed the title ~~New command: 'm365 entra pim roles request list' - Retrieves a list of PIM requests for roles~~ New command: 'm365 entra pim role request list' - Retrieves a list of PIM requests for roles Feb 18, 2024

Jwaegebaert assigned MartinM85 Apr 16, 2024

Jwaegebaert added work in progress and removed needs design enhancement labels Apr 16, 2024

MartinM85 linked a pull request Apr 20, 2024 that will close this issue

New command: 'm365 entra pim role request list'. Closes #5781 #5986

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

martinlingstuyl commented Jan 16, 2024 •

edited

waldekmastykarz commented Jan 21, 2024

MartinM85 commented Apr 10, 2024

martinlingstuyl commented Apr 13, 2024

Jwaegebaert commented Apr 16, 2024

MartinM85 commented Apr 19, 2024

martinlingstuyl commented Apr 19, 2024

martinlingstuyl commented Apr 19, 2024

MartinM85 commented Apr 19, 2024

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

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

Comments

martinlingstuyl commented Jan 16, 2024 • edited

Usage

Description

Options

Examples

Response

Response with details of the principal

Default properties

Additional information

waldekmastykarz commented Jan 21, 2024

MartinM85 commented Apr 10, 2024

martinlingstuyl commented Apr 13, 2024

Jwaegebaert commented Apr 16, 2024

MartinM85 commented Apr 19, 2024

martinlingstuyl commented Apr 19, 2024

martinlingstuyl commented Apr 19, 2024

MartinM85 commented Apr 19, 2024

martinlingstuyl commented Jan 16, 2024 •

edited