Erstellen oder Aktualisieren von benutzerdefinierten Rollen in Azure über die REST-API

Artikel
12/01/2023

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ässigen actions ausgeschlossen sind.

Geben Sie in den Eigenschaften roleName und description 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 assignableScopesverfü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.

Erstellen oder Aktualisieren von benutzerdefinierten Rollen in Azure über die REST-API

Voraussetzungen

Auflisten aller benutzerdefinierten Rollendefinitionen

Auflisten aller benutzerdefinierten Rollendefinitionen in einem Bereich

Auflisten einer Definition einer benutzerdefinierten Rolle nach Namen

Auflisten einer Definition einer benutzerdefinierten Rolle nach ID

Erstellen einer benutzerdefinierten Rolle

Aktualisieren einer benutzerdefinierten Rolle

Löschen einer benutzerdefinierten Rolle

Nächste Schritte

Zusätzliche Ressourcen