pnp
New command: 'm365 entra pim role assignment eligibility list' - Retrieves a list of roles a user or group is eligible to be assigned.
Aside from checking the list of active pim roles, an important part of pim is checking what roles you are eligible for.
Usage
m365 entra pim role assignment eligibility list [options]
Description
Retrieves a list of eligible roles a user or group can be assigned to
Options
| Option | Description |
|---|---|
--userId [userId] |
Id of the user for which to list eligible roles. 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 eligible roles. 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 eligible roles. 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 eligible roles. Specify either userId, userName, groupId or groupName. If not specified, all eligible roles will be listed. |
--includePrincipalDetails |
An optional flag to include details of the principals |
Examples
Get a list of eligible roles for any user
m365 entra pim role assignment eligibility list
Get a list of eligible roles for the current user.
m365 entra pim role assignment eligibility list --userId '@meID'
Response
[
{
"id": "8MYkhImhnkm70CbBdTyW1BbHHAdHgZdDpbqyEFlRzAs-1-e",
"principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
"roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
"directoryScopeId": "/",
"appScopeId": null,
"startDateTime": "2022-04-12T14:44:50.287Z",
"endDateTime": "2024-04-10T00:00:00Z",
"memberType": "Direct",
"roleEligibilityScheduleId": "77f71919-62f3-4d0c-9f88-0a0391b665cd",
"roleDefinitionName": "Global Administrator"
}
]
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 and 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-roleeligibilityscheduleinstances?view=graph-rest-1.0&tabs=http
And maybe use this one for the current user: https://learn.microsoft.com/en-us/graph/api/unifiedroleeligibilityscheduleinstance-filterbycurrentuser?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)
Nice! Since it's a list command, which properties are we going to show by default?
What about role definition name, Id and principal id? @waldekmastykarz
We'd have to flatten the roleDefinitionName into the response output, but that's a good idea anyway...
What about role definition name, Id and principal id? @waldekmastykarz
I know too little about pim to decide which values would be useful. I'll go with your gut feeling given you're more experienced in the area.
You would typically use this command to check for eligible roles, so role definition name and Id are helpful. You can use those when creating a pim request.
The principalId is may be only useful when running the command without principalId... you might never want to do that. (I don't see why an admin would use that in that way) so maybe we can also start simple, just the two properties.
Same here. This needs to be peer reviewed and some last i's dotted and t's crossed...
At first sight, I don't have any comments. However, I find eligibility a weird word to use in a command name.
Is eligibility a term that's already used in PIM in this context or is it a word we decided to use? If the latter, we could look for alternatives such as role assignment available list
In PIM you have assigned roles and roles you are eligible to be assigned, so yes.
so yes.
yes, as in: it's a standard word in PIM that we're aligning with, correct?
Correct, you'll find the concept of Eligible roles in both the user interface of Entra ID as well as in the Microsoft Graph API surface.
Additional info probably contains wrong link. I guess the correct one is
https://learn.microsoft.com/en-us/graph/api/rbacapplication-list-roleeligibilityscheduleinstances?view=graph-rest-1.0&tabs=http
Maybe we can add options startDateTime and includePrincipalDetails similar to entra pim role assignment list
I'll update the endpoint indeed. I've also added the options.
We must be sure by the way to also use https://learn.microsoft.com/en-us/graph/api/unifiedroleeligibilityscheduleinstance-filterbycurrentuser?view=graph-rest-1.0&tabs=http
...for the current user. We don't want people to need an administrative role to retrieve their own eligibility
By the way, I'm not sure how useful a startDateTime option is here. What about you? You generally search for any eligible roles I'd say.
@martinlingstuyl
I'll update the endpoint indeed. I've also added the options.
We must be sure by the way to also use https://learn.microsoft.com/en-us/graph/api/unifiedroleeligibilityscheduleinstance-filterbycurrentuser?view=graph-rest-1.0&tabs=http
...for the current user. We don't want people to need an administrative role to retrieve their own eligibility
We can still filter eligible roles by principalId for the current user.
Ok, startDateTime doesn't make sense in this case, can be removed
We can still filter eligible roles by principalId for the current user.
But can you call the endpoint without a administrative role?
We can still filter eligible roles by principalId for the current user.
But can you call the endpoint without a administrative role?
Quick test on my side...a user without any role mentioned in the doc (Global Reader, Security Operator, Security Reader, Security Administrator, or Privileged Role Administrator) can list eligible roles for all users. Maybe the doc is obsolete.
hmmm, but that seems rather odd and insecure. Are you really sure? :-)
hmmm, but that seems rather odd and insecure. Are you really sure? :-)
Yep, I've tried two users. One user is global admin and the second one is a common user without any role. Both of them were able to read eligible roles. I sent a feedback two days ago through the Microsoft Doc about it. Microsoft Doc is not the best place to report possible issues in Graph API, but there is no other way to report bugs.