Share via

Verwenden von Azure PIM zum Verwalten des aktiven Zugriffs mit der REST-API

  • Artikel

Mit Azure Privileged Identity Management (PIM) können Sie den ständigen Administratorzugriff auf privilegierte Rollen beschränken, ermitteln, wer Zugriff hat, und privilegierten Zugriff überprüfen. In diesem Artikel werden die gängigen Methoden zum Verwalten des Zugriffs mithilfe der REST-API beschrieben.

Auflisten aktiver Zuweisungen

Zum Auflisten aktiver Rollenzuweisungen (Listenzugriff) können Sie eine der Rollenzuweisungszeitplaninstanzen – Liste für Bereichs - oder Rollenzuweisungszeitpläne – List For Scope-REST-APIs verwenden. Um die Ergebnisse einzugrenzen, geben Sie einen Bereich und einen optionalen Filter an. Zum Aufrufen der API benötigen Sie Zugriff auf den Vorgang Microsoft.Authorization/roleAssignments/read für den angegebenen Bereich. Allen integrierten Rollen wird Zugriff auf diesen Vorgang gewährt.

Wichtig

Der Unterschied zwischen Zeitplänen und Zeitplaninstanzen besteht darin, dass Zeitpläne-Instanzen zwar nur Zuweisungen enthalten, die zum aktuellen Zeitpunkt aktiv sind, aber auch Zuweisungen enthalten, die in Zukunft aktiv werden.

  1. Beginnen Sie mit der folgenden Anforderung:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleInstances?api-version=2020-10-01&$filter={filter}

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentSchedules?api-version=2020-10-01&$filter={filter}

  2. Ersetzen Sie innerhalb des URIs {scope} durch den Bereich, für den die Rollen aufgelistet werden sollen.

    `Scope` type
    providers/Microsoft.Management/managementGroups/{mg-name} Verwaltungsgruppe
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1 Resource

  3. Ersetzen Sie {filter} durch die Bedingung, die zum Filtern der Liste mit den Rollenzuweisungen angewendet werden soll.

    Filtern BESCHREIBUNG
    $filter=atScope() Listet nur die Rollenzuweisungen für den angegebenen Bereich auf, ohne die Rollenzuweisungen der Unterbereiche.
    $filter=principalId%20eq%20'{objectId}' Listet die Rollenzuweisungen für bestimmte Benutzer, Gruppen oder Dienstprinzipale auf.
    $filter=roleDefinitionId%20eq%20'{roleDefinitionId}' Auflisten von Rollenzuweisungen für eine angegebene Rollendefinition.
    $filter=assignedTo('{objectId}') Listet Rollenzuweisungen für bestimmte Benutzer auf, einschließlich für von Gruppen geerbten Benutzer.
    $filter=asTarget() Listen Sie Rollenzuweisungen für den aktuellen Benutzer oder Dienstprinzipal auf, einschließlich der Rollenzuweisungen, die von Gruppen geerbt wurden.
    $filter=assignedTo('{objectId}')+and+atScope() Listen Sie Rollenzuweisungen für einen angegebenen Benutzer auf, einschließlich von Gruppen geerbten für den angegebenen Bereich, ohne die Rollenzuweisungen in Unterbereichen.

Gewähren einer aktiven Zuweisung

Um eine aktive Rollenzuweisung zu erstellen (Zugriff gewähren), verwenden Sie die Rollenzuweisungszeitplananforderungen – Erstellen der REST-API und geben den Sicherheitsprinzipal, die Rollendefinition, den Zeitplan, den RequestType = AdminAssign und den Bereich an. Um diese API aufzurufen, müssen Sie Zugriff auf den Microsoft.Authorization/roleAssignments/write Vorgang haben. Von den integrierten Rollen verfügen nur Besitzer und Benutzerzugriffsadministrator über Zugriff auf diesen Vorgang.

  1. Verwenden Sie die REST API unter Rollendefinitionen – Auflisten oder lesen Sie Integrierte Rollen in Azure, um den Bezeichner für die zuzuweisende Rollendefinition zu ermitteln.

  2. Verwenden Sie ein GUID-Tool, um einen eindeutigen Bezeichner zu generieren, der für den Bezeichner der Rollenzuweisung verwendet wird. Das Format des Bezeichners ist: 00000000-0000-0000-0000-000000000000

  3. Beginnen Sie mit folgender Anforderung und folgendem Text:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

    {
  "Properties": {
    "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "PrincipalId": "{principalId}",
    "RequestType": "AdminAssign",
    "ScheduleInfo": {
      "StartDateTime": "2020-09-09T21:31:27.91Z",
      "Expiration": {
        "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
        "EndDateTime": null,
        "Duration": "P30D" // Use ISO 8601 format
      }
    }
  }
}

  4. Ersetzen Sie innerhalb des URIs {scope} durch den Bereich für die Rollenzuweisung.

    `Scope` type
    providers/Microsoft.Management/managementGroups/{mg-name} Verwaltungsgruppe
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1 Resource

  5. Ersetzen Sie {roleAssignmentScheduleRequestName} durch den GUID-Bezeichner der Rollenzuweisung.

  6. Ersetzen Sie innerhalb des Anforderungstexts {subscriptionId} durch Ihre Abonnement-ID.

  7. Ersetzen Sie {roleDefinitionId} durch den Bezeichner der Rollendefinition.

  8. Ersetzen Sie {principalId} durch den Objektbezeichner des Benutzers, der Gruppe oder des Dienstprinzipals, der bzw. die der Rolle zugewiesen wird.

Entfernen der aktiven Zuweisung

Um eine aktive Rollenzuweisung zu entfernen (Zugriff entfernen), verwenden Sie die REST-API "Rollenzuweisungszeitplananforderungen – Erstellen ", um eine neue Anforderung zum Widerrufen der Zuweisung zu erstellen und den Sicherheitsprinzipal, die Rollendefinition, den requestType = AdminRemove und den Bereich anzugeben. Zum Aufrufen dieser API benötigen Sie Zugriff auf den Vorgang Microsoft.Authorization/roleAssignments/write. Von den integrierten Rollen verfügen nur Besitzer und Benutzerzugriffsadministrator über Zugriff auf diesen Vorgang.

  1. Verwenden Sie ein GUID-Tool, um einen eindeutigen Bezeichner zu generieren, der für den Bezeichner der Rollenzuweisung verwendet wird. Das Format des Bezeichners ist: 00000000-0000-0000-0000-000000000000

  2. Beginnen Sie mit der folgenden Anforderung:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

    {
  "Properties": {
    "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "PrincipalId": "{principalId}",
    "RequestType": "AdminRemove"
    }
}

  3. Ersetzen Sie innerhalb des URIs {scope} durch den Bereich, um die Rollenzuweisung zu entfernen.

    `Scope` type
    providers/Microsoft.Management/managementGroups/{mg-name} Verwaltungsgruppe
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource

  4. Ersetzen Sie {roleAssignmentScheduleRequestName} durch den GUID-Bezeichner der Rollenzuweisung.

Aktivieren einer berechtigten Rollenzuweisung

Um eine berechtigte Rollenzuweisung zu aktivieren (aktivierten Zugriff zu erhalten), verwenden Sie die Rollenzuweisungszeitplananforderungen – Erstellen der REST-API, um eine neue Anforderung zu erstellen und den Sicherheitsprinzipal, die Rollendefinition, den requestType = SelfActivate und den Bereich anzugeben. Sie müssen über eine berechtigte Rollenzuweisung für den Bereich verfügen, um diese API aufrufen zu können.

  1. Verwenden Sie ein GUID-Tool, um einen eindeutigen Bezeichner zu generieren, der für den Bezeichner der Rollenzuweisung verwendet wird. Das Format des Bezeichners ist: 00000000-0000-0000-0000-000000000000

  2. [Optional] Wählen Sie einen RoleEligibilitySchedule aus, den Sie aktivieren möchten, und rufen Sie die RoleEligibilityScheduleId von der API für Rollenberechtigungszeitpläne ab, um als LinkedRoleEligibilityScheduleIdübergeben zu werden. Dies ist optional, und wenn nicht übergeben wird, wählt das System einen RoleEligibilityScheduleaus.

  3. Beginnen Sie mit der folgenden Anforderung:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

     {
   "Properties": {
     "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
     "PrincipalId": "{principalId}",
     "RequestType": "SelfActivate",
     "ScheduleInfo": {
       "StartDateTime": "2020-09-09T21:31:27.91Z",
       "Expiration": {
         "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
         "EndDateTime": null,
         "Duration": "PT8H" // Use ISO 8601 format
       }
     },
     "LinkedRoleEligibilityScheduleId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleAssignmentSchedules/{roleAssignmentScheduleId}" //Optional
   }
 }

  4. Ersetzen Sie innerhalb des URIs {scope} durch den Bereich, um die Rollenzuweisung zu entfernen.

    `Scope` type
    providers/Microsoft.Management/managementGroups/{mg-name} Verwaltungsgruppe
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource

  5. Ersetzen Sie {roleAssignmentScheduleRequestName} durch den GUID-Bezeichner der Rollenzuweisung.

Deaktivieren einer aktiven Rollenzuweisung

Verwenden Sie zum Aufheben der Aktivierung einer aktivierten Rollenzuweisung (Entfernen des aktivierten Zugriffs) die REST-API "Rollenzuweisungszeitplananforderungen – Erstellen ", um eine neue Anforderung zu erstellen und den Sicherheitsprinzipal, die Rollendefinition, den requestType = SelfDeactivate und den Bereich anzugeben. Zum Aufrufen dieser API muss eine aktivierte Rollenzuweisung im Bereich vorhanden sein.

  1. Verwenden Sie ein GUID-Tool, um einen eindeutigen Bezeichner zu generieren, der für den Bezeichner der Rollenzuweisung verwendet wird. Das Format des Bezeichners ist: 00000000-0000-0000-0000-000000000000

  2. Beginnen Sie mit der folgenden Anforderung:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

     {
   "Properties": {
     "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
     "PrincipalId": "{principalId}",
     "RequestType": "SelfDeactivate"        
   }
 }

  3. Ersetzen Sie innerhalb des URIs {scope} durch den Bereich, um die Rollenzuweisung zu entfernen.

    `Scope` type
    providers/Microsoft.Management/managementGroups/{mg-name} Verwaltungsgruppe
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource

  4. Ersetzen Sie {roleAssignmentScheduleRequestName} durch den GUID-Bezeichner der Rollenzuweisung.

Just-Enough-Access (JEA)

Wenn ein Benutzer über eine berechtigte Rollenzuweisung für eine Ressource (übergeordnete Ressource) verfügt, kann er die Rolle auf einem untergeordneten Bereich der übergeordneten Ressource anstelle des gesamten übergeordneten Bereichs aktivieren. Wenn ein Benutzer Contributor beispielsweise über eine berechtigte Rolle für ein Abonnement verfügt, kann er die Rolle auf der Ebene einer untergeordneten Ressourcengruppe des Abonnements aktivieren.

Um eine Liste aller untergeordneten Elemente einer Ressource abzurufen, auf die Sie berechtigter Zugriff haben, können Sie die API für berechtigte untergeordnete Ressourcen verwenden.

  1. Beginnen Sie mit der folgenden Anforderung:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/eligibleChildResources?api-version=2020-10-01&$filter={filter}

  2. Ersetzen Sie innerhalb des URIs {scope} durch den Bereich, für den die Rollen aufgelistet werden sollen.

    `Scope` type
    providers/Microsoft.Management/managementGroups/{mg-name} Verwaltungsgruppe
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group

  3. Ersetzen Sie {filter} durch die Bedingung, die zum Filtern der Liste mit den Rollenzuweisungen angewendet werden soll.

    Filtern BESCHREIBUNG
    $filter=resourceType+eq+'Subscription' Auflisten von Ressourcen vom Typ = "Abonnement".
    $filter=$filter=resourceType+eq+'subscription'+or+resourceType+eq+'resourcegroup'' Auflisten von Ressourcen vom Typ = "Abonnement" oder Typ = "ResourceGroup".

  4. Verwenden Sie die id einer beliebigen untergeordneten Ressource, um als die scope für die Aktivierung zu verwenden. RoleAssignmentScheduleRequest

Häufige Fehler, die für eine neue Anforderung zurückgegeben werden

Im Folgenden finden Sie eine Liste der häufig auftretenden Fehler, die beim Erstellen einer neuen Anforderung auftreten können, und wie Sie diese beheben können.

Fehlermeldung Explanantion Minderung
code: RoleAssignmentExists
message: Die Rollenzuweisung ist bereits vorhanden.		 Eine ähnliche Rollenzuweisung ist bereits vorhanden. Sie können GET diese Rollenzuweisung und den Zeitplan überprüfen.
code: RoleAssignmentRequestPolicyValidationFailed
message: Fehler bei den folgenden Richtlinienregeln: ["ExpirationRule"]		 Die ScheduleInfo in der Anforderung angegebene überschreitet die maximal zulässige Dauer. Sie können GET die RoleManagementPolicy dazu RoleDefinitionId verwenden und die RoleManagementPolicyExpirationRule
code: RoleAssignmentRequestPolicyValidationFailed
message: Fehler bei den folgenden Richtlinienregeln: ["JustificationRule"]		 Sie müssen einen Justification im Anforderungstext angeben. Sie können GET die RoleManagementPolicy dazu RoleDefinitionId verwenden und die RoleManagementPolicyEnablementRule
code: RoleAssignmentRequestPolicyValidationFailed
message: Fehler bei den folgenden Richtlinienregeln: ["EligibilityRule"]		 Zum Aktivieren dieser Rolle ist kein gültiger RoleEligibilityScheduleInstance Wert vorhanden. Ein Ressourcenadministrator muss einen RoleEligibilityScheduleRequest für diesen Prinzipal erstellen.
code: RoleAssignmentRequestPolicyValidationFailed
message: Fehler bei den folgenden Richtlinienregeln: ["TicketingRule"]		 Sie müssen einen TicketInfo im Anforderungstext angeben. Sie können GET die RoleManagementPolicy dazu RoleDefinitionId verwenden und die RoleManagementPolicyEnablementRule
code: RoleAssignmentRequestPolicyValidationFailed
message: Fehler bei den folgenden Richtlinienregeln: ["MfaRule"]		 Sie müssen Azure Multi-Factor Authentication abschließen, um diese Anforderung zu übermitteln. Sie können GET die RoleManagementPolicy dazu RoleDefinitionId verwenden und die RoleManagementPolicyEnablementRule