Introducción al SDK de Microsoft Graph PowerShell
Un enfoque unificado para la gestión de Microsoft 365
La API de Microsoft Graph existe desde hace algún tiempo y Microsoft está trasladando más funciones de administración (como la administración de licencias para cuentas de Azure AD) a la plataforma. Cuando Microsoft realiza la transición de una función a Graph, es posible que las organizaciones tengan que actualizar los scripts de PowerShell.
Comenzar a utilizar Graph API puede ser una tarea desalentadora, especialmente si no tiene experiencia con servicios basados en REST. Con algo de práctica y tiempo dedicado a leer la documentación de Graph, es posible ver cómo se crean herramientas como la Evaluación de migración de inquilinos de Microsoft 365 y comenzar a comprender el valor de usar Graph.
Si desea una forma más familiar de aprovechar Graph, el SDK de Microsoft Graph PowerShell simplifica el proceso y lo empaqueta en un módulo de PowerShell (relativamente) simple. Hay altibajos al conectarse a Microsoft Graph mediante el SDK de PowerShell, pero facilita el proceso de aprendizaje y adopción de la API Graph para los administradores de inquilinos.
En la primera parte de una serie sobre el uso del SDK de Microsoft Graph PowerShell, explico qué es el SDK y qué se debe tener en cuenta al comenzar.
¿Qué es la API de Microsoft Graph?
Una forma de ver la API de Microsoft Graph (o cualquier API de Graph) es como un conjunto de nodos en una estructura de árbol lógica. La solicitud se envía al punto final que representa los datos a los que desea acceder.
Por ejemplo, el punto final usuarios (https://graph.microsoft.com/v1.0) devuelve todos los usuarios del inquilino, pero Para obtener datos sobre un usuario específico, por ejemplo, usuario1@contoso.com, consultamos el punto final https://graph.microsoft.com/v1.0/user1@contoso.com.
Esta lógica continúa a lo largo de la estructura como se muestra en la Figura 1. Por ejemplo, el punto final https://graph.microsoft.com/v1.0/user1@contoso.com/Messages devuelve los mensajes de correo electrónico de user1@contoso.com, mientras que el punto final https://graph.microsoft.com/v1.0/user1@contoso.com/<ID de mensaje> devuelve los detalles de un mensaje individual.
Microsoft Graph Explorer es una forma útil de explorar los diferentes puntos finales y la información que devuelven. También viene con un conjunto de datos de muestra para consultar, de modo que pueda familiarizarse con la herramienta antes de conectarla a su inquilino de producción. En la Figura 2, vemos los resultados de Graph Explorer para el punto final manager del usuario AdeleV.
Los resultados de las consultas de Graph se devuelven en formato JSON, que es lo suficientemente flexible como para tener en cuenta diferentes tipos de valores y objetos anidados.
Otra cosa a considerar al utilizar las API Graph son los permisos necesarios para cada punto final y operación que ejecute. Para leer más sobre los permisos en la API de Microsoft Graph, consulte este artículo sobre Cómo determinar qué permisos de Microsoft Graph necesita.
¿Cómo ayuda el SDK de PowerShell?
Trabajar con Graph API es un concepto nuevo para muchos administradores de inquilinos y existe una curva de aprendizaje que dominar. El SDK de PowerShell es una forma para que los administradores que se sienten más cómodos con PowerShell utilicen Graph sin preocuparse por detalles específicos, como tokens de autenticación y solicitudes de formato.
Para ello, el SDK proporciona cmdlets de PowerShell que emiten las llamadas de Graph en su nombre. Por ejemplo, en la Figura 3, vemos que el cmdlet Get-MgGroup del SDK de PowerShell emite una solicitud GET al punto final https://graph.microsoft.com/v1.0/groups . Si bien es posible enviar esta solicitud directamente mediante Invoke-WebRequest, tener un conjunto más familiar de cmdlets y parámetros simplifica significativamente el trabajo con Graph.
Al crear nuevos objetos o actualizar objetos existentes a través de Graph, se requiere una carga útil JSON para definir los parámetros del objeto nuevo o actualizado. Esta carga útil sigue un esquema predefinido para cada tipo de objeto que puede resultar complicado de lograr. Los cmdlets del SDK dan formato a la carga útil automáticamente según los parámetros del cmdlet. Por ejemplo, en la Figura 4, el cmdlet New-MgUser pasa los datos JSON requeridos por Graph API para crear un nuevo usuario.
El uso del parámetro -Debug para los cmdlets del SDK de Microsoft Graph PowerShell es una buena manera de obtener visibilidad de lo que hace el SDK en segundo plano y ver las solicitudes que se envían a la API Graph.
Gestión de riesgos de ciberseguridad para Active Directory
Descubra cómo prevenir y recuperarse de ataques AD a través de estas soluciones de gestión de riesgos de ciberseguridad.
Instalación del SDK de PowerShell
El SDK de Microsoft Graph PowerShell está disponible en la Galería de PowerShell. Para instalar el SDK, se debe registrar el repositorio de PSGallery; sin él, la instalación fallará como se muestra en la Figura 5. Para registrar el repositorio si falta, ejecute el cmdlet Register-PSRepository -Default, y la instalación debería funcionar.
Una vez instalado el SDK, hay 39 módulos nuevos disponibles (el recuento es correcto al momento de escribir este artículo).
Actualizar el SDK es relativamente sencillo ejecutando el cmdlet Update-Module Microsoft.Graph como administrador y reiniciando PowerShell. El SDK se actualiza mensualmente y es importante utilizar la última versión.
Usando la automatización de Azure
La automatización es un factor clave para PowerShell. La automatización de tareas suele ser crucial para el funcionamiento diario de un inquilino de Microsoft 365, ya que permite a los administradores centrarse en agregar valor en otros lugares. Si bien el SDK se ejecuta perfectamente como una tarea programada desde un servidor Windows, Azure Automation agrega un nivel adicional de seguridad y disponibilidad a las tareas automatizadas.
Este artículo sobre el uso del SDK de Microsoft Graph para PowerShell con Azure Automation explica los requisitos para que el SDK de Graph se ejecute en Azure Automation.
Permisos delegados versus permisos de aplicación
Microsoft Graph admite dos tipos de permisos, Delegados y Aplicación. En un nivel alto, los permisos delegados se ejecutan como si un usuario estuviera presente y generalmente requieren que el usuario se autentique y recupere un token de acceso de forma interactiva. Los permisos delegados se utilizan a menudo para aplicaciones cliente que se conectan a Graph en nombre de los usuarios finales y son el método predeterminado para PowerShell SDK y Graph Explorer. Las aplicaciones que utilizan permisos delegados están limitadas a los permisos disponibles para el usuario que ha iniciado sesión, por lo que un usuario no administrador que utiliza el SDK solo puede realizar tareas para las que su cuenta tiene permiso.
Los permisos de aplicación se ejecutan como un registro de aplicación y admiten autenticación no interactiva. Los permisos de aplicaciones generalmente se usan para tareas automatizadas o aplicaciones que no pueden usar autenticación interactiva. La configuración de permisos de aplicaciones para Graph SDK requiere el uso de una aplicación registrada en Azure AD. Como los permisos de la aplicación no se ejecutan como el usuario actual, no están sujetos a las restricciones de permisos que sí lo están los permisos delegados. Tenga cuidado al utilizar permisos de aplicaciones, especialmente cuando se trata de almacenar el secreto o certificado del cliente.
Otra consideración a la hora de elegir entre permisos delegados y de aplicación es la funcionalidad. Hay tareas en Microsoft 365 que debe realizar un usuario. Por ejemplo, este artículo sobre la creación de un nuevo grupo de Microsoft 365 con el SDK de Microsoft PowerShell Graph muestra cómo configurar un grupo de Microsoft 365 y asignar una etiqueta de confidencialidad, y esto funciona bien con permisos delegados. Intentar hacer lo mismo con los permisos de la aplicación falla porque no es compatible con un token de solo aplicación (Figura 6).
Hay muchos matices como este que afectan el tipo de permisos necesarios. Es importante al planificar su código verificar la documentación para identificar dónde puede encontrar un problema.
Conexión a Graph usando el SDK
Existen varias formas de conectarse a Graph API mediante el SDK, según cómo desee utilizar los cmdlets. Los escenarios más comunes para conectarse son:
- Conéctese interactivamente con permisos delegados
- Conéctese de forma no interactiva con permisos de aplicaciones y un certificado
- Conéctese de forma no interactiva con permisos de aplicaciones y un secreto de cliente
- Conéctese mediante Azure Automation y una identidad administrada
Conectarse con permisos delegados es probablemente el primer método que la gente probará y el más fácil de realizar. Al ejecutar el cmdlet Connect-MgGraph y especificar los ámbitos que desea, se le solicitará el inicio de sesión y el consentimiento a la aplicación Microsoft Graph PowerShell, como se muestra en la Figura 7.
El uso de permisos de la aplicación Graph con un script requiere una aplicación de Azure AD registrada con consentimiento para usar los permisos necesarios. No voy a repasar la creación de un registro de aplicación aquí, ya que se ha discutido muchas veces (como en este artículo sobre cómo completar previamente los contactos de Outlook con Graph API), pero con un registro de aplicación implementado, Connect-MgGraph El cmdlet acepta los parámetros Certificado de cliente o Token de acceso.
Usar el Certificado de cliente como se muestra en este artículo sobre Uso de la autenticación basada en certificados con el SDK de PowerShell de Microsoft Graph es una excelente manera de automatizar tareas con el SDK de PowerShell de forma segura (siempre que se asegure de almacenar el certificado). en una ubicación segura como Azure Key Vault).
Para utilizar un secreto de cliente, primero debe obtener un token de acceso. Existen varios métodos para obtener un token de acceso para Graph API, pero un método sencillo es utilizar el módulo PowerShell de la biblioteca de autenticación de Microsoft (MSAL.PS), como se menciona en este artículo sobre el uso de Azure Automation para procesar datos de Exchange Online con PowerShell.
La Figura 8 muestra ambos métodos en acción.
Usar el SDK de Microsoft Graph para PowerShell con Azure Automation es una buena manera de automatizar scripts complejos o de larga duración. El SDK de Microsoft Graph también puede usar identidades administradas a través de Azure Automation, asignando permisos a la entidad de servicio de la identidad administrada y poniéndolos a disposición directamente de la cuenta de Automation.
Resumen
En este artículo, explico cómo el SDK de Microsoft Graph PowerShell simplifica la administración de Microsoft 365 a través de la API de Microsoft Graph. También muestro cómo conectarse a Graph usando el SDK en una variedad de escenarios. Conectarse y comprender los requisitos al trabajar con Graph es el primer gran desafío que enfrentan muchos administradores al intentar actualizar su código.
En la segunda parte de esta serie, profundizaremos en el uso de Microsoft Graph a través del SDK y veremos algunos ejemplos de dónde puede ahorrarle tiempo y esfuerzo mediante la automatización y el procesamiento masivo.