Создание или обновление настраиваемых ролей Azure с использованием REST API

  • Статья

Если встроенные роли Azure не соответствуют потребностям вашей организации, вы можете создать собственные настраиваемые роли. В данной статье описывается, как составлять список, создавать, обновлять или удалять пользовательские роли при помощи REST API.

Необходимые компоненты

Необходимо использовать следующую версию:

  • 2015-07-01 или более поздней версии.

Дополнительные сведения см. в версиях API REST API Azure RBAC.

Перечисление всех определений настраиваемых ролей

Чтобы перечислить все определения настраиваемых ролей в клиенте, используйте определения ролей — список REST API.

  • В следующем примере перечислены все определения пользовательских ролей в клиенте:

    Запросить

    GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01

    Ответ

    {
    "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"
        }
    ]
}

Вывод списка всех определений пользовательских ролей на область

Чтобы перечислить пользовательские определения ролей в область, используйте определения ролей — список REST API.

  1. Можете начать со следующего запроса:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01

  2. В URI замените {scope} на область, для которой нужно получить список ролей.

    Область Тип
    subscriptions/{subscriptionId1} Подписка
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Группа ресурсов
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} Ресурс
    providers/Microsoft.Management/managementGroups/{groupId1} Группа управления

  3. Замените {filter} типом роли.

    Фильтр Description
    $filter=type+eq+'CustomRole' Фильтр по типу CustomRole

    В следующем примере перечислены все определения пользовательских ролей в подписке:

    Запросить

    GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01

    Ответ

    {
    "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"
        }
    ]
}

Перечислите определение настраиваемой роли по имени

Чтобы получить сведения об определении пользовательской роли по отображаемой имени, используйте определения ролей — получение REST API.

  1. Можете начать со следующего запроса:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01

  2. В URI замените {scope} на область, для которой нужно получить список ролей.

    Область Тип
    subscriptions/{subscriptionId1} Подписка
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Группа ресурсов
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} Ресурс
    providers/Microsoft.Management/managementGroups/{groupId1} Группа управления

  3. Замените {filter} отображаемым именем роли.

    Фильтр Description
    $filter=roleName+eq+'{roleDisplayName}' Используйте точное отображаемое имя роли в формате URL-адреса. Например, $filter=roleName+eq+'Virtual%20Machine%20Contributor'

    В следующем примере перечислены пользовательские определения ролей с именем Billing Reader Plus в подписке:

    Запросить

    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

    Ответ

    {
    "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"
        }
    ]
}

Перечислить определение настраиваемой роли по идентификатору

Чтобы получить сведения об определении пользовательской роли по уникальному идентификатору, используйте определения ролей — получение REST API.

  1. Для получения идентификатора GUID роли используйте REST API Определения ролей — список.

  2. Можете начать со следующего запроса:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

  3. В URI замените {scope} на область, для которой нужно получить список ролей.

    Область Тип
    subscriptions/{subscriptionId1} Подписка
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Группа ресурсов
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} Ресурс
    providers/Microsoft.Management/managementGroups/{groupId1} Группа управления

  4. Замените {roleDefinitionId} на идентификатор GUID определения роли.

    В следующем примере приводится определение пользовательской роли с идентификатором 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c в подписке:

    Запросить

    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

    Ответ

    {
    "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"
}

Создание пользовательской роли

Чтобы создать пользовательскую роль, используйте REST API Определения ролей — создание или обновление. Чтобы вызвать этот API, вы должны войти в систему с пользователем, которому назначена роль, имеющая разрешение Microsoft.Authorization/roleDefinitions/write на все assignableScopes. Из встроенных ролей только Владелец и Администратор доступа пользователей включают данное разрешение.

  1. Просмотрите список доступных операций поставщиков ресурсов для создания разрешений для пользовательской роли.

  2. Используйте средство GUID для создания уникального идентификатора, который будет использоваться в качестве идентификатора пользовательской роли. Этот идентификатор имеет следующий формат: 00000000-0000-0000-0000-000000000000

  3. Можете начать со следующего запроса и основного текста:

    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}"
    ]
  }
}

  4. В URI замените {scope} на первую область assignableScopes пользовательской роли.

    Область Тип
    subscriptions/{subscriptionId1} Подписка
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Группа ресурсов
    providers/Microsoft.Management/managementGroups/{groupId1} Группа управления

  5. Замените {role-definition-id} на идентификатор GUID пользовательской роли.

  6. В теле запроса замените {roleDefinitionId} идентификатором GUID.

  7. Если assignableScopes является подпиской или группой ресурсов, замените экземпляры {subscriptionId} или {resourceGroup} своими идентификаторами.

  8. Если assignableScopes является группой управления, замените экземпляр {groupId} идентификатором своей группы управления.

  9. В свойстве actions добавьте действия, которые позволяет выполнять роль.

  10. В свойстве notActions добавьте действия, исключенные из разрешенного actions.

  11. В свойствах roleName и description укажите уникальное имя и описание роли. Дополнительные сведения о свойствах см. в разделе Пользовательские роли Azure.

    Ниже приведен пример текста запроса:

    {
  "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"
    ]
  }
}

Обновление пользовательской роли

Чтобы обновить пользовательскую роль, используйте REST API Определения ролей — создание или обновление. Чтобы вызвать этот API, необходимо войти в систему с помощью пользователя, которому назначена роль, которая имеет Microsoft.Authorization/roleDefinitions/write разрешение на все assignableScopesдействия, например Администратор istrator для доступа пользователей.

  1. Чтобы получить сведения о пользовательской роли, используйте REST API Определения ролей — список или Определения ролей — получение. Дополнительные сведения см. в предыдущем разделе "Список всех определений пользовательских ролей".

  2. Можете начать со следующего запроса:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

  3. В URI замените {scope} на первую область assignableScopes пользовательской роли.

    Область Тип
    subscriptions/{subscriptionId1} Подписка
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Группа ресурсов
    providers/Microsoft.Management/managementGroups/{groupId1} Группа управления

  4. Замените {role-definition-id} на идентификатор GUID пользовательской роли.

  5. На основе сведений о пользовательской роли создайте текст запроса в следующем формате:

    {
  "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}"
    ]
  }
}

  6. Внесите необходимые изменения для пользовательской роли в текст запроса.

    Ниже приведен пример текста запроса с добавленным действием "Параметры диагностики":

    {
  "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"
    ]
  }
}

Удаление настраиваемой роли

Чтобы удалить пользовательскую роль, используйте REST API Определения ролей — удаление. Чтобы вызвать этот API, вы должны войти в систему с пользователем, которому назначена роль, имеющая разрешение Microsoft.Authorization/roleDefinitions/delete на все assignableScopes. Из встроенных ролей только Владелец и Администратор доступа пользователей включают данное разрешение.

  1. Удалите все назначения ролей, использующие пользовательскую роль. Дополнительные сведения см. в разделе "Поиск назначений ролей" для удаления настраиваемой роли.

  2. Чтобы получить идентификатор GUID пользовательской роли, используйте REST API Определения ролей — список или Определения ролей — получение. Дополнительные сведения см. в предыдущем разделе "Список всех определений пользовательских ролей".

  3. Можете начать со следующего запроса:

    DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

  4. В URI замените {scope} на область, для которой нужно удалить пользовательскую роль.

    Область Тип
    subscriptions/{subscriptionId1} Подписка
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Группа ресурсов
    providers/Microsoft.Management/managementGroups/{groupId1} Группа управления

  5. Замените {role-definition-id} на идентификатор GUID пользовательской роли.

Следующие шаги