Erstellen oder Aktualisieren von benutzerdefinierten Rollen in Azure über die REST-API
Wenn die integrierten Azure-Rollen die Anforderungen Ihrer Organisation nicht erfüllen, können Sie Ihre eigenen benutzerdefinierten Rollen erstellen. In diesem Artikel wird beschrieben, wie Sie benutzerdefinierte Rollen mithilfe der REST-API auflisten, erstellen, aktualisieren oder löschen.
Voraussetzungen
Sie müssen die folgende Version verwenden:
2015-07-01
oder höher
Weitere Informationen finden Sie unter API-Versionen von Azure RBAC REST-APIs.
Auflisten aller benutzerdefinierten Rollendefinitionen
Um alle benutzerdefinierten Rollendefinitionen in einem Mandanten auflisten zu können, verwenden Sie die Rollendefinitionen – Rest-API für Listen .
Im folgenden Beispiel werden alle benutzerdefinierten Rollendefinitionen in einem Mandanten aufgelistet:
Anforderung
GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01
Antwort
{ "value": [ { "properties": { "roleName": "Billing Reader Plus", "type": "CustomRole", "description": "Read billing data and download invoices", "assignableScopes": [ "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15" ], "permissions": [ { "actions": [ "Microsoft.Authorization/*/read", "Microsoft.Billing/*/read", "Microsoft.Commerce/*/read", "Microsoft.Consumption/*/read", "Microsoft.Management/managementGroups/read", "Microsoft.CostManagement/*/read", "Microsoft.Billing/invoices/download/action", "Microsoft.CostManagement/exports/*" ], "notActions": [ "Microsoft.CostManagement/exports/delete" ], "dataActions": [], "notDataActions": [] } ], "createdOn": "2021-05-22T21:57:23.5764138Z", "updatedOn": "2021-05-22T21:57:23.5764138Z", "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70", "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70" }, "id": "/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c", "type": "Microsoft.Authorization/roleDefinitions", "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c" } ] }
Auflisten aller benutzerdefinierten Rollendefinitionen in einem Bereich
Um benutzerdefinierte Rollendefinitionen in einem Bereich auflisten zu können, verwenden Sie die Rollendefinitionen – Listen-REST-API .
Beginnen Sie mit der folgenden Anforderung:
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
Ersetzen Sie innerhalb des URIs {scope} mit dem Bereich, für den Sie die Rollen auflisten möchten.
`Scope` type subscriptions/{subscriptionId1}
Subscription subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}
Resource group subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}
Resource providers/Microsoft.Management/managementGroups/{groupId1}
Verwaltungsgruppe Ersetzen Sie {Filter} mit dem Rollentyp.
Filtern BESCHREIBUNG $filter=type+eq+'CustomRole'
Auf dem CustomRole-Typ basierender Filter Im folgenden Beispiel werden alle benutzerdefinierten Rollendefinitionen in einem Abonnement aufgelistet:
Anforderung
GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01
Antwort
{ "value": [ { "properties": { "roleName": "Billing Reader Plus", "type": "CustomRole", "description": "Read billing data and download invoices", "assignableScopes": [ "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15" ], "permissions": [ { "actions": [ "Microsoft.Authorization/*/read", "Microsoft.Billing/*/read", "Microsoft.Commerce/*/read", "Microsoft.Consumption/*/read", "Microsoft.Management/managementGroups/read", "Microsoft.CostManagement/*/read", "Microsoft.Billing/invoices/download/action", "Microsoft.CostManagement/exports/*" ], "notActions": [ "Microsoft.CostManagement/exports/delete" ], "dataActions": [], "notDataActions": [] } ], "createdOn": "2021-05-22T21:57:23.5764138Z", "updatedOn": "2021-05-22T21:57:23.5764138Z", "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70", "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70" }, "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c", "type": "Microsoft.Authorization/roleDefinitions", "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c" } ] }
Auflisten einer Definition einer benutzerdefinierten Rolle nach Namen
Um Informationen zu einer benutzerdefinierten Rollendefinition anhand des Anzeigenamens abzurufen, verwenden Sie die Rollendefinitionen – REST-API abrufen .
Beginnen Sie mit der folgenden Anforderung:
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
Ersetzen Sie innerhalb des URIs {scope} mit dem Bereich, für den Sie die Rollen auflisten möchten.
`Scope` type subscriptions/{subscriptionId1}
Subscription subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}
Resource group subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}
Resource providers/Microsoft.Management/managementGroups/{groupId1}
Verwaltungsgruppe Ersetzen Sie {Filter} mit dem Anzeigenamen für die Rolle.
Filtern BESCHREIBUNG $filter=roleName+eq+'{roleDisplayName}'
Verwenden Sie die URL-codierte Form des genauen Anzeigenamens der Rolle. Beispiel: $filter=roleName+eq+'Virtual%20Machine%20Contributor'
.Im folgenden Beispiel wird eine benutzerdefinierte Rollendefinition namens Billing Reader Plus in einem Abonnement aufgeführt:
Anforderung
GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=roleName+eq+'Billing Reader Plus'&api-version=2022-04-01
Antwort
{ "value": [ { "properties": { "roleName": "Billing Reader Plus", "type": "CustomRole", "description": "Read billing data and download invoices", "assignableScopes": [ "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15" ], "permissions": [ { "actions": [ "Microsoft.Authorization/*/read", "Microsoft.Billing/*/read", "Microsoft.Commerce/*/read", "Microsoft.Consumption/*/read", "Microsoft.Management/managementGroups/read", "Microsoft.CostManagement/*/read", "Microsoft.Billing/invoices/download/action", "Microsoft.CostManagement/exports/*" ], "notActions": [ "Microsoft.CostManagement/exports/delete" ], "dataActions": [], "notDataActions": [] } ], "createdOn": "2021-05-22T21:57:23.5764138Z", "updatedOn": "2021-05-22T21:57:23.5764138Z", "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70", "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70" }, "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c", "type": "Microsoft.Authorization/roleDefinitions", "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c" } ] }
Auflisten einer Definition einer benutzerdefinierten Rolle nach ID
Um Informationen zu einer benutzerdefinierten Rollendefinition anhand des eindeutigen Bezeichners abzurufen, verwenden Sie die Rollendefinitionen – REST-API abrufen .
Verwenden Sie die Rollendefinitionen – Liste-REST-API zum Abrufen des GUID-Bezeichners für die Rolle.
Beginnen Sie mit der folgenden Anforderung:
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01
Ersetzen Sie innerhalb des URIs {scope} mit dem Bereich, für den Sie die Rollen auflisten möchten.
`Scope` type subscriptions/{subscriptionId1}
Subscription subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}
Resource group subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}
Resource providers/Microsoft.Management/managementGroups/{groupId1}
Verwaltungsgruppe Ersetzen Sie {roledefinitionid} durch den GUID-Bezeichner der Rollendefinition.
Im folgenden Beispiel wird eine benutzerdefinierte Rollendefinition mit dem Bezeichner 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c in einem Abonnement aufgeführt:
Anforderung
GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c?api-version=2022-04-01
Antwort
{ "properties": { "roleName": "Billing Reader Plus", "type": "CustomRole", "description": "Read billing data and download invoices", "assignableScopes": [ "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15" ], "permissions": [ { "actions": [ "Microsoft.Authorization/*/read", "Microsoft.Billing/*/read", "Microsoft.Commerce/*/read", "Microsoft.Consumption/*/read", "Microsoft.Management/managementGroups/read", "Microsoft.CostManagement/*/read", "Microsoft.Billing/invoices/download/action", "Microsoft.CostManagement/exports/*" ], "notActions": [ "Microsoft.CostManagement/exports/delete" ], "dataActions": [], "notDataActions": [] } ], "createdOn": "2021-05-22T21:57:23.5764138Z", "updatedOn": "2021-05-22T21:57:23.5764138Z", "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70", "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70" }, "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c", "type": "Microsoft.Authorization/roleDefinitions", "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c" }
Erstellen einer benutzerdefinierten Rolle
Um eine benutzerdefinierte Rolle zu erstellen, verwenden Sie die Rollendefinitionen – Erstellen oder Aktualisieren-REST-API. Um diese API aufzurufen, müssen Sie als Benutzer angemeldet sein, dem eine Rolle zugewiesen ist, die über die Microsoft.Authorization/roleDefinitions/write
-Berechtigung für alle assignableScopes
verfügt. Unter den integrierten Rollen verfügen nur Besitzer und Benutzerzugriffsadministrator über diese Berechtigung.
Überprüfen Sie die Liste der Ressourcenanbietervorgänge, die zum Erstellen von Berechtigungen für die benutzerdefinierte Rolle verfügbar sind.
Verwenden Sie ein GUID-Tool, um einen eindeutigen Bezeichner zu generieren, der für den benutzerdefinierten Rollenbezeichner 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/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01
{ "name": "{roleDefinitionId}", "properties": { "roleName": "", "description": "", "type": "CustomRole", "permissions": [ { "actions": [ ], "notActions": [ ] } ], "assignableScopes": [ "/subscriptions/{subscriptionId1}", "/subscriptions/{subscriptionId2}", "/subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}", "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroup2}", "/providers/Microsoft.Management/managementGroups/{groupId1}" ] } }
Ersetzen Sie im URI {scope} durch die ersten
assignableScopes
der benutzerdefinierten Rolle.`Scope` type subscriptions/{subscriptionId1}
Subscription subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}
Resource group providers/Microsoft.Management/managementGroups/{groupId1}
Verwaltungsgruppe Ersetzen Sie {roleDefinitionId} durch den GUID-Bezeichner der benutzerdefinierten Rolle.
Ersetzen Sie im Anforderungstext {roleDefinitionId} mit dem GUID-Bezeichner.
Wenn
assignableScopes
ein Abonnement oder eine Ressourcengruppe ist, ersetzen Sie die {subscriptionId} - oder {resourceGroup} -Instanz durch Ihre Bezeichner.Wenn
assignableScopes
eine Verwaltungsgruppe ist, ersetzen Sie die {GroupID} Instanz durch ihren Verwaltungsgruppenbezeichner.Fügen Sie in der
actions
-Eigenschaft die Aktionen hinzu, deren Ausführung die Rolle zulässt.Fügen Sie in der
notActions
-Eigenschaft die Aktionen hinzu, die von den zulässigenactions
ausgeschlossen sind.Geben Sie in den Eigenschaften
roleName
unddescription
einen eindeutigen Rollennamen und eine Beschreibung an. Weitere Informationen zu den Eigenschaften finden Sie unter Benutzerdefinierte Rollen in Azure.Es folgt ein Beispiel für einen Anforderungstext:
{ "name": "88888888-8888-8888-8888-888888888888", "properties": { "roleName": "Virtual Machine Operator", "description": "Can monitor and restart virtual machines.", "type": "CustomRole", "permissions": [ { "actions": [ "Microsoft.Storage/*/read", "Microsoft.Network/*/read", "Microsoft.Compute/*/read", "Microsoft.Compute/virtualMachines/start/action", "Microsoft.Compute/virtualMachines/restart/action", "Microsoft.Authorization/*/read", "Microsoft.ResourceHealth/availabilityStatuses/read", "Microsoft.Resources/subscriptions/resourceGroups/read", "Microsoft.Insights/alertRules/*", "Microsoft.Support/*" ], "notActions": [] } ], "assignableScopes": [ "/subscriptions/00000000-0000-0000-0000-000000000000", "/providers/Microsoft.Management/managementGroups/marketing-group" ] } }
Aktualisieren einer benutzerdefinierten Rolle
Um eine benutzerdefinierte Rolle zu aktualisieren, verwenden Sie die Rollendefinitionen – Erstellen oder Aktualisieren-REST-API. Um diese API aufzurufen, müssen Sie mit einem Benutzer angemeldet sein, dem eine Rolle zugewiesen ist, die über die Microsoft.Authorization/roleDefinitions/write
Berechtigung für alle Benutzer assignableScopes
verfügt, z . B. Benutzerzugriffsadministrator.
Verwenden Sie die Rollendefinitionen – Liste- oder Rollendefinitionen – Abrufen-REST-API zum Abrufen von Informationen zu der benutzerdefinierten Rolle. Weitere Informationen finden Sie im abschnitt " Alle benutzerdefinierten Rollendefinitionen auflisten".
Beginnen Sie mit der folgenden Anforderung:
PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01
Ersetzen Sie im URI {scope} durch die ersten
assignableScopes
der benutzerdefinierten Rolle.`Scope` type subscriptions/{subscriptionId1}
Subscription subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}
Resource group providers/Microsoft.Management/managementGroups/{groupId1}
Verwaltungsgruppe Ersetzen Sie {roleDefinitionId} durch den GUID-Bezeichner der benutzerdefinierten Rolle.
Erstellen Sie basierend auf den Informationen über die benutzerdefinierte Rolle einen Anforderungstext mit folgendem Format:
{ "name": "{roleDefinitionId}", "properties": { "roleName": "", "description": "", "type": "CustomRole", "permissions": [ { "actions": [ ], "notActions": [ ] } ], "assignableScopes": [ "/subscriptions/{subscriptionId1}", "/subscriptions/{subscriptionId2}", "/subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}", "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroup2}", "/providers/Microsoft.Management/managementGroups/{groupId1}" ] } }
Aktualisieren Sie den Anforderungstext mit den Änderungen, die Sie an der benutzerdefinierten Rolle vornehmen möchten.
Im Folgenden sehen Sie ein Beispiel für einen Anforderungstext mit einer neu hinzugefügten Diagnoseeinstellungenaktion:
{ "name": "88888888-8888-8888-8888-888888888888", "properties": { "roleName": "Virtual Machine Operator", "description": "Can monitor and restart virtual machines.", "type": "CustomRole", "permissions": [ { "actions": [ "Microsoft.Storage/*/read", "Microsoft.Network/*/read", "Microsoft.Compute/*/read", "Microsoft.Compute/virtualMachines/start/action", "Microsoft.Compute/virtualMachines/restart/action", "Microsoft.Authorization/*/read", "Microsoft.ResourceHealth/availabilityStatuses/read", "Microsoft.Resources/subscriptions/resourceGroups/read", "Microsoft.Insights/alertRules/*", "Microsoft.Insights/diagnosticSettings/*", "Microsoft.Support/*" ], "notActions": [] } ], "assignableScopes": [ "/subscriptions/00000000-0000-0000-0000-000000000000", "/providers/Microsoft.Management/managementGroups/marketing-group" ] } }
Löschen einer benutzerdefinierten Rolle
Verwenden Sie zum Löschen einer benutzerdefinierten Rolle die Rollendefinitionen – Löschen-REST-API. Um diese API aufzurufen, müssen Sie als Benutzer angemeldet sein, dem eine Rolle zugewiesen ist, die über die Microsoft.Authorization/roleDefinitions/delete
-Berechtigung für alle assignableScopes
verfügt. Unter den integrierten Rollen verfügen nur Besitzer und Benutzerzugriffsadministrator über diese Berechtigung.
Entfernen Sie alle Rollenzuweisungen, welche die benutzerdefinierte Rolle verwenden. Weitere Informationen finden Sie unter Suchen nach Rollenzuweisungen zum Löschen einer benutzerdefinierten Rolle.
Verwenden Sie die Rollendefinitionen – Liste- oder Rollendefinitionen – Abrufen-REST-API zum Abrufen des GUID-Bezeichners der benutzerdefinierten Rolle. Weitere Informationen finden Sie im abschnitt " Alle benutzerdefinierten Rollendefinitionen auflisten".
Beginnen Sie mit der folgenden Anforderung:
DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01
Ersetzen Sie innerhalb des URIs {scope} mit dem Bereich, in dem Sie die benutzerdefinierte Rolle löschen möchten.
`Scope` type subscriptions/{subscriptionId1}
Subscription subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}
Resource group providers/Microsoft.Management/managementGroups/{groupId1}
Verwaltungsgruppe Ersetzen Sie {roleDefinitionId} durch den GUID-Bezeichner der benutzerdefinierten Rolle.