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

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.

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.