Compilación de scripts de PowerShell con Microsoft Graph y autenticación solo de aplicación
En este tutorial se explica cómo crear un script de PowerShell que use Microsoft Graph API para acceder a los datos mediante la autenticación de solo aplicación. La autenticación solo de aplicación es una buena opción para los servicios en segundo plano o las aplicaciones que necesitan acceder a los datos de todos los usuarios de una organización.
Nota:
Para obtener información sobre cómo usar Microsoft Graph para acceder a datos en nombre de un usuario, consulte este tutorial de autenticación de usuario (delegado).
En este tutorial, aprenderá a:
Sugerencia
Como alternativa a seguir este tutorial, puede descargar o clonar el repositorio de GitHub y seguir las instrucciones de README para registrar una aplicación y configurar el proyecto.
Requisitos previos
Antes de iniciar este tutorial, debe tener PowerShell instalado en la máquina de desarrollo. PowerShell 5.1 es el requisito mínimo, pero se recomienda PowerShell 7.
También debe tener una cuenta profesional o educativa de Microsoft con el rol de administrador global. Si no tiene un inquilino de Microsoft 365, puede calificar para uno a través del Programa para desarrolladores de Microsoft 365; Para obtener más información, consulte las preguntas más frecuentes. Como alternativa, puede registrarse para obtener una evaluación gratuita de 1 mes o comprar un plan de Microsoft 365.
Nota:
Este tutorial se ha escrito con PowerShell 7.2.2 y el SDK de PowerShell de Microsoft Graph, versión 1.9.5. Los pasos de esta guía pueden funcionar con otras versiones, pero no se han probado.
Registrar la aplicación en el portal
En este ejercicio registrará una nueva aplicación en Microsoft Entra para habilitar la autenticación de solo aplicación.
Creación de un certificado autofirmado
El SDK de PowerShell de Microsoft Graph requiere un certificado para la autenticación de solo aplicación. Con fines de desarrollo, basta con un certificado autofirmado. Necesita un certificado con la clave privada instalada en el equipo local y la clave pública exportada en . CER, . PEM o . Archivo CRT.
En Windows, puede usar el módulo de PowerShell pki para generar el certificado.
$cert = New-SelfSignedCertificate -Subject "CN=PowerShell App-Only" -CertStoreLocation `
"Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 `
-KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "./PowerShellAppOnly.cer"
Registro de la aplicación para la autenticación de solo aplicación
En esta sección registrará una aplicación que admitirá la autenticación de solo aplicación mediante el flujo de credenciales de cliente.
Abra un explorador y vaya al Centro de administración de Microsoft Entra e inicie sesión con una cuenta de administrador global.
Seleccione Microsoft Entra ID en el panel de navegación izquierdo, expanda Identidad, aplicaciones y registros de aplicaciones.
Seleccione Nuevo registro. Escriba un nombre para la aplicación, por ejemplo,
Graph App-Only Auth Tutorial.Establezca Tipos de cuenta admitidosen Solo cuentas en este directorio organizativo.
Deje URI de redireccionamiento vacía.
Seleccione Registrar. En la página Información general de la aplicación, copie el valor del identificador de aplicación (cliente) y del identificador de directorio (inquilino) y guárdelos, necesitará estos valores en el paso siguiente.
Seleccione Permisos de las API en Administrar.
Quite el permiso User.Read predeterminado en Permisos configurados ; para ello, seleccione los puntos suspensivos (...) de su fila y seleccione Quitar permiso.
Seleccione Agregar un permiso y, a continuación, Microsoft Graph.
Seleccione Permisos de aplicación.
Seleccione User.Read.All y, a continuación, seleccione Agregar permisos.
Seleccione Conceder consentimiento de administrador para...y, a continuación, seleccione Sí para proporcionar el consentimiento del administrador para el permiso seleccionado.
Seleccione Certificados y secretos en Administrar y, a continuación, seleccione Certificados.
Seleccione Cargar certificado. Cargue el archivo PowerShellAppOnly.cer o powershell.crt que creó en el paso anterior y, a continuación, seleccione Agregar.
Nota:
Tenga en cuenta que, a diferencia de los pasos al registrarse para la autenticación de usuario, en esta sección configuró los permisos de Microsoft Graph en el registro de la aplicación. Esto se debe a que la autenticación de solo aplicación usa el flujo de credenciales de cliente, lo que requiere que los permisos se configuren en el registro de la aplicación. Consulte El ámbito .default para obtener más información.
Agregar autenticación de solo aplicación
En esta sección usará la autenticación de solo aplicación con el SDK de PowerShell de Microsoft Graph.
Conexión con la autenticación de solo aplicación
Desconecte cualquier conexión existente de Microsoft Graph mediante el siguiente comando.
Disconnect-MgGraphAbra PowerShell y use el siguiente comando para establecer la
$clientIDvariable de sesión, reemplazando <your-client-id> por el identificador de cliente del registro de la aplicación.$clientId = <your-client-id>Establezca la variable de
$tenantIdsesión y reemplace <your-tenant-id> por el identificador de inquilino de la organización.$tenantId = <your-tenant-id>Establezca la
$certificatevariable de sesión en el asunto del certificado creado en el paso anterior.$certificate = "CN=PowerShell App-Only"Use el
Connect-MgGraphcomando para autenticarse mediante el certificado del paso anterior.Connect-MgGraph -ClientId $clientId -TenantId $tenantId -CertificateName $certificateUse
Get-MgContextpara comprobar que está autenticado con la autenticación de solo aplicación. Compruebe que AuthType esAppOnly.PS > Get-MgContext ClientId : 2fb1652f-a9a0-4db9-b220-b224b8d9d38b TenantId : 601faea3-be45-4960-898f-92b379b17cd9 CertificateThumbprint : Scopes : {User.Read.All} AuthType : AppOnly AuthProviderType : ClientCredentialProvider CertificateName : CN=PowerShell App-Only Account : AppName : PowerShell Graph Tutorial ContextScope : Process Certificate : PSHostVersion : 2022.4.1 ClientTimeout : 00:05:00
List users
En esta sección enumerará todos los usuarios de Azure Active Directory mediante la autenticación de solo aplicación.
En la sesión de PowerShell autenticada, ejecute el siguiente comando para enumerar a los usuarios.
Get-MgUser -Select "displayName,id,mail" -Top 25 -OrderBy "displayName"Revise la salida.
Id DisplayName Mail UserPrincipalName UserType -- ----------- ---- ----------------- -------- 05fb57bf-2653-4396-846d-2f210a91d9cf Adele Vance AdeleV@contoso.com a36fe267-a437-4d24-b39e-7344774d606c Alex Wilber AlexW@contoso.com 54cebbaa-2c56-47ec-b878-c8ff309746b0 Allan Deyoung AllanD@contoso.com 9cb2ad7c-8e69-46a6-a947-a02c255048de Automate Bot 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Bianca Pisani a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Brian Johnson (TAILSPIN) BrianJ@contoso.com 9e2d4937-44ee-4af4-bd56-77a12cc3ecc4 Cameron White 8990227d-31dc-4120-a38e-f652576974f4 Christie Cline ChristieC@contoso.com ...
Código explicado
Tenga en cuenta el comando que se usa para enumerar usuarios.
-
-SelectUsa para solicitar propiedades específicas -
-TopUsa para limitar el número de usuarios devueltos -
-OrderByUsa para ordenar la respuesta
Opcional: agregue su propio código
En esta sección usará sus propios comandos del SDK de PowerShell de Microsoft Graph. Podría tratarse de un fragmento de código de la documentación de Microsoft Graph o del Explorador de Graph, o código que haya creado. Esta sección es opcional.
Elección de una API
Busque una API en Microsoft Graph que le gustaría probar. Por ejemplo, la API De lista de grupos . Puede usar uno de los ejemplos de la documentación de la API, personalizar una solicitud de API en el Explorador de Graph y usar el fragmento de código generado o usar el Find-MgGraphCommand comando para buscar el comando correspondiente.
Por ejemplo, el punto de conexión de API para enumerar grupos es GET /groups. Puede usarlo para buscar el comando de PowerShell correspondiente.
PS > Find-MgGraphCommand -Uri "/groups" -Method "GET"
APIVersion: v1.0
Command Module Method URI OutputType Permissions
------- ------ ------ --- ---------- -----------
Get-MgGroup Groups GET /groups IMicrosoftGraphGroup {Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, G…
APIVersion: beta
Command Module Method URI OutputType Permissions
------- ------ ------ --- ---------- -----------
Get-MgGroup Groups GET /groups IMicrosoftGraphGroup1 {Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, …
La salida indica que el Get-MgGroup comando es el comando correspondiente.
Configurar permisos
Compruebe la sección Permisos de la documentación de referencia de la API elegida para ver qué métodos de autenticación se admiten. Algunas API no admiten solo aplicaciones, por ejemplo.
Para llamar a una API con autenticación de solo aplicación (si la API la admite), agregue el ámbito de permisos necesario en el Centro de administración de Azure AD. Asegúrese de desconectarse y volver a conectarse mediante el permiso de solo aplicación.
Sugerencia
El uso del -ForceRefresh parámetro con el Connect-MgGraph comando garantiza que se apliquen los permisos recién configurados.
Ejecución del comando
Ahora que está conectado con los permisos necesarios, ejecute el comando elegido.
¡Enhorabuena!
Ha completado el tutorial de solo aplicación de Microsoft Graph de PowerShell. Ahora que tiene una aplicación en funcionamiento que llama a Microsoft Graph, puede experimentar y agregar nuevas características.
- Obtenga información sobre cómo usar la autenticación de usuario (delegado) con el SDK de PowerShell de Microsoft Graph.
- Visite información general de Microsoft Graph para ver todos los datos a los que puede acceder con Microsoft Graph.
¿Tiene algún problema con esta sección? Si es así, envíenos sus comentarios para que podamos mejorarla.