Skip to content

New command: 'm365 entra pim role assignment add' - Request activation of an Entra role assignment #5766

Closed
Closed
New command: 'm365 entra pim role assignment add' - Request activation of an Entra role assignment#5766
Assignees
MartinM85
Labels
new feature
Milestone
v7.7
@martinlingstuyl

Description

@martinlingstuyl
martinlingstuyl
opened on Jan 8, 2024

The first hurdle in the PIM space: requesting activation of a role. By default it will request activation of a role assignment for the current user. But it's also possible to request activation as an admin for another user.

Usage

m365 entra pim role assignment add [options]

Description

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

Options

Option Description
-n, --roleDefinitionName [roleDefinitionName] Name of the role definition that should be assigned. Specify either roleDefinitionName or roleDefinitionId but not both.
-i, --roleDefinitionId [roleDefinitionId] Id of the role definition that is being assigned. Specify either roleDefinitionName or roleDefinitionId but not both.
--userId [userId] Id of the user that will be granted the assignment. Specify either userId, userName, groupId or groupName. If not specified, the current user will be used.
--userName [userName] UPN of the user that will be granted the assignment. Specify either userId, userName, groupId or groupName. If not specified, the current user will be used.
--groupId [groupId] Id of the group that will be granted the assignment. Specify either userId, userName, groupId or groupName. If not specified, the current user will be used.
--groupName [groupName] Display name of the group that will be granted the assignment. 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 of the assignment. Will default to tenant-wide scope if not specified.
-j, --justification [justification] An optional justification message.
-s, --startDateTime [startDateTime] When the assignment should start. If left out, the assignment will start from the current time.
-e, --endDateTime [endDateTime] When the assignment should end. Specify either duration or endDateTime.
-d, --duration [duration] How long the assignment should last. Write in ISO 8601 format for durations: PT3H for 3 hours.
--ticketNumber [ticketNumber] Optional ticket number value to communicate with the request.
--ticketSystem [ticketSystem] Optional ticket system to communicate with the request.

Examples

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

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

Request activation of an Entra ID role assignment for the current user.

m365 entra pim role assignment add --roleDefinitionId 'f1417aa3-bf0b-4cc5-a845-a0b2cf11f690'

Request activation of an Entra ID role assignment for the current user with a justification and max duration of 4 hours.

m365 entra pim role assignment add --roleDefinitionId 'f1417aa3-bf0b-4cc5-a845-a0b2cf11f690' --justification 'Need Global Admin to release application xyz to production' --duration 'PT4H'

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

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

Request activation of an Entra ID role assignment for a specific period of two days.

m365 entra pim role assignment add --roleDefinitionName 'Global Administrator' --userId '[email protected]' --startDateTime '2024-01-10T09:00:00Z' --endDateTime '2024-01-11T17:00:00Z'

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 adminAssign or selfActivate, 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

First specs, created for 'm365 entra pim roleassignment request add'

Usage

m365 entra pim roleassignment request add [options]

Description

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

Options

Option Description
-n, --roleDefinitionName [roleDefinitionName] Name of the role definition that should be assigned. Specify either roleDefinitionName or roleDefinitionId but not both.
-i, --roleDefinitionId [roleDefinitionId] Id of the role definition that is being assigned. Specify either roleDefinitionName or roleDefinitionId but not both.
-p, --principalId [principalId] Id of the user or group that has been granted the assignment. Will default to the Id of the signed-in user if not specified. Is required when running in app-only mode.
-a, --action [action] Represents the type of the role assignment request. Allowed values are: adminAssign, adminUpdate, adminRemove, selfActivate, selfDeactivate, adminExtend, adminRenew, selfExtend, selfRenew. Defaults to selfActivate.
-d, --directoryScopeId [directoryScopeId] Id of the directory object representing the scope of the assignment. Specify either directoryScopeId or appScopeId. If none is specified, will default to tenant-wide scope.
--appScopeId [appScopeId] Id of an app-specific scope. Specify either directoryScopeId or appScopeId. If none is specified, will default to tenant-wide scope.
-j, --justification [justification] An optional justification message.
-s, --startDateTime [startDateTime] When the assignment should start. If left out, the assignment will start from the current time.
-d, --duration [duration] How long the assignment should last. Write in ISO 8601 format for durations: PT3H for 3 hours.
--ticketNumber [ticketNumber] Optional ticket number value to communicate with the request.
--ticketSystem [ticketSystem] Optional ticket system to communicate with the request.

Remarks

Use the principalId option to request a role assignment for other users or groups. Only use actions selfActivate and selfDeactivate when not specifying principalId.

Examples

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

m365 entra pim roleassignment request add --roleDefinitionName 'SharePoint Administrator'

Request activation of an Entra ID role assignment for the current user.

m365 entra pim roleassignment request add --roleDefinitionId 'f1417aa3-bf0b-4cc5-a845-a0b2cf11f690'

Request activation of an Entra ID role assignment for the current user with a justification and max duration of 4 hours.

m365 entra pim roleassignment request add --roleDefinitionId 'f1417aa3-bf0b-4cc5-a845-a0b2cf11f690' --justification 'Need Global Admin to release application xyz to production' --duration 'PT4H'

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

m365 entra pim roleassignment request add --roleDefinitionId 'f1417aa3-bf0b-4cc5-a845-a0b2cf11f690' --action adminAssign --principalId '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

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

Metadata

Metadata

Assignees

Labels

new feature

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions