New command: 'm365 entra pim role assignment list' - Retrieves a list of role assignments for a user or group

[martinlingstuyl]

Aside from checking the list of pim requests, an important part of pim is checking what roles you have been assigned. (Either through PIM, or directly through RBAC)

Usage

m365 entra pim role assignment list [options]

Description

Retrieves a list of Entra role assignments for a user or group.

Options

Option	Description
--userId [userId]	Id of the user for which to list role assignments for. Specify either userId, userName, groupId or groupName. If not specified, all eligible roles will be listed.
--userName [userName]	UPN of the user for which to list role assignments for. Specify either userId, userName, groupId or groupName. If not specified, all eligible roles will be listed.
--groupId [groupId]	Id of the group for which to list role assignments for. Specify either userId, userName, groupId or groupName. If not specified, all eligible roles will be listed.
--groupName [groupName]	Display name of the group for which to list role assignments for. Specify either userId, userName, groupId or groupName. If not specified, all eligible roles will be listed.
-s, --startDateTime [startDateTime]	An optional ISO 8601 formatted date filter to search from.
--includePrincipalDetails	An optional flag to include details of the principals that were assigned a role

Examples

Get a list of Entra role assignments.

m365 entra pim role assignment list

Get a list of Entra role assignments for the current user.

m365 entra pim role assignment list --principalId '@meID'

Get a list of Entra role assignments since the first of January 2024

m365 entra pim role assignment list --startDateTime 2024-01-01T00:00:00Z

Get a list of Entra role assignments with principal details.

m365 entra pim role assignment list --includePrincipalDetails

Response

 [
        {
            "id": "lAPpYvVpN0KRkAEhdxReEAWz5Gtet_xOv8wxvTtTpfg-1",
            "principalId": "6be4b305-b75e-4efc-bfcc-31bd3b53a5f8",
            "roleDefinitionId": "62e90394-69f5-4237-9190-012177145e10",
            "directoryScopeId": "/",
            "appScopeId": null,
            "startDateTime": null,
            "endDateTime": null,
            "assignmentType": "Assigned",
            "memberType": "Direct",
            "roleAssignmentOriginId": "lAPpYvVpN0KRkAEhdxReEAWz5Gtet_xOv8wxvTtTpfg-1",
            "roleAssignmentScheduleId": "lAPpYvVpN0KRkAEhdxReEAWz5Gtet_xOv8wxvTtTpfg-1",            
            "roleDefinitionName": "Global Administrator",
        }
    ]

Response with principal details

 [
        {
            "id": "lAPpYvVpN0KRkAEhdxReEAWz5Gtet_xOv8wxvTtTpfg-1",
            "principalId": "6be4b305-b75e-4efc-bfcc-31bd3b53a5f8",
            "roleDefinitionId": "62e90394-69f5-4237-9190-012177145e10",
            "directoryScopeId": "/",
            "appScopeId": null,
            "startDateTime": null,
            "endDateTime": null,
            "assignmentType": "Assigned",
            "memberType": "Direct",
            "roleAssignmentOriginId": "lAPpYvVpN0KRkAEhdxReEAWz5Gtet_xOv8wxvTtTpfg-1",
            "roleAssignmentScheduleId": "lAPpYvVpN0KRkAEhdxReEAWz5Gtet_xOv8wxvTtTpfg-1",
            "roleDefinitionName": "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 roleDefinitionId, 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-roleassignmentscheduleinstances?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]

Nice! Since this is a list command, which properties are we going to show by default?

[martinlingstuyl]

Added those and opened it up 👍

[MartinM85]

Can I take it?

[martinlingstuyl]

Hi @MartinM85, I'd first like some peer review one other maintainers here, as well as a conclusion on the command group structure. So we'll have to wait a bit still.

[martinlingstuyl]

Ok, @MartinM85 , I've assigned you if you're still interested