Crear governanceRoleAssignmentRequest

  • Artículo

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Precaución

Esta versión de la API de Privileged Identity Management (PIM) para recursos de Azure dejará de usarse pronto. Use la nueva API de PIM de REST de Azure para roles de recursos de Azure.

Cree una solicitud de asignación de roles para representar la operación que desee en una asignación de roles. En la tabla siguiente se enumeran las operaciones.

Operación Tipo
Asignación de una asignación de roles AdminAdd
Activación de una asignación de roles apta Useradd
Desactivación de una asignación de roles activada UserRemove
Eliminación de una asignación de roles AdminRemove
Actualización de una asignación de roles AdminUpdate
Solicitud para ampliar mi asignación de roles UserExtend
Extensión de una asignación de roles AdminExtend
Solicitud para renovar mi asignación de roles expirada UserRenew
Renovación de una asignación de roles expirada AdminRenew

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ❌

Permissions

En la tabla siguiente se muestran los permisos o permisos con privilegios mínimos necesarios para llamar a esta API en cada tipo de recurso admitido. Siga los procedimientos recomendados para solicitar permisos con privilegios mínimos. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Recurso admitido Delegado (cuenta profesional o educativa) Delegado (cuenta de Microsoft personal) Aplicación
Microsoft Entra ID PrivilegedAccess.ReadWrite.AzureAD No admitida. No admitida.
Recursos de Azure PrivilegedAccess.ReadWrite.AzureResources No admitida. No admitida.
group PrivilegedAccess.ReadWrite.AzureADGroup No admitida. No admitida.

Solicitud HTTP

POST /privilegedAccess/azureResources/roleAssignmentRequests

Encabezados de solicitud

Nombre Descripción
Autorización Portador {code}
Tipo de contenido application/json

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione una representación JSON de un objeto governanceRoleAssignmentRequest .

Propiedad Tipo Descripción
resourceId Cadena Identificador único del recurso de Azure asociado a la solicitud de asignación de roles. Los recursos de Azure pueden incluir suscripciones, grupos de recursos, máquinas virtuales y bases de datos SQL. Obligatorio.
roleDefinitionId Cadena Identificador de la definición de roles de Azure a la que está asociada la solicitud de asignación de roles. Obligatorio.
subjectId Cadena Identificador único de la entidad de seguridad o asunto al que está asociada la solicitud de asignación de roles. Las entidades de seguridad pueden ser usuarios, grupos o entidades de servicio. Obligatorio.
assignmentState Cadena Estado de la asignación. El valor puede ser Eligible y Active. Obligatorio.
type Cadena Tipo de solicitud. El valor puede ser AdminAdd, UserAdd, AdminUpdate, AdminRemove, UserRemove, UserExtend, UserRenewAdminRenewy AdminExtend. Obligatorio.
motivo Cadena El motivo debe proporcionarse para la solicitud de asignación de roles con fines de auditoría y revisión.
schedule governanceSchedule Programación de la solicitud de asignación de roles. Para el tipo de solicitud , UserAddAdminAdd, AdminUpdatey AdminExtend, es necesario.

Respuesta

Si se ejecuta correctamente, este método devuelve un 201 Created código de respuesta y un objeto governanceRoleAssignmentRequest en el cuerpo de la respuesta.

Códigos de error

Esta API devuelve los códigos de error HTTP estándar. Además, también devuelve los códigos de error enumerados en la tabla siguiente.

Código de error Mensaje de error Detalles
400 BadRequest RoleNotFound No roleDefinitionId se puede encontrar el proporcionado en el cuerpo de la solicitud.
400 BadRequest ResourceIsLocked El recurso proporcionado en el cuerpo de la solicitud está en estado y no puede crear solicitudes de Locked asignación de roles.
400 BadRequest SubjectNotFound No subjectId se puede encontrar el proporcionado en el cuerpo de la solicitud.
400 BadRequest PendingRoleAssignmentRequest Ya existe una governanceRoleAssignmentRequest pendiente en el sistema.
400 BadRequest RoleAssignmentExists El governanceRoleAssignment solicitado para crearse ya existe en el sistema.
400 BadRequest RoleAssignmentDoesNotExist El governanceRoleAssignment solicitado para actualizarse o extenderse no existe en el sistema.
400 BadRequest RoleAssignmentRequestPolicyValidationFailed GovernanceRoleAssignmentRequest no cumple las directivas internas y no se puede crear.

Ejemplos

En los ejemplos siguientes se muestra cómo usar esta API.

Ejemplo 1: El administrador asigna un usuario a un rol

En este ejemplo, un administrador asigna un usuario nawu@contoso.com al rol Lector de facturación.

Nota: Además del permiso, este ejemplo requiere que el solicitante tenga al menos una Active asignación de roles de administrador (owner o user access administrator) en el recurso.

Propiedad Tipo Obligatorio Valor
resourceId Cadena Sí <resourceId>
roleDefinitionId Cadena Sí <roleDefinitionId>
subjectId Cadena Sí <subjectId>
assignmentState Cadena Sí Apto/activo
type Cadena Sí AdminAdd
motivo Cadena depende de la configuración del rol
schedule governanceSchedule Sí

Solicitud

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "ea48ad5e-e3b0-4d10-af54-39a45bbfe68d",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Eligible",
  "type": "AdminAdd",
  "reason": "Assign an eligible role",
  "schedule": {
    "startDateTime": "2018-05-12T23:37:43.356Z",
    "endDateTime": "2018-11-08T23:37:43.356Z",
    "type": "Once"
  }
}

Respuesta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "1232e4ea-741a-4be5-8044-5edabdd61672",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "ea48ad5e-e3b0-4d10-af54-39a45bbfe68d",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminAdd",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Evaluate Only",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:37:43.356Z",
    "endDateTime": "2018-11-08T23:37:43.356Z",
    "duration": "PT0S"
  }
}

Ejemplo 2: El usuario activa el rol apto

En este ejemplo, el usuario nawu@contoso.com activa el rol lector de facturación apto.

Propiedad Tipo Obligatorio Valor
resourceId Cadena Sí <resourceId>
roleDefinitionId Cadena Sí <roleDefinitionId>
subjectId Cadena Sí <subjectId>
assignmentState Cadena Sí Activo
type Cadena Sí Useradd
motivo Cadena depende de la configuración del rol
schedule governanceSchedule Sí

Solicitud

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "8b4d1d51-08e9-4254-b0a6-b16177aae376",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Active",
  "type": "UserAdd",
  "reason": "Activate the owner role",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:28:43.537Z",
    "duration": "PT9H"
  },
  "linkedEligibleRoleAssignmentId": "e327f4be-42a0-47a2-8579-0a39b025b394"
}

Respuesta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "3ad49a7c-918e-4d86-9f84-fab28f8658c0",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "8b4d1d51-08e9-4254-b0a6-b16177aae376",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "e327f4be-42a0-47a2-8579-0a39b025b394",
  "type": "UserAdd",
  "assignmentState": "Active",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Activate the owner role",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "EligibilityRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      },
      {
        "key": "JustificationRule",
        "value": "Grant"
      },
      {
        "key": "ActivationDayRule",
        "value": "Grant"
      },
      {
        "key": "ApprovalRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:28:43.537Z",
    "endDateTime": "0001-01-01T00:00:00Z",
    "duration": "PT9H"
  }
}

Ejemplo 3: El usuario desactiva un rol asignado

En este ejemplo, el usuario nawu@contoso.com desactiva el rol lector de facturación activo.

Propiedad Tipo Obligatorio Valor
resourceId Cadena Sí <resourceId>
roleDefinitionId Cadena Sí <roleDefinitionId>
subjectId Cadena Sí <subjectId>
assignmentState Cadena Sí Activo
type Cadena Sí UserRemove
motivo Cadena No
schedule governanceSchedule No

Solicitud

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "bc75b4e6-7403-4243-bf2f-d1f6990be122",
  "resourceId": "fb016e3a-c3ed-4d9d-96b6-a54cd4f0b735",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Active",
  "type": "UserRemove",
  "reason": "Deactivate the role",
  "linkedEligibleRoleAssignmentId": "cb8a533e-02d5-42ad-8499-916b1e4822ec"
}

Respuesta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "abfcdb57-8e5d-42a0-ae67-7598b96fddb1",
  "resourceId": "fb016e3a-c3ed-4d9d-96b6-a54cd4f0b735",
  "roleDefinitionId": "bc75b4e6-7403-4243-bf2f-d1f6990be122",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "cb8a533e-02d5-42ad-8499-916b1e4822ec",
  "type": "UserRemove",
  "assignmentState": "Active",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Evaluate only",
  "schedule": null,
  "status": {
    "status": "Closed",
    "subStatus": "Revoked",
    "statusDetails": []
  }
}

Ejemplo 4: El administrador quita al usuario de un rol

En este ejemplo, un administrador quita al usuario nawu@contoso.com del rol Lector de facturación.

Nota: Además del permiso, este ejemplo requiere que el solicitante tenga al menos una Active asignación de roles de administrador (owner o user access administrator) en el recurso.

Propiedad Tipo Obligatorio Valor
resourceId Cadena Sí <resourceId>
roleDefinitionId Cadena Sí <roleDefinitionId>
subjectId Cadena Sí <subjectId>
assignmentState Cadena Sí Apto/activo
type Cadena Sí AdminRemove
motivo Cadena No
schedule governanceSchedule No

Solicitud

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "65bb4622-61f5-4f25-9d75-d0e20cf92019",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "assignmentState": "Eligible",
  "type": "AdminRemove"
}

Respuesta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "c934fcb9-cf53-42ac-a8b4-6246f6726299",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "65bb4622-61f5-4f25-9d75-d0e20cf92019",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminRemove",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": null,
  "status": {
    "status": "Closed",
    "subStatus": "Revoked",
    "statusDetails": []
  },
  "schedule": null
}

Ejemplo 5: Asignación de roles de actualizaciones de administrador

En este ejemplo, los administradores actualizan la asignación de roles del usuario nawu@contoso.com al propietario.

Nota: Además del permiso, este ejemplo requiere que el solicitante tenga al menos una Active asignación de roles de administrador (owner o user access administrator) en el recurso.

Propiedad Tipo Obligatorio Valor
resourceId Cadena Sí <resourceId>
roleDefinitionId Cadena Sí <roleDefinitionId>
subjectId Cadena Sí <subjectId>
assignmentState Cadena Sí Apto/activo
type Cadena Sí AdminUpdate
motivo Cadena depende de roleSettings
schedule governanceSchedule Sí

Solicitud

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "70521f3e-3b95-4e51-b4d2-a2f485b02103",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "1566d11d-d2b6-444a-a8de-28698682c445",
  "assignmentState": "Eligible",
  "type": "AdminUpdate",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-03-08T05:42:45.317Z",
    "endDateTime": "2018-06-05T05:42:31.000Z"
  }
}

Respuesta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "4f6d4802-b3ac-4f5a-86d7-a6a4edd7d383",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "70521f3e-3b95-4e51-b4d2-a2f485b02103",
  "subjectId": "1566d11d-d2b6-444a-a8de-28698682c445",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminUpdate",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": null,
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-03-08T05:42:45.317Z",
    "endDateTime": "2018-06-05T05:42:31Z",
    "duration": "PT0S"
  }
}

Ejemplo 6: El administrador extiende la asignación de roles que expira

En este ejemplo se amplía la asignación de roles que expira para el usuario ANUJCUSER a API Management colaborador del servicio.

Nota: Además del permiso, este ejemplo requiere que el solicitante tenga al menos una Active asignación de roles de administrador (owner o user access administrator) en el recurso.

Propiedad Tipo Obligatorio Valor
resourceId Cadena Sí <resourceId>
roleDefinitionId Cadena Sí <roleDefinitionId>
subjectId Cadena Sí <subjectId>
assignmentState Cadena Sí Apto/activo
type Cadena Sí AdminExtend
motivo Cadena depende de roleSettings
schedule governanceSchedule Sí

Solicitud

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "0e88fd18-50f5-4ee1-9104-01c3ed910065",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "assignmentState": "Eligible",
  "type": "AdminExtend",
  "reason": "extend role assignment",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:53:55.327Z",
    "endDateTime": "2018-08-10T23:53:55.327Z"
  }
}

Respuesta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "486f0c05-47c8-4498-9c06-086a78c83004",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "0e88fd18-50f5-4ee1-9104-01c3ed910065",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminExtend",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "extend role assignment",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:53:55.327Z",
    "endDateTime": "2018-08-10T23:53:55.327Z",
    "duration": "PT0S"
  }
}