Dominar el flujo de identidad administrada con PowerShell y Microsoft Graph

By Mirko Peters · 2026-08-28

¡Bienvenido de nuevo al blog del podcast! Si alguna vez te has frustrado con contraseñas codificadas en los scripts, con engorrosos secretos de cliente o con la preocupación de que las credenciales se filtren en tus automatizaciones…

Automatically translated with AI from the original post. Read the English original

¡Bienvenido de nuevo al blog del podcast! Si alguna vez te ha frustrado tener contraseñas codificadas en los scripts, gestionar engorrosos secretos de cliente o preocuparte por que las credenciales se filtren en tus automatizaciones, estás en el lugar correcto. La automatización en la nube exige un cambio de mentalidad en lo que respecta a la seguridad. Ya pasaron los días en que los administradores podían guardar credenciales en archivos de configuración en texto plano o en variables de entorno sin mirar por encima del hombro. Hoy profundizamos en el mundo de la autenticación nativa de la nube y vemos cómo puedes aprovechar las identidades administradas de Azure dentro de tus scripts de PowerShell para autenticarte de forma segura en Microsoft Graph, sin almacenar credenciales sensibles.

Automatizar tu entorno de Microsoft 365 ya no es una habilidad deseable; es una necesidad operativa absoluta. Sin embargo, combinar PowerShell con la API de Microsoft Graph puede parecer a veces un laberinto de solicitudes de permisos, límites de throttling y flujos complejos de obtención de tokens. Si adoptamos una mentalidad moderna centrada en la identidad, podemos eliminar por completo la gestión de credenciales para las cargas de trabajo que se ejecutan en Azure. En esta publicación analizaremos los componentes esenciales de la autenticación nativa de la nube, repasando los requisitos previos, los registros de aplicaciones en Azure AD, los flujos de obtención de tokens y la optimización de scripts. Si quieres profundizar en este flujo de trabajo, no dejes de escuchar nuestro episodio complementario del podcast, Use Managed Identity with PowerShell for Microsoft Graph.

Requisitos previos para PowerShell + API de Graph

Antes de empezar a automatizar tareas de Microsoft 365 con PowerShell y la API de Graph, debes preparar correctamente tu sistema y tu entorno. Esta preparación garantiza una ejecución fluida y un acceso seguro a los recursos de Microsoft Graph.

Instalación de los módulos de PowerShell

Debes instalar los módulos de PowerShell adecuados para interactuar con la API de Microsoft Graph. El SDK de PowerShell de Microsoft Graph proporciona todos los cmdlets necesarios para esta integración. Para evitar errores, comprueba que tu sistema cumple estos requisitos mínimos:

Puedes actualizar PowerShellGet ejecutando Install-Module PowerShellGet -Force y configurar la directiva de ejecución con Set-ExecutionPolicy RemoteSigned. Después, instala el módulo de Microsoft Graph con:

Install-Module Microsoft.Graph -Scope CurrentUser

Este comando descarga la última versión estable del módulo, lo que te permite llamar a los endpoints de Microsoft Graph de forma sencilla.

Configuración del entorno de Microsoft 365

Configurar correctamente tu entorno de Microsoft 365 es fundamental para la automatización. Sigue estos pasos para empezar:

1. Confirma que tu sistema cumple los requisitos: PowerShell 7.2 o posterior, .NET Framework 4.7.2 o posterior y el módulo PowerShellGet más reciente.
2. Instala el módulo de PowerShell de Microsoft Graph tal como se indicó anteriormente.
3. Conéctate al inquilino de Microsoft 365 importando el módulo y autenticándote con los permisos necesarios. Por ejemplo:

Connect-MgGraph -Scopes "User.ReadWrite.All","Directory.ReadWrite.All"

Este comando te pide que inicies sesión y concede a tu sesión permisos para leer y escribir datos de usuarios y del directorio. Puedes ajustar los ámbitos según las necesidades de tu automatización.

Comprender los permisos y los ámbitos

Los permisos y los ámbitos definen qué pueden acceder o modificar tus scripts en Microsoft 365. La API de Microsoft Graph utiliza dos tipos principales de permisos:

• Permisos delegados: Se aplican cuando ejecutas scripts como un usuario que ha iniciado sesión. Limitan el acceso a los datos que el usuario posee o a los que puede acceder.
• Permisos de aplicación: Permiten que tu aplicación o script acceda a los datos de toda la organización sin un usuario que haya iniciado sesión, lo habitual en la automatización en segundo plano y en los flujos con identidad administrada.

Entre los permisos habituales están *.Read.All, para acceso de solo lectura, y *.ReadWrite.All, para lectura y escritura completas. Por ejemplo, SecurityActions.Read.All te permite ver las acciones de seguridad, mientras que SecurityActions.ReadWrite.All permite modificarlas.

Los permisos de aplicación requieren consentimiento de administrador. Un administrador del inquilino debe aprobarlos para garantizar la seguridad. Además, los usuarios necesitan los roles de Microsoft Entra adecuados, como Lector de seguridad, para acceder a datos sensibles. Este control de acceso basado en roles añade una capa de seguridad adicional.

Cuando te conectes con el SDK de PowerShell de Microsoft Graph, especifica solo los ámbitos que necesite tu script. Esta práctica sigue el principio de privilegio mínimo y reduce los riesgos de seguridad. Ten en cuenta que los permisos concedidos a tu aplicación se aplican a todos los usuarios de esa aplicación, así que revísalos y gestiónalos periódicamente.

Identidad de aplicación en Azure AD

Registrar una nueva aplicación

Para automatizar tareas de Microsoft 365 con PowerShell y la API de Graph, primero debes registrar una aplicación en Azure Active Directory (Azure AD). Esta aplicación actúa como una identidad que tus scripts usan para acceder de forma segura a Microsoft Graph. Sigue estos pasos para registrar tu aplicación:

1. Abre el portal de Azure y ve a Azure Active Directory > Registros de aplicaciones > Nuevo registro.
2. Dale a tu aplicación un nombre significativo, como "My Graph Automation App".
3. Elige los tipos de cuenta compatibles:
   • Inquilino único: solo los usuarios de tu inquilino de Azure AD pueden iniciar sesión.
   • Varios inquilinos: los usuarios de cualquier inquilino de Azure AD pueden iniciar sesión.
   • Varios inquilinos y cuentas personales: incluye a los usuarios de Azure AD y las cuentas personales de Microsoft.
4. Configura el URI de redirección según el tipo de aplicación:
   • Para las aplicaciones web, usa una URL como https://yourapp.com/auth/callback.
   • Para las aplicaciones de una sola página, usa https://yourapp.com.
   • Para las aplicaciones móviles o de escritorio, usa https://login.microsoftonline.com/common/oauth2/nativeclient.
5. Haz clic en Registrar para crear tu aplicación.

Este proceso crea una identidad de aplicación única en tu inquilino. La usarás para solicitar tokens y llamar a la API de Microsoft Graph.

Configurar los permisos de API

Después de registrar tu aplicación, debes configurar los permisos de API que necesita. Estos permisos controlan lo que tu aplicación puede acceder o modificar en Microsoft 365. Para establecer los permisos:

1. En el registro de tu aplicación, ve a Permisos de API > Agregar un permiso > Microsoft Graph.
2. Elige Permisos de aplicación si tu script se ejecuta sin interfaz o mediante un contexto de identidad administrada, o Permisos delegados si se ejecuta de forma interactiva.
3. Selecciona los permisos específicos que necesita tu aplicación, como User.Read.All o Directory.Read.All.
4. Haz clic en Agregar permisos para aplicarlos.

⚠️ Aplica siempre el principio de privilegio mínimo. Asigna solo los permisos que necesita tu aplicación para reducir los riesgos de seguridad.

Algunos permisos requieren consentimiento de administrador antes de que tu aplicación pueda usarlos. Puedes concederlo haciendo clic en Conceder consentimiento de administrador para [nombre del inquilino] en el portal de Azure. Revisa los permisos con regularidad para evitar que tu aplicación tenga más privilegios de los necesarios.

Generar un secreto de cliente o un certificado

Tu aplicación necesita credenciales para autenticarse de forma segura con Azure AD si no usas una identidad administrada. Puedes usar un secreto de cliente o un certificado. Ambos métodos demuestran la identidad de tu aplicación al solicitar tokens.

Para crear un secreto de cliente, ve a Certificados y secretos en el registro de tu aplicación, selecciona Nuevo secreto de cliente, agrega una descripción y define un periodo de expiración. Para los certificados, sube un archivo de certificado válido en la misma sección.

Obtención de tokens de acceso

Comprender OAuth 2.0

OAuth 2.0 desempeña un papel fundamental para proteger tu acceso a la API de Microsoft Graph cuando usas PowerShell + API de Graph. Actúa como un guardián de confianza que permite a tus aplicaciones autenticarse de forma segura y obtener tokens de acceso. Estos tokens funcionan como llaves digitales que permiten a tus scripts llamar a los endpoints de Microsoft Graph sin exponer tus credenciales directamente.

Para usar OAuth 2.0, primero debes registrar tu aplicación en Azure Active Directory (Azure AD). Este registro proporciona credenciales de cliente, como un ID de aplicación y un secreto o certificado. Cuando tu script solicita un token de acceso, presenta estas credenciales a Azure AD. Azure AD verifica entonces tu identidad y emite un token de vida corta. Tu script incluye este token en las solicitudes a la API para demostrar que tiene derecho a acceder a los recursos solicitados.

Este proceso garantiza un acceso seguro y controlado a los datos de Microsoft 365. Además, admite permisos granulares, de modo que tus scripts solo obtienen el acceso que necesitan. Al seguir los estándares de OAuth 2.0, proteges tu entorno frente a accesos no autorizados y, al mismo tiempo, habilitas una automatización potente con PowerShell + API de Graph.

Uso de PowerShell para solicitudes de token

Puedes obtener tokens de acceso mediante varios flujos de autenticación adaptados a distintos escenarios. Cada flujo equilibra la seguridad y la facilidad de uso de forma diferente. La API de Microsoft Graph admite estos flujos comunes:

• Flujo de código de dispositivo: ideal para dispositivos o scripts sin navegador ni capacidad de entrada. Te autenticas en un dispositivo independiente, lo que lo hace seguro y fácil de usar.
• Flujo basado en certificados: diseñado para la automatización sin interfaz, este flujo usa certificados en lugar de contraseñas, lo que mejora la seguridad de los scripts desatendidos.
• Flujo de identidad administrada: ideal para entornos nativos de la nube como Azure Functions o máquinas virtuales, este flujo aprovecha las identidades administradas de Azure para obtener tokens sin almacenar secretos.

Flujo de código de dispositivo

El flujo de código de dispositivo funciona bien cuando ejecutas scripts en local o en dispositivos sin opciones de entrada cómodas. Te permite autenticarte de forma interactiva en otro dispositivo, como tu teléfono o el navegador de tu PC.

Así puedes usar el flujo de código de dispositivo con PowerShell:

1. Ejecuta el siguiente comando para iniciar la autenticación con código de dispositivo:

   Connect-MgGraph -Scopes "User.Read.All" -DeviceCode

2. PowerShell muestra un código y una URL. Abre la URL en el navegador de cualquier dispositivo.
3. Introduce el código que aparece en PowerShell e inicia sesión con tu cuenta de Microsoft 365.
4. Una vez completada la autenticación, PowerShell obtiene un token de acceso y conecta tu sesión.

💡 El flujo de código de dispositivo equilibra seguridad y facilidad de uso. Evita incrustar credenciales en los scripts y funciona bien para tareas manuales o semiautomatizadas.

Flujo basado en certificados

El flujo basado en certificados es adecuado para scripts automatizados que se ejecutan sin interacción del usuario. En lugar de un secreto de cliente, usas un certificado para demostrar la identidad de tu aplicación. Este método reduce los riesgos asociados a secretos filtrados.

Para usar este flujo, sigue estos pasos:

1. Registra tu aplicación en Azure AD y sube un certificado en Certificados y secretos.
2. Almacena el certificado de forma segura en el equipo que ejecuta tu script.
3. Usa PowerShell para solicitar un token especificando la huella digital del certificado, el ID de cliente y el ID de inquilino.

Este es un ejemplo simplificado de cómo obtener un token con un certificado en PowerShell:

$tenantId = "YOUR_TENANT_ID"
$clientId = "YOUR_CLIENT_ID"
$certThumbprint = "YOUR_CERT_THUMBPRINT"
$cert = Get-Item Cert:\CurrentUser\My\$certThumbprint
$body = @{
    grant_type = "client_credentials"
    client_id = $clientId
    scope = "https://graph.microsoft.com/.default"
    client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    client_assertion = New-JwtToken -Certificate $cert -TenantId $tenantId -ClientId $clientId
}
$tokenResponse = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -Body $body
$accessToken = $tokenResponse.access_token

⚠️ Gestionar certificados requiere cuidado. Protege las claves privadas y renueva los certificados con regularidad para mantener la seguridad.

Flujo de identidad administrada

El flujo de identidad administrada funciona mejor cuando ejecutas scripts de PowerShell + Graph API dentro de servicios de Azure como Azure Virtual Machines, Azure Functions o Azure Automation. Azure asigna automáticamente una identidad a tu recurso, por lo que no tienes que gestionar credenciales manualmente.

Para obtener un token de acceso con identidad administrada, sigue estos pasos:

1. Habilita la identidad administrada (asignada por el sistema o asignada por el usuario) en tu recurso de Azure.
2. Asigna los permisos necesarios de Microsoft Graph API a esta identidad en Azure AD mediante Microsoft Graph PowerShell o Graph Explorer.
3. Usa PowerShell para solicitar un token al servicio local de metadatos de instancias de Azure (IMDS).

Ejemplo de fragmento de PowerShell para obtener un token mediante identidad administrada:

$resource = "https://graph.microsoft.com"
$tokenAuthUri = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=$resource"
$headers = @{ Metadata = "true" }
$response = Invoke-RestMethod -Method Get -Uri $tokenAuthUri -Headers $headers
$accessToken = $response.access_token

🔐 El flujo de identidad administrada elimina la necesidad de almacenar secretos en tus scripts. Ofrece una autenticación segura y transparente dentro de los entornos de Azure.

Realizar llamadas a la API con PowerShell + Graph API

Realizar llamadas a la API con PowerShell + Graph API te permite interactuar de forma eficaz con los servicios de Microsoft 365. Entender cómo construir solicitudes HTTP es esencial para una comunicación correcta con la API.

Construcción de solicitudes HTTP

Cuando interactúas con Microsoft Graph API, debes construir las solicitudes HTTP correctamente. Estos son los componentes clave de una solicitud HTTP:

• Recuperación del token de acceso: usa el token obtenido en el encabezado.
• Configuración de encabezados: establece los encabezados necesarios, incluidos Content-Type: application/json y Authorization: Bearer $accessToken.
• Solicitud GET/POST: realiza una solicitud explícita al endpoint de Microsoft Graph API que necesites.

Uso de Invoke-RestMethod

El cmdlet Invoke-RestMethod simplifica la comunicación con Microsoft Graph API. Permite enviar solicitudes HTTP y recibir respuestas de forma directa. Aquí tienes un resumen rápido de su comportamiento y sus limitaciones:

Endpoints comunes de la API

Varios endpoints de Microsoft Graph API se usan con frecuencia para tareas de administración de Microsoft 365. Estos son algunos de los más comunes:

Gestión de la salida de la API

Entender las respuestas JSON

Cuando interactúas con Microsoft Graph API, devuelve los datos en formato JSON. JSON (JavaScript Object Notation) es ligero y fácil de leer. Entender las respuestas JSON es fundamental para manipular los datos con eficacia. Una respuesta JSON típica tiene este aspecto:

{
  "id": "1",
  "displayName": "John Doe",
  "mail": "john.doe@example.com"
}

Conversión de JSON a objetos de PowerShell

Para trabajar con datos JSON en PowerShell, debes convertirlos en objetos de PowerShell. Esta conversión te permite manipular los datos con facilidad. Para ello puedes usar el cmdlet ConvertFrom-Json. Así funciona:

$jsonData = '{"id": "1", "displayName": "John Doe", "mail": "john.doe@example.com"}'
$powerShellObject = $jsonData | ConvertFrom-Json

Ahora, $powerShellObject contiene propiedades a las que puedes acceder directamente, como $powerShellObject.displayName.

Filtrado y formato de datos

Una vez que tengas tus datos en objetos de PowerShell, puedes filtrarlos y darles formato según tus necesidades. PowerShell ofrece varias técnicas para refinar la salida de datos. Por ejemplo, puedes usar parámetros de consulta OData al realizar llamadas a la API para filtrar los resultados directamente desde Microsoft Graph API.

Exportación de resultados

Exportar los resultados de tus scripts de PowerShell es esencial para una gestión eficaz de los datos. Puedes guardar la salida en varios formatos, como CSV, JSON o XML. Por ejemplo, puedes exportar los datos de usuario de esta forma:

$users = Get-MgUser -All
$users | Select-Object DisplayName, Mail | Export-Csv -Path "Users.csv" -NoTypeInformation

Procedimientos recomendados y solución de problemas

Gestión de errores y límites de la API

Al trabajar con Microsoft Graph API, los errores suelen deberse a configuraciones específicas del inquilino o problemas de permisos. Muchos usuarios ejecutan scripts descargados de internet sin adaptarlos a su entorno, lo que provoca fallos. Además, Microsoft Graph aplica límites de frecuencia para proteger sus servicios. Si tu script envía demasiadas solicitudes en poco tiempo, la API devuelve un código de estado 429. Debes respetar el encabezado Retry-After y esperar el tiempo sugerido antes de volver a intentarlo.

Protección de credenciales

Proteger tus credenciales es fundamental al automatizar tareas de Microsoft 365. Usa registros de aplicaciones e identidades administradas para crear identidades seguras para tus aplicaciones. Evita almacenar secretos de cliente en texto plano dentro de tus scripts siempre que sea posible.

Optimización de scripts

Los scripts eficientes ahorran tiempo y reducen el consumo de recursos. Recupera solo las propiedades que necesitas aplicando el parámetro de consulta $select, aprovecha los mecanismos de procesamiento por lotes y diseña tus bucles de automatización con controladores de paginación bien estructurados.

Dominar los flujos de identidades administradas con PowerShell y Microsoft Graph API cambia por completo la forma de abordar la automatización en la nube. Al eliminar secretos estáticos y adoptar identidades nativas de la nube, creas flujos de trabajo resilientes y muy seguros que protegen tu empresa. Para conocer más sobre estas estrategias y escuchar debates prácticos sobre la administración moderna en la nube, no dejes de revisar nuestro episodio relacionado: Use Managed Identity with PowerShell for Microsoft Graph. Prueba estos ejemplos en tu tenant de pruebas hoy mismo y lleva tu marco de automatización al siguiente nivel.

Preguntas frecuentes

¿Qué es PowerShell?

PowerShell es un marco de automatización de tareas de Microsoft que combina un shell de línea de comandos con un lenguaje de scripting para agilizar la administración del sistema y las operaciones en la nube.

¿Qué es Microsoft Graph API?

Microsoft Graph API es un punto de conexión RESTful unificado para acceder a datos y servicios de Microsoft 365, incluidos usuarios, grupos, correo y configuraciones del directorio.

¿Cómo instalo el módulo de PowerShell de Microsoft Graph?

Puedes instalar el módulo ejecutando Install-Module Microsoft.Graph -Scope CurrentUser en tu entorno de PowerShell 7.

¿Qué son los permisos delegados y los permisos de aplicación?

Los permisos delegados permiten que tu aplicación actúe en nombre de un usuario que ha iniciado sesión, mientras que los permisos de aplicación permiten la ejecución en segundo plano sin un contexto de usuario activo.

¿Cómo gestiono los límites de frecuencia de la API?

Revisa siempre el valor de Retry-After en los encabezados de respuesta cuando recibas un código de estado 429, e implementa en tus scripts una lógica de reintentos con retroceso exponencial.

¿Qué es OAuth 2.0?

OAuth 2.0 es un marco de autorización que permite a las aplicaciones obtener de forma segura tokens de acceso para llamar a API protegidas sin exponer las credenciales del usuario.

¿Puedo usar PowerShell en Linux?

¡Sí! PowerShell es totalmente multiplataforma y se ejecuta de forma nativa en Windows, macOS y Linux.

¿Cómo exporto datos desde PowerShell?

Puedes exportar datos estructurados fácilmente con cmdlets como Export-Csv o ConvertTo-Json, según los requisitos de formato de tus informes.