Skip to content

rbacapplication-post-roleassignmentschedulerequests.md

Latest commit

 

History

History
305 lines (255 loc) · 14.7 KB

rbacapplication-post-roleassignmentschedulerequests.md

File metadata and controls

305 lines (255 loc) · 14.7 KB
title Create roleAssignmentScheduleRequests
description Create a new unifiedRoleAssignmentScheduleRequest object.
author rkarim-ms
ms.localizationpriority medium
ms.subservice entra-id-governance
doc_type apiPageType
ms.date 04/05/2024

Create roleAssignmentScheduleRequests

Namespace: microsoft.graph

[!INCLUDE beta-disclaimer]

Create a new unifiedRoleAssignmentScheduleRequest object. This operation allows both admins and users to add, remove, extend, or renew assignments. 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. 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.

The following table lists the properties that are required when you create the unifiedRoleAssignmentScheduleRequest.

Property Type Description
id String The unique identifier for the unifiedRoleAssignmentScheduleRequest. Key, not nullable, Read-only.
action String Represents the type of the operation on the role assignment. The possible values are:
  • 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.
principalId String Identifier of the principal to which the assignment is being granted to.
roleDefinitionId String Identifier of the unifiedRoleDefinition the assignment is for. Read only.
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.
appScopeId String Identifier of the app-specific scope when the assignment scope is app-specific. 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.
isValidationOnly Boolean Specifies whether the call is a validation or an actual call. Only set this property if you want to check whether an activation is subject to additional rules like MFA before actually submitting the request.
targetScheduleId String ID of the schedule object attached to the assignment.
justification String A message provided by users and administrators when create the request about why it is needed.
scheduleInfo requestSchedule The schedule object of the role assignment request.
ticketInfo ticketInfo The ticketInfo object attached to the role assignment request which includes details of the ticket number and ticket system.

Response

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

When the calling user was not challenged for multifactor authentication during their sign in session, a request with the SelfActivate action fails and returns a 400 Bad request response code.

Examples

Example 1: Admin assigning a directory role to a principal

Request

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 07706ff1-46c7-4847-ae33-3003830675a1. The scope of their role is all directory objects in the tenant and the assignment is permanent, that is, it doesn't expire.

HTTP

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

{
  "action": "AdminAssign",
  "justification": "Assign User Admin to IT Helpdesk (User) group",
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "directoryScopeId": "/",
  "principalId": "07706ff1-46c7-4847-ae33-3003830675a1",
  "scheduleInfo": {
    "startDateTime": "2021-07-01T00: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

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/beta/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
  "id": "b5a22921-656a-4429-9c4e-59a5f576614d",
  "status": "Provisioned",
  "createdDateTime": "2021-07-27T09:18:40.2029365Z",
  "completedDateTime": "2021-07-27T09:18:42.7811184Z",
  "approvalId": null,
  "customData": null,
  "action": "AdminAssign",
  "principalId": "07706ff1-46c7-4847-ae33-3003830675a1",
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "directoryScopeId": "/",
  "appScopeId": null,
  "isValidationOnly": false,
  "targetScheduleId": "b5a22921-656a-4429-9c4e-59a5f576614d",
  "justification": "Assign User Admin to IT Helpdesk (User) group",
  "createdBy": {
    "application": null,
    "device": null,
    "user": {
      "displayName": null,
      "id": "fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f"
    }
  },
  "scheduleInfo": {
    "startDateTime": "2021-07-27T09:18:42.7811184Z",
    "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 c6ad1942-4afa-47f8-8d48-afb5d8d69d2f activates their own eligible role identified by 9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3. 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.

HTTP

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

{
    "action": "SelfActivate",
    "principalId": "c6ad1942-4afa-47f8-8d48-afb5d8d69d2f",
    "roleDefinitionId": "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3",
    "directoryScopeId": "/",
    "justification": "Need to update app roles for selected apps.",
    "scheduleInfo": {
        "startDateTime": "2021-08-17T17:40: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/beta/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
    "id": "163daf73-8746-4996-87de-ab71dc624bf9",
    "status": "Granted",
    "createdDateTime": "2021-08-17T17:39:36.7040696Z",
    "completedDateTime": "2021-08-17T17:40:00Z",
    "approvalId": null,
    "customData": null,
    "action": "SelfActivate",
    "principalId": "c6ad1942-4afa-47f8-8d48-afb5d8d69d2f",
    "roleDefinitionId": "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": "163daf73-8746-4996-87de-ab71dc624bf9",
    "justification": "Need to update app roles for selected apps.",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "c6ad1942-4afa-47f8-8d48-afb5d8d69d2f"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2021-08-17T17:40:00Z",
        "recurrence": null,
        "expiration": {
            "type": "afterDuration",
            "endDateTime": null,
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Normal-67890",
        "ticketSystem": "MS Project"
    }
}