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.
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.
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}
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 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.
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.
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
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 } } } }
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 Ersetzen Sie {roleAssignmentScheduleRequestName} durch den GUID-Bezeichner der Rollenzuweisung.
Ersetzen Sie innerhalb des Anforderungstexts {subscriptionId} durch Ihre Abonnement-ID.
Ersetzen Sie {roleDefinitionId} durch den Bezeichner der Rollendefinition.
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.
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
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" } }
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 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.
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
[Optional] Wählen Sie einen
RoleEligibilitySchedule
aus, den Sie aktivieren möchten, und rufen Sie dieRoleEligibilityScheduleId
von der API für Rollenberechtigungszeitpläne ab, um alsLinkedRoleEligibilityScheduleId
übergeben zu werden. Dies ist optional, und wenn nicht übergeben wird, wählt das System einenRoleEligibilitySchedule
aus.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 } }
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 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.
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
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" } }
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 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.
Beginnen Sie mit der folgenden Anforderung:
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/eligibleChildResources?api-version=2020-10-01&$filter={filter}
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 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". Verwenden Sie die
id
einer beliebigen untergeordneten Ressource, um als diescope
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 : RoleAssignmentExistsmessage : Die Rollenzuweisung ist bereits vorhanden. |
Eine ähnliche Rollenzuweisung ist bereits vorhanden. | Sie können GET diese Rollenzuweisung und den Zeitplan überprüfen. |
code : RoleAssignmentRequestPolicyValidationFailedmessage : 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 : RoleAssignmentRequestPolicyValidationFailedmessage : 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 : RoleAssignmentRequestPolicyValidationFailedmessage : 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 : RoleAssignmentRequestPolicyValidationFailedmessage : 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 : RoleAssignmentRequestPolicyValidationFailedmessage : 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 |