Skip to content

rbacapplication-post-roleassignmentschedulerequests.md

Latest commit

 

History

History
306 lines (254 loc) · 15.5 KB

rbacapplication-post-roleassignmentschedulerequests.md

File metadata and controls

306 lines (254 loc) · 15.5 KB
title Create roleAssignmentScheduleRequests
description In PIM, request for an active and persistent role assignment through the unifiedRoleAssignmentScheduleRequest object. Use this API to activate eligible roles.
author rkarim-ms
ms.localizationpriority medium
ms.subservice entra-id-governance
doc_type apiPageType
ms.date 04/04/2024

Create roleAssignmentScheduleRequests

Namespace: microsoft.graph

In PIM, carry out the following operations through the unifiedRoleAssignmentScheduleRequest object:

  • Request active and persistent role assignments for a principal, with or without expiry dates.
  • Activate, deactivate, extend, or renew an eligible role assignment for a principal.

To call this API to update, renew, and extend assignments for yourself, you must have multifactor authentication (MFA) enforced, and running the query in a session in which they were challenged for MFA. See Enable per-user Microsoft Entra multifactor authentication to secure sign-in events.

[!INCLUDE national-cloud-support]

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

[!INCLUDE permissions-table]

[!INCLUDE rbac-pim-entra-roles-apis]

HTTP request

POST /roleManagement/directory/roleAssignmentScheduleRequests

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.

Request body

In the request body, supply a JSON representation of the unifiedRoleAssignmentScheduleRequest object.

You can specify the following properties when creating an unifiedRoleAssignmentScheduleRequest.

Property Type Description
action unifiedRoleScheduleRequestActions Represents the type of the operation on the role assignment request. The possible values are: adminAssign, adminUpdate, adminRemove, selfActivate, selfDeactivate, adminExtend, adminRenew, selfExtend, selfRenew, unknownFutureValue.
  • adminAssign: For administrators to assign roles to users or groups.
  • adminRemove: For administrators to remove users or groups from roles.
  • adminUpdate: For administrators to change existing role assignments.
  • adminExtend: For administrators to extend expiring assignments.
  • adminRenew: For administrators to renew expired assignments.
  • selfActivate: For users to activate their assignments.
  • selfDeactivate: For users to deactivate their active assignments.
  • selfExtend: For users to request to extend their expiring assignments.
  • selfRenew: For users to request to renew their expired assignments.
customData String Free text field to define any custom data for the request. Optional.
principalId String Identifier of the principal that has been granted the assignment. Required.
roleDefinitionId String Identifier of the unifiedRoleDefinition object that is being assigned. Required.
directoryScopeId String Identifier of the directory object representing the scope of the assignment. The scope of an assignment determines the set of resources for which the principal has been granted access. Directory scopes are shared scopes stored in the directory that are understood by multiple applications. Use / for tenant-wide scope. Use appScopeId to limit the scope to an application only. Either directoryScopeId or appScopeId is required.
appScopeId String Identifier of the app-specific scope when the assignment is scoped to an app. The scope of an assignment determines the set of resources for which the principal has been granted access. App scopes are scopes that are defined and understood by this application only. Use / for tenant-wide app scopes. Use directoryScopeId to limit the scope to particular directory objects, for example, administrative units. Either directoryScopeId or appScopeId is required.
justification String A message provided by users and administrators when create they create the unifiedRoleAssignmentScheduleRequest object.

Optional for selfDeactivate and adminRemove actions; might be optional or required for other action types depending on the rules in the policy that's linked to the Microsoft Entra role. For more information, see Rules in PIM.
scheduleInfo requestSchedule The period of the role assignment request. Recurring schedules are currently unsupported. Required.
ticketInfo ticketInfo Ticket details linked to the role assignment request including details of the ticket number and ticket system.

Optional for selfDeactivate and adminRemove actions; might be optional or required for other action types depending on the rules in the policy that's linked to the Microsoft Entra role. For more information, see Rules in PIM.

Response

If successful, this method returns a 201 Created response code and an unifiedRoleAssignmentScheduleRequest object in the response body.

Examples

Example 1: Admin assigning a directory role to a principal

In the following request, the admin creates a request to assign a role identified by fdd7a751-b60b-444a-984c-02652fe8fa1c to a principal identified by ID 071cc716-8147-4397-a5ba-b2105951cc0b. The scope of their role is all directory objects in the tenant and the assignment is permanent.

Request

HTTP

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleRequests
Content-Type: application/json

{
    "action": "adminAssign",
    "justification": "Assign Groups Admin to IT Helpdesk group",
    "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
    "directoryScopeId": "/",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "scheduleInfo": {
        "startDateTime": "2022-04-10T00:00:00Z",
        "expiration": {
            "type": "NoExpiration"
        }
    }
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
    "id": "95c690fb-3eb3-4942-a03f-4524aed6f31e",
    "status": "Provisioned",
    "createdDateTime": "2022-04-11T11:50:03.9014347Z",
    "completedDateTime": "2022-04-11T11:50:05.9999343Z",
    "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
    }
}

Example 2: User activating their eligible role

Request

In the following request, a user identified by principalId 071cc716-8147-4397-a5ba-b2105951cc0b activates their own eligible role to a Microsoft Entra role identified by ID 8424c6f0-a189-499e-bbd0-26c1753c96d4. The scope of their role is all directory objects in the tenant and the assignment is for five hours. To run this request, the calling user must have multifactor authentication (MFA) enforced, and running the query in a session in which they were challenged for MFA.

To retrieve the details of their eligibility requests and identify the eligibility to activate, the user will call the unifiedRoleEligibilitySchedule: filterByCurrentUser API.

HTTP

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleRequests/
Content-Type: application/json

{
    "action": "selfActivate",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
    "directoryScopeId": "/",
    "justification": "I need access to the Attribute Administrator role to manage attributes to be assigned to restricted AUs",
    "scheduleInfo": {
        "startDateTime": "2022-04-14T00:00:00.000Z",
        "expiration": {
            "type": "AfterDuration",
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Normal-67890",
        "ticketSystem": "MS Project"
    }
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@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"
    }
}