Uso del SDK de Microsoft Graph para PowerShell con Azure Automation
De los Runbooks al correo electrónico
En un artículo anterior sobre el uso de cuentas y runbooks de Azure Automation con el módulo PowerShell de administración de Exchange Online, en ese artículo también expliqué cómo usar consultas de Graph API en un script de PowerShell ejecutado en un runbook. La siguiente pregunta natural es si el SDK de Microsoft Graph PowerShell admite runbooks. Puedo informar que el SDK se puede usar con Azure Automation mediante autenticación basada en certificados o identidades administradas. Por supuesto, una simple declaración puede ocultar mucha complejidad, así que exploremos los detalles.
Como ejemplo práctico de lo que es posible, en este artículo convierto el script para enviar correo electrónico a nuevos buzones de correo descritos aquí para ejecutarlo en un runbook.
Configuración de automatización de Azure
Como se analizó en el artículo anterior, usaremos una cuenta de Azure Automation (vinculada a una suscripción de Azure) para ejecutar el script en un servidor sandbox. Azure Automation admite identidades administradas y profundizaré en ese tema en un artículo futuro. Por ahora, la técnica probada y comprobada funciona.
Actualización: Azure Automation ya no admite cuentas Runbook. Utilice una identidad administrada en su lugar. Consulte este artículo para obtener más información. Los principios explicados aquí sobre cómo cargar módulos en una cuenta de automatización y asignar permisos Graph a cuentas de automatización siguen siendo válidos.
Importación de módulos de gráficos
La cuenta RunAs tiene una entidad de servicio y un certificado administrado por Azure. Estos son los componentes clave utilizados para la autenticación. Sin embargo, la autenticación es sólo el comienzo. Para que el SDK de Microsoft Graph PowerShell esté disponible para un runbook, debemos importar sus módulos a la cuenta de automatización como recursos compartidos.
Quizás notes que utilicé módulos y no módulos. Cuando descarga el SDK de Microsoft Graph PowerShell de la galería de PowerShell y lo instala en una estación de trabajo, no obtiene ni un solo módulo. En cambio, el SDK se divide en muchos módulos diferentes, cada uno de los cuales se ocupa de una pequeña parte del panorama general de Graph. Cuando importa el SDK a una cuenta de automatización, debe importar los módulos que necesita un script. La primera tarea es verificar la documentación de los cmdlets que planea usar para descubrir en qué módulo se encuentra cada cmdlet.
Por ejemplo, digamos que su script usa el cmdlet Get-MgOrganization para devolver detalles de su inquilino. La documentación de Microsoft nos dice que el cmdlet pertenece al módulo Microsoft.Graph.Identity.DirectoryManagement (Figura 1).
De paso, permítanme decir que la documentación de los cmdlets del SDK es un horrible ejemplo de por qué la inteligencia artificial a veces no funciona tan bien cuando se utiliza para crear documentación basada en el código fuente. Mejorar la documentación ayudaría a las personas a comprender mejor los cmdlets del SDK y fomentaría su uso. Por ahora, se necesita una interpretación sustancial y mucha paciencia.
Carga de módulos SDK en la cuenta de Azure Automation
Después de verificar el script para encontrar todos los cmdlets del SDK, terminé importando cuatro módulos (Figura 2):
- Microsoft.Graph.Authentication: para autenticarse en Graph.
- Microsoft.Graph.Users.Action: para enviar un mensaje.
- Microsoft.Graph.Mail: para acceder a mensajes de correo.
- Microsoft.Graph.Identity.Management: para obtener detalles de la organización.
Asignar permisos de gráficos
Cargar los módulos SDK para interactuar con Graph nos inicia: tener los permisos para hacerlo completa el círculo. Cuando se conecta mediante el cmdlet Connect-MgGraph, la sesión que crea puede utilizar ciertos permisos de Graph. Este es el alcance de la sesión. En este caso, el script necesita acceder al buzón de un usuario para crear un mensaje antes de enviarlo a los destinatarios del mensaje, por lo que la entidad utilizada para la autenticación debe tener el permiso de la aplicación Graph necesario para realizar estas acciones. La entidad es la entidad principal de servicio de la cuenta RunAs. Antes de que el script pueda enviar correo electrónico, un administrador debe otorgar consentimiento para permitir que la entidad de servicio tenga los permisos Mail.Send y Mail.ReadWrite.
Asignar permisos a la entidad de servicio para la cuenta RunAs es lo mismo que asignar permisos a una aplicación registrada. Vaya al centro de administración de Azure AD, busque la entidad de servicio en el conjunto de aplicaciones registradas, agregue los permisos necesarios y otorgue el consentimiento en nombre de la organización. Debería terminar con algo como la Figura 3. Hay dos permisos Graph adicionales porque utilicé esta entidad de servicio en el artículo anterior.
Tenga cuidado de no crear entidades de servicio con demasiados permisos de Graph. Al igual que la entidad de servicio utilizada para sesiones interactivas con el SDK de Microsoft Graph PowerShell, es fácil para una entidad de servicio acumular permisos con el tiempo si se usa para varias tareas. En producción, considere usar cuentas de automatización separadas para diferentes trabajos.
Modificación del código de PowerShell
Ahora tenemos una cuenta RunAs con los permisos correctos y acceso a los módulos necesarios, por lo que es hora de escribir algo de código. Hay un script de trabajo disponible como punto de partida, pero necesita ajustes para funcionar en un runbook. Esto es lo que hice:
Primero, agregué una nueva sección de autenticación para obtener la huella digital del certificado de la cuenta de automatización. Luego, el certificado autentica la conexión a Microsoft Graph.
$Connection = Get-AutomationConnection -Name AzureRunAsConnection
# Get certificate from the automation account
$Certificate = Get-AutomationCertificate -Name AzureRunAsCertificate
# Connect to the Graph SDK endpoint using the automation account
Connect-MgGraph -ClientID $Connection.ApplicationId -TenantId $Connection.TenantId -CertificateThumbprint $Connection.CertificateThumbprint
A continuación, recuperé el dominio de servicio del inquilino y lo utilicé junto con la misma huella digital del certificado para conectarme a Exchange Online (para recuperar el conjunto de buzones agregados recientemente).
$Organization = Get-MgOrganization
$TenantName = $Organization.DisplayName
$TenantDomain = $Organization.Verifieddomains | ? {$_.IsInitial -eq $True} | Select -ExpandProperty Name
# Connect to Exchange Online
Connect-ExchangeOnline –CertificateThumbprint $Connection.CertificateThumbprint –AppId $Connection.ApplicationID –ShowBanner:$false –Organization $TenantDomain
Recuerde que la cuenta de automatización necesita algunos permisos para conectarse a Exchange Online. Esos permisos se describen en mi artículo anterior.
Luego definí de quién es el mensaje (el buzón que quiero usar). Cuando ejecuto el script de forma interactiva, obtengo esta información de la cuenta actualmente conectada a PowerShell, pero esto no funciona para una cuenta RunAs, por lo que debemos definir la dirección SMTP de la cuenta a usar en una variable.
$MsgFrom = "WelcomeNewUsers@Office365itpros.com"Mi secuencia de comandos adjunta una carta de bienvenida almacenada en una unidad local. Obviamente, un script que se ejecuta en un entorno limitado no tiene acceso a mi disco local, por lo que descargo la carta de bienvenida de un sitio web y la almaceno en una carpeta local. Luego, el script codifica el contenido para permitir adjuntar el archivo a un mensaje.
$WebAttachmentFile = "https://office365itpros.com/wp-content/uploads/2022/02/WelcomeToOffice365ITPros.docx"
New-Item -Path c:\TempForScriptxxx -ItemType directory -ErrorAction SilentlyContinue
$AttachmentFile = "c:\TempForScriptxxx\WelcomeNewEmployeeToOffice365itpros.docx"
Invoke-WebRequest -uri $WebAttachmentFile -OutFile $AttachmentFile
$Attachment = (Get-Item -Path $AttachmentFile).Name
$EncodedAttachmentFile = [Convert]::ToBase64String([IO.File]::ReadAllBytes($AttachmentFile))
Finalmente. Eliminé todos los mensajes enviados a la pantalla usando Write-Host. No tiene sentido emitir estos mensajes porque no hay una pantalla en la que mostrarse cuando se ejecuta el código en un runbook.
Los mensajes llegan
Y eso es todo. El proceso no es difícil una vez realizado el trabajo preparatorio. El código se ejecuta porque todos los módulos necesarios están disponibles en la cuenta y la cuenta tiene los permisos Graph correctos, por lo que el correo fluye hacia los buzones de correo de los nuevos usuarios (Figura 4).
Puedes descargar una copia del script completo que utilicé desde GitHub.
La automatización es agradable
Lo bueno de usar Azure Automation es que puede publicar el script y luego programarlo para que se ejecute semanalmente y enviar mensajes de bienvenida a los usuarios que se unieron durante la semana anterior. Con un par de clics, los nuevos miembros reciben oleadas de felicidad. Y la misma técnica de creación y envío de correo electrónico se puede utilizar para distribuir información generada por muchos otros trabajos. ¿No es algo agradable?