Uso de Azure PIM para administrar el acceso activo con la API REST

Artículo
07/19/2023

Azure Privileged Identity Management (PIM) le permite limitar el acceso de administrador permanente a roles con privilegios, detectar quién tiene acceso y revisar el acceso con privilegios. En este artículo se describen las formas comunes de administrar el acceso mediante la API REST.

Enumeración de asignaciones activas

Para enumerar las asignaciones de roles activas (acceso de lista), puede usar una de las instancias de programación de asignación de roles: lista para las programaciones de ámbito o asignación de roles: lista para las API REST de ámbito. Para mejorar los resultados, especifique un ámbito y un filtro opcional. Para llamar a la API, debe tener acceso a la operación Microsoft.Authorization/roleAssignments/read en el ámbito especificado. A todos los roles integrados se les concede acceso a esta operación.

Importante

La diferencia entre las programaciones y las instancias de programación es que, aunque las instancias de programación solo incluyen asignaciones que están activas en el momento actual, las programaciones también incluyen asignaciones que se activarán en el futuro.

Empiece con la solicitud siguiente:

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}

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

Ámbito	Tipo
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupo de administración
`subscriptions/{subscriptionId}`	Subscription
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Resource group
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1`	Resource

Reemplace {filter} por la condición que quiere aplicar para filtrar la lista de asignación de roles.

Filter	Descripción
`$filter=atScope()`	Lista de las asignaciones de roles únicamente para el ámbito especificado, sin incluir las asignaciones de roles en ámbitos secundarios.
`$filter=principalId%20eq%20'{objectId}'`	Lista de las asignaciones de roles para un usuario, un grupo o una entidad de servicio determinados.
`$filter=roleDefinitionId%20eq%20'{roleDefinitionId}'`	Enumera las asignaciones de roles para una definición de rol especificada.
`$filter=assignedTo('{objectId}')`	Lista de las asignaciones de roles para un usuario determinado, incluidas las que se heredaron de otros grupos.
`$filter=asTarget()`	Enumere las asignaciones de roles para el usuario o la entidad de servicio actual, incluidas las heredadas de los grupos.
`$filter=assignedTo('{objectId}')+and+atScope()`	Enumere las asignaciones de roles para un usuario especificado, incluidas las heredadas de grupos solo para el ámbito especificado, no incluidas las asignaciones de roles en subámbitas.

Conceder asignación activa

Para crear una asignación de roles activa (conceder acceso), use la API de programación de asignación de roles : cree la API REST y especifique la entidad de seguridad, la definición de roles, la programación, requestType = AdminAssign y el ámbito. Para llamar a esta API, debe tener acceso a la Microsoft.Authorization/roleAssignments/write operación. Entre los roles integrados, solo se concede acceso a esta operación a Propietario y Administrador de acceso de usuario.

Use la API de REST Definiciones de roles - Lista o consulte Roles integrados para obtener el identificador de la definición de roles que quiere asignar.
Use una herramienta de GUID para generar un identificador único que se use para el identificador de asignación de roles. 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/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
      }
    }
  }
}

En el identificador URI, reemplace {scope} por el ámbito de la asignación de roles.

Ámbito	Tipo
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupo de administración
`subscriptions/{subscriptionId}`	Subscription
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Resource group
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1`	Resource

Reemplace {roleAssignmentScheduleRequestName} por el identificador GUID de la asignación de roles.
En el cuerpo de la solicitud, reemplace {subscriptionId} por el identificador de la suscripción.
Reemplace {roleDefinitionId} por el identificador de la definición de roles.
Reemplace {principalId} por el identificador de objeto del usuario, grupo o entidad de servicio al que se asignará el rol.

Quitar asignación activa

Para quitar una asignación de roles activa (quitar el acceso), use la API de programación de asignación de roles : crear una API REST para crear una nueva solicitud para revocar la asignación y especificar la entidad de seguridad, la definición de roles, requestType = AdminRemove y el ámbito. Para llamar a esta API, debe tener acceso a la operación Microsoft.Authorization/roleAssignments/write. Entre los roles integrados, solo se concede acceso a esta operación a Propietario y Administrador de acceso de usuario.

Use una herramienta de GUID para generar un identificador único que se use para el identificador de asignación de roles. El identificador tiene el formato: 00000000-0000-0000-0000-000000000000

Empiece con la solicitud siguiente:

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

En el identificador URI, reemplace {scope} por el ámbito para eliminar la asignación de roles.

Ámbito	Tipo
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupo de administración
`subscriptions/{subscriptionId}`	Subscription
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Resource group
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1`	Resource

Reemplace {roleAssignmentScheduleRequestName} por el identificador GUID de la asignación de roles.

Activación de una asignación de roles apta

Para activar una asignación de roles apta (obtener acceso activado), use la API de programación de asignación de roles - Crear api REST para crear una nueva solicitud y especificar la entidad de seguridad, la definición de roles, requestType = SelfActivate y el ámbito. Para llamar a esta API, debe tener una asignación de roles apta en el ámbito.

Use una herramienta de GUID para generar un identificador único que se use para el identificador de asignación de roles. El identificador tiene el formato: 00000000-0000-0000-0000-000000000000
[Opcional] Elija un RoleEligibilitySchedule objeto que desee activar y obtener de RoleEligibilityScheduleId la API Programaciones de idoneidad de roles para pasar como LinkedRoleEligibilityScheduleId. Esto es opcional y, si no se pasa, el sistema elegirá .RoleEligibilitySchedule

Empiece con la solicitud siguiente:

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

En el identificador URI, reemplace {scope} por el ámbito para eliminar la asignación de roles.

Ámbito	Tipo
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupo de administración
`subscriptions/{subscriptionId}`	Subscription
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Resource group
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1`	Resource

Reemplace {roleAssignmentScheduleRequestName} por el identificador GUID de la asignación de roles.

Desactivar una asignación de roles activa

Para anular la activación de una asignación de roles activada (quitar el acceso activado), use la API de programación de asignación de roles - Crear api REST para crear una nueva solicitud y especificar la entidad de seguridad, la definición de roles, requestType = SelfDeactivate y el ámbito. Para llamar a esta API, debe tener una asignación de roles activada en el ámbito.

Use una herramienta de GUID para generar un identificador único que se use para el identificador de asignación de roles. El identificador tiene el formato: 00000000-0000-0000-0000-000000000000

Empiece con la solicitud siguiente:

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

En el identificador URI, reemplace {scope} por el ámbito para eliminar la asignación de roles.

Ámbito	Tipo
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupo de administración
`subscriptions/{subscriptionId}`	Subscription
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Resource group
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1`	Resource

Reemplace {roleAssignmentScheduleRequestName} por el identificador GUID de la asignación de roles.

Just-Enough-Access (JEA)

Si un usuario tiene una asignación de roles apta en un recurso (primario), puede optar por activar el rol en un ámbito de nivel secundario del recurso primario en lugar de todo el ámbito primario. Por ejemplo, si un usuario tiene Contributor un rol apto en una suscripción, puede activar el rol en un nivel de grupo de recursos secundario de la suscripción.

Para obtener una lista de todos los elementos secundarios de un recurso en el que tiene acceso apto, puede usar la API de recursos secundarios elegibles .

Empiece con la solicitud siguiente:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/eligibleChildResources?api-version=2020-10-01&$filter={filter}

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

Ámbito	Tipo
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupo de administración
`subscriptions/{subscriptionId}`	Subscription
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Resource group

Reemplace {filter} por la condición que quiere aplicar para filtrar la lista de asignación de roles.

Filter	Descripción
`$filter=resourceType+eq+'Subscription'`	Enumere los recursos de tipo = "Suscripción".
`$filter=$filter=resourceType+eq+'subscription'+or+resourceType+eq+'resourcegroup''`	Enumere los recursos de tipo = "Suscripción" o tipo = "ResourceGroup".

Use el id de cualquier recurso secundario que se usará como scope para la activación. RoleAssignmentScheduleRequest

Errores comunes devueltos para una nueva solicitud

A continuación se muestra una lista de errores comunes que puede encontrar al crear una nueva solicitud y cómo mitigarlos.

Mensaje de error	Explanación	Mitigación
`code`: RoleAssignmentExists `message`: la asignación de roles ya existe.	Ya existe una asignación de roles similar	Puede `GET` esta asignación de roles y comprobar su programación.
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: se produjo un error en las siguientes reglas de directiva: ["ExpirationRule"]	El `ScheduleInfo` especificado en la solicitud supera la duración máxima permitida.	Puede `GET` usar RoleManagementPolicy para esto `RoleDefinitionId` y comprobar el `RoleManagementPolicyExpirationRule`
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: se han producido errores en las siguientes reglas de directiva: ["JustificationRule"]	Debe especificar en el cuerpo de la solicitud.`Justification`	Puede `GET` usar RoleManagementPolicy para esto `RoleDefinitionId` y comprobar el `RoleManagementPolicyEnablementRule`
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: se produjo un error en las siguientes reglas de directiva: ["EligibilityRule"]	No existe un válido `RoleEligibilityScheduleInstance` para activar este rol.	Un administrador de recursos debe crear un `RoleEligibilityScheduleRequest` para esta entidad de seguridad.
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: se produjo un error en las siguientes reglas de directiva: ["TicketingRule"]	Debe especificar en el cuerpo de la solicitud.`TicketInfo`	Puede `GET` usar RoleManagementPolicy para esto `RoleDefinitionId` y comprobar el `RoleManagementPolicyEnablementRule`
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: se produjo un error en las siguientes reglas de directiva: ["MfaRule"]	Debe completar Azure Multi-Factor Authentication para enviar esta solicitud.	Puede `GET` usar RoleManagementPolicy para esto `RoleDefinitionId` y comprobar el `RoleManagementPolicyEnablementRule`

Compartir a través de

Uso de Azure PIM para administrar el acceso activo con la API REST

Enumeración de asignaciones activas

Conceder asignación activa

Quitar asignación activa

Activación de una asignación de roles apta

Desactivar una asignación de roles activa

Just-Enough-Access (JEA)

Errores comunes devueltos para una nueva solicitud

Recursos adicionales