governanceRoleAssignmentRequest erstellen

  • Artikel

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Achtung

Diese Version der Privileged Identity Management-API (PIM-API) für Azure-Ressourcen wird in Kürze eingestellt. Verwenden Sie die neue Azure REST PIM-API für Azure-Ressourcenrollen.

Erstellen Sie eine Rollenzuweisungsanforderung, um den gewünschten Vorgang für eine Rollenzuweisung darzustellen. In der folgenden Tabelle sind die Vorgänge aufgeführt.

Vorgang Typ
Zuweisen einer Rollenzuweisung AdminHind hinzufügen
Aktivieren einer berechtigten Rollenzuweisung Useradd
Deaktivieren einer aktivierten Rollenzuweisung UserRemove
Entfernen einer Rollenzuweisung AdminRemove
Aktualisieren einer Rollenzuweisung AdminUpdate
Anfordern der Erweiterung meiner Rollenzuweisung UserExtend
Erweitern einer Rollenzuweisung AdminExtend
Anfordern der Verlängerung meiner abgelaufenen Rollenzuweisung UserRenew
Verlängern einer abgelaufenen Rollenzuweisung AdminRenew

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet
✅ ✅ ✅ ❌

Berechtigungen

In der folgenden Tabelle sind die Berechtigungen mit den geringsten Berechtigungen aufgeführt, die zum Aufrufen dieser API für jeden unterstützten Ressourcentyp erforderlich sind. Befolgen Sie bewährte Methoden , um Berechtigungen mit den geringsten Berechtigungen anzufordern. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Unterstützte Ressource Delegiert (Geschäfts-, Schul- oder Unikonto) Delegiert (persönliches Microsoft-Konto) Anwendung
Microsoft Entra-ID PrivilegedAccess.ReadWrite.AzureAD Nicht unterstützt Nicht unterstützt
Azure-Ressourcen PrivilegedAccess.ReadWrite.AzureResources Nicht unterstützt Nicht unterstützt
Gruppe PrivilegedAccess.ReadWrite.AzureADGroup Nicht unterstützt Nicht unterstützt

HTTP-Anforderung

POST /privilegedAccess/azureResources/roleAssignmentRequests

Anforderungsheader

Name Beschreibung
Authorization Bearer {code}
Content-type application/json

Anforderungstext

Geben Sie im Anforderungstext eine JSON-Darstellung eines governanceRoleAssignmentRequest-Objekts an.

Eigenschaft Typ Beschreibung
resourceId String Der eindeutige Bezeichner der Azure-Ressource, die der Rollenzuweisungsanforderung zugeordnet ist. Azure-Ressourcen können Abonnements, Ressourcengruppen, virtuelle Computer und SQL-Datenbanken umfassen. Erforderlich.
roleDefinitionId String Der Bezeichner der Azure-Rollendefinition, der die Rollenzuweisungsanforderung zugeordnet ist. Erforderlich.
subjectId String Der eindeutige Bezeichner des Prinzipals oder Antragstellers, dem die Rollenzuweisungsanforderung zugeordnet ist. Prinzipale können Benutzer, Gruppen oder Dienstprinzipale sein. Erforderlich.
assignmentState String Der Status der Zuweisung. Der Wert kann und ActiveseinEligible. Erforderlich.
type String Der Anforderungstyp. Der Wert kann , , UserAdd, AdminUpdateAdminRemove, UserRemove, UserExtend, UserRenewund AdminExtendseinAdminRenewAdminAdd. Erforderlich.
reason String Der Grund muss für die Rollenzuweisungsanforderung zu Überwachungs- und Überprüfungszwecken angegeben werden.
Zeitplan governanceSchedule Der Zeitplan der Rollenzuweisungsanforderung. Für den Anforderungstyp UserAdd, AdminAdd, AdminUpdateund AdminExtendist dies erforderlich.

Antwort

Bei erfolgreicher Ausführung gibt die Methode einen 201 Created Antwortcode und ein governanceRoleAssignmentRequest-Objekt im Antworttext zurück.

Fehlercodes

Diese API gibt die HTTP-Standardfehlercodes zurück. Darüber hinaus werden auch die in der folgenden Tabelle aufgeführten Fehlercodes zurückgegeben.

Fehlercode Fehlermeldung Details
400 BadRequest RoleNotFound Die roleDefinitionId im Anforderungstext angegebene kann nicht gefunden werden.
400 BadRequest ResourceIsLocked Die im Anforderungstext bereitgestellte Ressource befindet sich im Zustand und kann keine Rollenzuweisungsanforderungen Locked erstellen.
400 BadRequest SubjectNotFound Die subjectId im Anforderungstext angegebene kann nicht gefunden werden.
400 BadRequest PendingRoleAssignmentRequest Es ist bereits eine ausstehende governanceRoleAssignmentRequest im System vorhanden.
400 BadRequest RoleAssignmentExists Die für die Erstellung angeforderte governanceRoleAssignment ist bereits im System vorhanden.
400 BadRequest RoleAssignmentDoesNotExist Die für die Aktualisierung/Erweiterung angeforderte governanceRoleAssignment ist im System nicht vorhanden.
400 BadRequest RoleAssignmentRequestPolicyValidationFailed GovernanceRoleAssignmentRequest erfüllt keine internen Richtlinien und kann nicht erstellt werden.

Beispiele

In den folgenden Beispielen wird die Verwendung dieser API veranschaulicht.

Beispiel 1: Der Administrator weist einen Benutzer einer Rolle zu

In diesem Beispiel weist ein Administrator den Benutzer nawu@contoso.com der Rolle Abrechnungsleser zu.

Hinweis: Zusätzlich zur Berechtigung erfordert dieses Beispiel, dass der anfordernde Benutzer mindestens eine Active Administratorrollenzuweisung (owner oder user access administrator) für die Ressource hat.

Eigenschaft Typ Erforderlich Wert
resourceId String Ja <resourceId>
roleDefinitionId String Ja <roleDefinitionId>
subjectId String Ja <subjectId>
assignmentState String Ja Berechtigt/Aktiv
type String Ja AdminHind hinzufügen
reason String hängt von den Rolleneinstellungen ab.
Zeitplan governanceSchedule Ja

Anforderung

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "ea48ad5e-e3b0-4d10-af54-39a45bbfe68d",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Eligible",
  "type": "AdminAdd",
  "reason": "Assign an eligible role",
  "schedule": {
    "startDateTime": "2018-05-12T23:37:43.356Z",
    "endDateTime": "2018-11-08T23:37:43.356Z",
    "type": "Once"
  }
}

Antwort

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "1232e4ea-741a-4be5-8044-5edabdd61672",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "ea48ad5e-e3b0-4d10-af54-39a45bbfe68d",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminAdd",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Evaluate Only",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:37:43.356Z",
    "endDateTime": "2018-11-08T23:37:43.356Z",
    "duration": "PT0S"
  }
}

Beispiel 2: Benutzer aktiviert berechtigte Rolle

In diesem Beispiel aktiviert der Benutzer nawu@contoso.com die berechtigte Rolle Abrechnungsleser.

Eigenschaft Typ Erforderlich Wert
resourceId String Ja <resourceId>
roleDefinitionId String Ja <roleDefinitionId>
subjectId String Ja <subjectId>
assignmentState String Ja Aktiv
type String Ja Useradd
reason String hängt von den Rolleneinstellungen ab.
Zeitplan governanceSchedule Ja

Anforderung

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "8b4d1d51-08e9-4254-b0a6-b16177aae376",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Active",
  "type": "UserAdd",
  "reason": "Activate the owner role",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:28:43.537Z",
    "duration": "PT9H"
  },
  "linkedEligibleRoleAssignmentId": "e327f4be-42a0-47a2-8579-0a39b025b394"
}

Antwort

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "3ad49a7c-918e-4d86-9f84-fab28f8658c0",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "8b4d1d51-08e9-4254-b0a6-b16177aae376",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "e327f4be-42a0-47a2-8579-0a39b025b394",
  "type": "UserAdd",
  "assignmentState": "Active",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Activate the owner role",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "EligibilityRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      },
      {
        "key": "JustificationRule",
        "value": "Grant"
      },
      {
        "key": "ActivationDayRule",
        "value": "Grant"
      },
      {
        "key": "ApprovalRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:28:43.537Z",
    "endDateTime": "0001-01-01T00:00:00Z",
    "duration": "PT9H"
  }
}

Beispiel 3: Benutzer deaktiviert eine zugewiesene Rolle

In diesem Beispiel deaktiviert der Benutzer nawu@contoso.com die aktive Rolle Abrechnungsleser.

Eigenschaft Typ Erforderlich Wert
resourceId String Ja <resourceId>
roleDefinitionId String Ja <roleDefinitionId>
subjectId String Ja <subjectId>
assignmentState String Ja Aktiv
type String Ja UserRemove
reason String Nein
Zeitplan governanceSchedule Nein

Anforderung

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "bc75b4e6-7403-4243-bf2f-d1f6990be122",
  "resourceId": "fb016e3a-c3ed-4d9d-96b6-a54cd4f0b735",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Active",
  "type": "UserRemove",
  "reason": "Deactivate the role",
  "linkedEligibleRoleAssignmentId": "cb8a533e-02d5-42ad-8499-916b1e4822ec"
}

Antwort

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "abfcdb57-8e5d-42a0-ae67-7598b96fddb1",
  "resourceId": "fb016e3a-c3ed-4d9d-96b6-a54cd4f0b735",
  "roleDefinitionId": "bc75b4e6-7403-4243-bf2f-d1f6990be122",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "cb8a533e-02d5-42ad-8499-916b1e4822ec",
  "type": "UserRemove",
  "assignmentState": "Active",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Evaluate only",
  "schedule": null,
  "status": {
    "status": "Closed",
    "subStatus": "Revoked",
    "statusDetails": []
  }
}

Beispiel 4: Der Administrator entfernt den Benutzer aus einer Rolle.

In diesem Beispiel entfernt ein Administrator den Benutzer nawu@contoso.com aus der Rolle Abrechnungsleser.

Hinweis: Zusätzlich zur Berechtigung erfordert dieses Beispiel, dass der anfordernde Benutzer mindestens eine Active Administratorrollenzuweisung (owner oder user access administrator) für die Ressource hat.

Eigenschaft Typ Erforderlich Wert
resourceId String Ja <resourceId>
roleDefinitionId String Ja <roleDefinitionId>
subjectId String Ja <subjectId>
assignmentState String Ja Berechtigt/Aktiv
type String Ja AdminRemove
reason String Nein
Zeitplan governanceSchedule Nein

Anforderung

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "65bb4622-61f5-4f25-9d75-d0e20cf92019",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "assignmentState": "Eligible",
  "type": "AdminRemove"
}

Antwort

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "c934fcb9-cf53-42ac-a8b4-6246f6726299",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "65bb4622-61f5-4f25-9d75-d0e20cf92019",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminRemove",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": null,
  "status": {
    "status": "Closed",
    "subStatus": "Revoked",
    "statusDetails": []
  },
  "schedule": null
}

Beispiel 5: Administrator aktualisiert die Rollenzuweisung

In diesem Beispiel aktualisieren Administratoren die Rollenzuweisung für den Benutzer nawu@contoso.com auf Besitzer.

Hinweis: Zusätzlich zur Berechtigung erfordert dieses Beispiel, dass der anfordernde Benutzer mindestens eine Active Administratorrollenzuweisung (owner oder user access administrator) für die Ressource hat.

Eigenschaft Typ Erforderlich Wert
resourceId String Ja <resourceId>
roleDefinitionId String Ja <roleDefinitionId>
subjectId String Ja <subjectId>
assignmentState String Ja Berechtigt/Aktiv
type String Ja AdminUpdate
reason String hängt von roleSettings ab.
Zeitplan governanceSchedule Ja

Anforderung

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "70521f3e-3b95-4e51-b4d2-a2f485b02103",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "1566d11d-d2b6-444a-a8de-28698682c445",
  "assignmentState": "Eligible",
  "type": "AdminUpdate",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-03-08T05:42:45.317Z",
    "endDateTime": "2018-06-05T05:42:31.000Z"
  }
}

Antwort

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "4f6d4802-b3ac-4f5a-86d7-a6a4edd7d383",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "70521f3e-3b95-4e51-b4d2-a2f485b02103",
  "subjectId": "1566d11d-d2b6-444a-a8de-28698682c445",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminUpdate",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": null,
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-03-08T05:42:45.317Z",
    "endDateTime": "2018-06-05T05:42:31Z",
    "duration": "PT0S"
  }
}

Beispiel 6: Administrator erweitert ablaufende Rollenzuweisung

In diesem Beispiel wird die ablaufende Rollenzuweisung für den Benutzer ANUJCUSER auf API Management Dienstmitwirkender erweitert.

Hinweis: Zusätzlich zur Berechtigung erfordert dieses Beispiel, dass der anfordernde Benutzer mindestens eine Active Administratorrollenzuweisung (owner oder user access administrator) für die Ressource hat.

Eigenschaft Typ Erforderlich Wert
resourceId String Ja <resourceId>
roleDefinitionId String Ja <roleDefinitionId>
subjectId String Ja <subjectId>
assignmentState String Ja Berechtigt/Aktiv
type String Ja AdminExtend
reason String hängt von roleSettings ab.
Zeitplan governanceSchedule Ja

Anforderung

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "0e88fd18-50f5-4ee1-9104-01c3ed910065",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "assignmentState": "Eligible",
  "type": "AdminExtend",
  "reason": "extend role assignment",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:53:55.327Z",
    "endDateTime": "2018-08-10T23:53:55.327Z"
  }
}

Antwort

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "486f0c05-47c8-4498-9c06-086a78c83004",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "0e88fd18-50f5-4ee1-9104-01c3ed910065",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminExtend",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "extend role assignment",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:53:55.327Z",
    "endDateTime": "2018-08-10T23:53:55.327Z",
    "duration": "PT0S"
  }
}