Retirar un dispositivo móvil de Intune con PowerShell – Invoke‑MgDeviceManagementManagedDeviceRetire

Retirar un teléfono o portátil administrado de Microsoft Intune mediante PowerShell es un trámite habitual, pero un identificador erróneo o un permiso ausente bastan para frustrar la tarea. Este artículo desglosa paso a paso la operación «Retire» y cómo resolver los errores más comunes.

Índice

Qué significa realmente «retirar» un dispositivo

En Microsoft Intune, Retire no es lo mismo que Wipe ni que Delete. Un dispositivo retirado abandona la administración MDM y se eliminan los perfiles de configuración, las aplicaciones administradas y el registro de la compañía. Los datos personales permanecen intactos. Por eso es la opción preferida cuando un empleado cambia de terminal o se jubila el hardware, mientras que Wipe suele reservarse para pérdidas o robos y Delete para limpieza de reporting.

Requisitos previos imprescindibles

Cuenta de Azure AD con rol mínimo «Intune Service Administrator» o permisos delegados DeviceManagementManagedDevices.PrivilegedOperations.All.
Módulo Microsoft.Graph versión 2.0 o posterior instalado en el canal Release.
Dispositivo en estado Managed y sin acciones pendientes en el portal de Intune.
Conexión a Internet para alcanzar graph.microsoft.com (puertos 443).

Actualizar e importar el módulo Microsoft Graph

Los cmdlets de Graph cambian con frecuencia; usar la versión correcta evita sorpresas:

# Comprueba la versión instalada
Get-InstalledModule Microsoft.Graph -ErrorAction SilentlyContinue | Select Name, Version, Repository

Actualiza al último release

Update-Module Microsoft.Graph -Force

Importa los cmdlets necesarios (solo el sub‑módulo de dispositivos)

Import-Module Microsoft.Graph.DeviceManagement.ManagedDevices

Obtener el identificador correcto

El error más habitual consiste en pasar el ObjectId de Azure AD en vez del ManagedDeviceId que usa Intune. Extraerlo es sencillo:

# Inicia sesión de Graph; se abrirá un navegador para el consentimiento
Connect-MgGraph -Scopes "DeviceManagementManagedDevices.Read.All"

Lista los dispositivos gestionados y filtra columnas clave

Get-MgDeviceManagementManagedDevice \`
\| Select DisplayName, OperatingSystem, ComplianceState, ManagedDeviceId

Apunta el GUID de la columna ManagedDeviceId; será el parámetro que reciba -ManagedDeviceId.

Comprobar y conceder permisos de Graph

Aunque la cuenta sea administradora global, la aplicación PowerShell necesita autorización explícita. Si el cmdlet devuelve 403 Forbidden, lo normal es que falte el scope correcto.

Ejecuta Connect-MgGraph -Scopes "DeviceManagementManagedDevices.PrivilegedOperations.All".
Acepta el consentimiento en el navegador con una cuenta que tenga permiso para otorgar permisos de administrador.
Cierra la sesión de PowerShell (Disconnect-MgGraph) y vuelve a abrirla para refrescar el token.

Ejecutar el cmdlet de retirada paso a paso

El nombre oficial desde el SDK v2 es Invoke-MgDeviceManagementManagedDeviceRetire. El alias Invoke‑MgRetireDeviceManagementManagedDevice sigue funcionando, pero conviene adoptar el nuevo para evitar confusiones.

# Una primera prueba con Debug para ver la petición HTTP
Invoke-MgDeviceManagementManagedDeviceRetire `
  -ManagedDeviceId "e4ecf4c9-2df6-4c8a-81b5-9f9c9e8eeab4" `
  -Debug

Interpretar la salida -Debug

POST a /deviceManagement/managedDevices/{id}/retire indica que la ruta es correcta.
Cabecera Authorization: Bearer eyJ0eXAiOi... debe estar presente y no expirar en menos de dos minutos.
Si la respuesta es 204 No Content, la solicitud se ha aceptado; la acción tardará unos minutos en reflejarse.

Tabla de errores habituales de Graph Retire

Código HTTP	Mensaje típico	Causa más probable	Corrección sugerida
403 Forbidden	Insufficient privileges	Scope de Graph incorrecto o token obsoleto	Conceder `DeviceManagementManagedDevices.PrivilegedOperations.All` y volver a iniciar sesión
404 Not Found	Resource not found	ManagedDeviceId erróneo o dispositivo ya eliminado	Listar dispositivos y confirmar GUID
409 Conflict	Sync pending	Hay otra acción de administración en curso	Esperar a que finalice o cancelar la acción previa
503 Service Unavailable	Server busy	Servicio Graph saturado u operación masiva	Reintentar con back‑off exponencial

Verificar el progreso en Intune

La consola web de Intune refleja la acción como «Pending retire». Cuando el terminal se conecte, descargará la orden y cambiará a «Retired». Para acelerar el proceso puedes forzar una sincronización:

Invoke-MgDeviceManagementManagedDeviceSyncDevice `
  -ManagedDeviceId "e4ecf4c9-2df6-4c8a-81b5-9f9c9e8eeab4"

Plan B: llamada REST directa

Si sospechas de un bug en el cmdlet, usa Invoke-MgGraphRequest. El endpoint es idéntico, por lo que el resultado debe coincidir:

$body = @{
    method = "POST"
    uri    = "https://graph.microsoft.com/v1.0/deviceManagement/managedDevices/e4ecf4c9-2df6-4c8a-81b5-9f9c9e8eeab4/retire"
}
Invoke-MgGraphRequest @body

Si aquí obtienes 204 pero el cmdlet nativo sigue fallando, actualiza a la última versión del SDK v2; ese suele ser el origen.

Automatizar la retirada en masa

En entornos con rotación frecuente de dispositivos resulta útil un script que acepte listados CSV. Un esqueleto operativo:

param(
    [Parameter(Mandatory)]
    [string] $CsvPath
)

Connect-MgGraph -Scopes "DeviceManagementManagedDevices.PrivilegedOperations.All"

\$devices = Import-Csv -Path \$CsvPath
foreach (\$device in \$devices) {
try {
Invoke-MgDeviceManagementManagedDeviceRetire \`
-ManagedDeviceId \$device.ManagedDeviceId -ErrorAction Stop
Write-Host "Solicitada retirada de \$(\$device.DisplayName)"
}
catch {
Write-Warning "Error en \$(\$device.DisplayName): \$($\_.Exception.Message)"
}
}

Preguntas frecuentes

¿El cmdlet está aún en versión beta?

No. Desde febrero de 2024 la operación Retire está en el canal estable del módulo Microsoft.Graph.DeviceManagement.ManagedDevices. Si tu PowerShell muestra «beta» es que estás usando una versión preliminar que conviene reemplazar.

¿Se pierde el contenido personal del usuario?

No. «Retire» desinstala perfiles de empresa y borra datos administrados, pero fotos, contactos y aplicaciones personales permanecen.

¿Cuánto tarda en completarse?

Depende de la cadencia de sincronización del dispositivo: iOS y Android suelen aplicar la orden en menos de quince minutos; Windows 10/11 puede tardar hasta una hora si el equipo está en reposo.

Flujo de trabajo recomendado

Identificar el ManagedDeviceId correcto con Get-MgDeviceManagementManagedDevice.
Conectar a Graph con el scope adecuado y Token fresco.
Ejecutar Invoke-MgDeviceManagementManagedDeviceRetire con -Debug.
Verificar 204 No Content o capturar el error y compararlo con la tabla anterior.
Forzar sincronización si el dispositivo no se conecta.
Confirmar el estado «Retired» en el portal o con Get-MgDeviceManagementManagedDevice.

Conclusión

La mayoría de fallos al retirar dispositivos de Intune provienen de un GUID erróneo o de un permiso incompleto, no de que el cmdlet siga en beta. Con un módulo actualizado, el scope DeviceManagementManagedDevices.PrivilegedOperations.All y el ManagedDeviceId correcto, la acción «Retire» funciona de forma fiable y puede automatizarse sin complicaciones.

Retirar un dispositivo móvil de Intune con PowerShell – Invoke‑MgDeviceManagementManagedDeviceRetire