Creación o actualización de roles personalizados para los recursos de Azure con la API REST

Artículo
12/01/2023

Si los roles integrados de Azure no cumplen las necesidades específicas de su organización, puede crear los suyos propios. En este artículo se describe cómo mostrar, crear, actualizar o eliminar roles personalizados con la API REST.

Requisitos previos

Debe usar la versión siguiente:

2015-07-01 o posterior

Para obtener más información, consulte Versiones de la API REST de RBAC de Azure.

Enumerar todas las definiciones de roles personalizados

Para enumerar todas las definiciones de roles personalizadas de un inquilino, use la API REST Definiciones de roles: lista .

En el ejemplo siguiente se enumeran todas las definiciones de roles personalizadas de un inquilino:

Solicitar

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

Respuesta

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

Enumeración de todas las definiciones de roles personalizadas en un ámbito

Para enumerar las definiciones de roles personalizadas en un ámbito, use la API REST Role Definitions - List .

Empiece con la solicitud siguiente:

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

En el identificador URI, reemplace {scope} por el ámbito cuya lista de roles quiere obtener.

Ámbito	Tipo
`subscriptions/{subscriptionId1}`	Suscripción
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Resource
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de administración

Reemplace {filter} por el tipo de rol.

Filter	Descripción
`$filter=type+eq+'CustomRole'`	Filtro basado en el tipo CustomRole

En el ejemplo siguiente se enumeran todas las definiciones de roles personalizadas de una suscripción:

Solicitar

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

Respuesta

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

Enumeración de una definición de rol personalizado por nombre

Para obtener información sobre una definición de rol personalizada por su nombre para mostrar, use la API REST Definiciones de roles - Obtener .

Empiece con la solicitud siguiente:

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

En el identificador URI, reemplace {scope} por el ámbito cuya lista de roles quiere obtener.

Ámbito	Tipo
`subscriptions/{subscriptionId1}`	Suscripción
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Resource
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de administración

Reemplace {filter} con el nombre para mostrar para el rol.

Filter	Descripción
`$filter=roleName+eq+'{roleDisplayName}'`	Use la forma con codificación URL del nombre para mostrar exacto del rol. Por ejemplo: `$filter=roleName+eq+'Virtual%20Machine%20Contributor'`

En el ejemplo siguiente se muestra una definición de rol personalizada denominada Billing Reader Plus en una suscripción:

Solicitar

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

Respuesta

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

Enumeración de una definición de rol personalizado por identificador

Para obtener información sobre una definición de rol personalizada por su identificador único, use la API REST Definiciones de roles - Obtener .

Use la API de REST Role Definitions - List para obtener el identificador GUID para el rol.

Empiece con la solicitud siguiente:

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

En el identificador URI, reemplace {scope} por el ámbito cuya lista de roles quiere obtener.

Ámbito	Tipo
`subscriptions/{subscriptionId1}`	Suscripción
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Resource
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de administración

Reemplace {roleDefinitionId} por el identificador GUID de la definición de roles.

En el ejemplo siguiente se muestra una definición de rol personalizada con el identificador 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c en una suscripción:

Solicitar

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

Respuesta

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

Crear un rol personalizado

Para crear un rol personalizado, use la API de REST Role Definitions - Create Or Update. Para llamar a esta API, debe haber iniciado sesión con un usuario que tenga asignado un rol que, a su vez, tenga el permiso Microsoft.Authorization/roleDefinitions/write en todos los assignableScopes. Entre los roles integrados, solamente Propietario y Administrador de acceso de usuario incluyen este permiso.

Revise la lista de operaciones de proveedores de recursos que están disponibles para crear los permisos para su rol personalizado.
Use una herramienta de GUID para generar un identificador único que se use para el identificador del rol personalizado. El identificador tiene el formato: 00000000-0000-0000-0000-000000000000

Empiece con la solicitud y el cuerpo siguientes:

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

Dentro del URI, reemplace {scope} por el primer elemento assignableScopes del rol personalizado.

Ámbito	Tipo
`subscriptions/{subscriptionId1}`	Suscripción
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupos de recursos
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de administración

Reemplace {roleDefinitionId} por el identificador GUID del rol personalizado.
En el cuerpo de la solicitud, reemplace {roleDefinitionId} por el identificador GUID.
Si assignableScopes es una suscripción o un grupo de recursos, reemplace las instancias {subscriptionId} o {resourceGroup} por sus identificadores.
Si assignableScopes es un grupo de administración, reemplace la instancia {groupId} por el identificador del grupo de administración.
En la propiedad actions, agregue las acciones que permite realizar el rol.
En la propiedad notActions, agregue las acciones excluidas de las actions permitidas.

En las propiedades roleName y description, especifique un nombre de rol exclusivo y una descripción. Para más información sobre las propiedades, consulte Roles personalizados de Azure.

A continuación se muestra un ejemplo de cuerpo de la solicitud:

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

Actualización de un rol personalizado

Para actualizar un rol personalizado, use la API de REST Role Definitions - Create Or Update. Para llamar a esta API, debe iniciar sesión con un usuario que tenga asignado un rol que tenga el Microsoft.Authorization/roleDefinitions/write permiso en todos los assignableScopes, como El acceso de usuario Administración istrator.

Para obtener información sobre el rol personalizado, use las API de REST Role Definitions - List o Role Definitions - Get. Para obtener más información, consulte la sección Enumerar todas las definiciones de roles personalizadas anteriormente.

Empiece con la solicitud siguiente:

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

Dentro del URI, reemplace {scope} por el primer elemento assignableScopes del rol personalizado.

Ámbito	Tipo
`subscriptions/{subscriptionId1}`	Suscripción
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupos de recursos
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de administración

Reemplace {roleDefinitionId} por el identificador GUID del rol personalizado.

Según la información sobre el rol personalizado, cree un cuerpo de la solicitud con el formato siguiente:

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

Actualice el cuerpo de la solicitud con los cambios que desee hacer en el rol personalizado.

A continuación se muestra un ejemplo de cuerpo de la solicitud con la nueva acción de configuración de diagnóstico agregada:

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

Eliminación de un rol personalizado

Para eliminar un rol personalizado, use la API de REST Role Definitions - Delete. Para llamar a esta API, debe haber iniciado sesión con un usuario que tenga asignado un rol que, a su vez, tenga el permiso Microsoft.Authorization/roleDefinitions/delete en todos los assignableScopes. Entre los roles integrados, solamente Propietario y Administrador de acceso de usuario incluyen este permiso.

Quite todas las asignaciones de roles que utilicen el rol personalizado. Para obtener más información, consulte Búsqueda de asignaciones de roles para eliminar un rol personalizado.
Para obtener el identificador GUID del rol personalizado, use las API de REST Role Definitions - List o Role Definitions - Get. Para obtener más información, consulte la sección Enumerar todas las definiciones de roles personalizadas anteriormente.

Empiece con la solicitud siguiente:

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

En el identificador URI, reemplace {scope} por el ámbito que desea eliminar para el rol personalizado.

Ámbito	Tipo
`subscriptions/{subscriptionId1}`	Suscripción
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupos de recursos
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de administración

Reemplace {roleDefinitionId} por el identificador GUID del rol personalizado.

Pasos siguientes

Roles personalizados en los recursos de Azure
Asignación de roles de Azure mediante la API REST
Azure REST API Reference (Referencia de API de REST en Azure)

Creación o actualización de roles personalizados para los recursos de Azure con la API REST

Requisitos previos

Enumerar todas las definiciones de roles personalizados

Enumeración de todas las definiciones de roles personalizadas en un ámbito

Enumeración de una definición de rol personalizado por nombre

Enumeración de una definición de rol personalizado por identificador

Crear un rol personalizado

Actualización de un rol personalizado

Eliminación de un rol personalizado

Pasos siguientes

Recursos adicionales