Compilación de aplicaciones de Python con Microsoft Graph y autenticación solo de aplicaciones

En este tutorial se explica cómo crear una aplicación de consola de Python 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.

En este tutorial, aprenderá a:

• Enumerar usuarios

Requisitos previos

Antes de iniciar este tutorial, debe tener Python y pip instalados en la máquina de desarrollo.

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.

Registrar la aplicación en el portal

• 18 minutos restantes

En este ejercicio registrará una nueva aplicación en Azure Active Directory para habilitar la autenticación de solo aplicación. Puede registrar una aplicación mediante el Centro de administración de Microsoft Entra o mediante el SDK de PowerShell de Microsoft Graph.

Registro de la aplicación para la autenticación de solo aplicación

En esta sección registrará una aplicación que admita la autenticación de solo aplicación mediante el flujo de credenciales de cliente.

Creación de una aplicación de consola de Python

• 15 minutos restantes

Empiece por crear un nuevo archivo de Python.

1. Cree un nuevo archivo denominado main.py y agregue el código siguiente.

   print ('Hello world!')
   

2. Guarde el archivo y use el siguiente comando para ejecutar el archivo.

   python3 main.py
   

   Si funciona, la aplicación debe generar Hello world!.

Instalar dependencias

Antes de continuar, agregue algunas dependencias adicionales que usará más adelante.

• Biblioteca cliente de Identidad de Azure para Python para autenticar al usuario y adquirir tokens de acceso.
• SDK de Microsoft Graph para Python (versión preliminar) para realizar llamadas a Microsoft Graph.

Ejecute los siguientes comandos en la CLI para instalar las dependencias.

python3 -m pip install azure-identity
python3 -m pip install msgraph-sdk

Cargar la configuración de la aplicación

En esta sección agregará los detalles del registro de la aplicación al proyecto.

1. Cree un archivo en el mismo directorio que main.py denominado config.cfg y agregue el código siguiente.

   [azure]
   clientId = YOUR_CLIENT_ID_HERE
   clientSecret = YOUR_CLIENT_SECRET_HERE
   tenantId = YOUR_TENANT_ID_HERE
   

2. Actualice los valores según la tabla siguiente.

   Configuración	Valor
   clientId	El identificador de cliente del registro de la aplicación
   clientSecret	El secreto de cliente del registro de la aplicación
   tenantId	El identificador de inquilino de la organización

   Sugerencia

   Opcionalmente, puede establecer estos valores en un archivo independiente denominado config.dev.cfg.

Diseñar la aplicación

En esta sección creará un menú simple basado en consola.

1. Cree un nuevo archivo denominado graph.py y agregue el código siguiente a ese archivo.

   # Temporary placeholder
   class Graph:
       def __init__(self, config):
           self.settings = config
   

   Este código es un marcador de posición. Implementará la Graph clase en la sección siguiente.

2. Abra main.py y reemplace todo su contenido por el código siguiente.

   import asyncio
   import configparser
   from msgraph.generated.models.o_data_errors.o_data_error import ODataError
   from graph import Graph
   
   async def main():
       print('Python Graph App-Only Tutorial\n')
   
       # Load settings
       config = configparser.ConfigParser()
       config.read(['config.cfg', 'config.dev.cfg'])
       azure_settings = config['azure']
   
       graph: Graph = Graph(azure_settings)
   
       choice = -1
   
       while choice != 0:
           print('Please choose one of the following options:')
           print('0. Exit')
           print('1. Display access token')
           print('2. List users')
           print('3. Make a Graph call')
   
           try:
               choice = int(input())
           except ValueError:
               choice = -1
   
           try:
               if choice == 0:
                   print('Goodbye...')
               elif choice == 1:
                   await display_access_token(graph)
               elif choice == 2:
                   await list_users(graph)
               elif choice == 3:
                   await make_graph_call(graph)
               else:
                   print('Invalid choice!\n')
           except ODataError as odata_error:
               print('Error:')
               if odata_error.error:
                   print(odata_error.error.code, odata_error.error.message)
   

3. Agregue los siguientes métodos de marcador de posición al final del archivo. Los implementará en pasos posteriores.

   async def display_access_token(graph: Graph):
       # TODO
       return
   
   async def list_users(graph: Graph):
       # TODO
       return
   
   async def make_graph_call(graph: Graph):
       # TODO
       return
   

4. Agregue la siguiente línea para llamar main al final del archivo.

   # Run main
   asyncio.run(main())
   

Esto implementa un menú básico y lee la elección del usuario desde la línea de comandos.

Agregar autenticación de solo aplicación

• 10 minutos restantes

En esta sección agregará la autenticación de solo aplicación a la aplicación. Esto es necesario para obtener el token de acceso de OAuth necesario para llamar a Microsoft Graph. En este paso, integrará la biblioteca cliente de Azure Identity para Python en la aplicación y configurará la autenticación para el SDK de Microsoft Graph para Python (versión preliminar).

La biblioteca de identidades de Azure proporciona varias clases que implementan flujos de TokenCredential token de OAuth2. El SDK de Microsoft Graph usa esas clases para autenticar llamadas a Microsoft Graph.

Configuración del cliente de Graph para la autenticación solo de la aplicación

En esta sección usará la ClientSecretCredential clase para solicitar un token de acceso mediante el flujo de credenciales de cliente.

1. Abra graph.py y reemplace todo su contenido por el código siguiente.

   from configparser import SectionProxy
   from azure.identity.aio import ClientSecretCredential
   from msgraph import GraphServiceClient
   from msgraph.generated.users.users_request_builder import UsersRequestBuilder
   
   class Graph:
       settings: SectionProxy
       client_credential: ClientSecretCredential
       app_client: GraphServiceClient
   
       def __init__(self, config: SectionProxy):
           self.settings = config
           client_id = self.settings['clientId']
           tenant_id = self.settings['tenantId']
           client_secret = self.settings['clientSecret']
   
           self.client_credential = ClientSecretCredential(tenant_id, client_id, client_secret)
           self.app_client = GraphServiceClient(self.client_credential) # type: ignore
   

   Este código declara dos propiedades privadas, un ClientSecretCredential objeto y un GraphServiceClient objeto . La __init__ función crea una nueva instancia de ClientSecretCredentialy, a continuación, usa esa instancia para crear una nueva instancia de GraphServiceClient. Cada vez que se realiza una llamada API a Microsoft Graph a través de app_client, usará la credencial proporcionada para obtener un token de acceso.

2. Agregue la siguiente función a graph.py.

   async def get_app_only_token(self):
       graph_scope = 'https://graph.microsoft.com/.default'
       access_token = await self.client_credential.get_token(graph_scope)
       return access_token.token
   

3. Reemplace la función vacía display_access_token de main.py por lo siguiente.

   async def display_access_token(graph: Graph):
       token = await graph.get_app_only_token()
       print('App-only token:', token, '\n')
   

4. Compile y ejecute la aplicación. Escriba 1 cuando se le solicite una opción. La aplicación muestra un token de acceso.

   Python Graph App-Only Tutorial
   
   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List users
   3. Make a Graph call
   1
   App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
   

   Sugerencia

   Solo con fines de validación y depuración, puede descodificar tokens de acceso de solo aplicación mediante el analizador de tokens en línea de Microsoft en https://jwt.ms. Esto puede ser útil si encuentra errores de token al llamar a Microsoft Graph. Por ejemplo, comprobar que la role notificación del token contiene los ámbitos de permiso de Microsoft Graph esperados.

List users

• 7 minutos restantes

En esta sección agregará la capacidad de enumerar todos los usuarios de Azure Active Directory mediante la autenticación de solo aplicación.

1. Agregue la siguiente función a graph.py.

   async def get_users(self):
       query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
           # Only request specific properties
           select = ['displayName', 'id', 'mail'],
           # Get at most 25 results
           top = 25,
           # Sort by display name
           orderby= ['displayName']
       )
       request_config = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
           query_parameters=query_params
       )
   
       users = await self.app_client.users.get(request_configuration=request_config)
       return users
   

2. Reemplace la función vacía list_users de main.py por lo siguiente.

   async def list_users(graph: Graph):
       users_page = await graph.get_users()
   
       # Output each users's details
       if users_page and users_page.value:
           for user in users_page.value:
               print('User:', user.display_name)
               print('  ID:', user.id)
               print('  Email:', user.mail)
   
           # If @odata.nextLink is present
           more_available = users_page.odata_next_link is not None
           print('\nMore users available?', more_available, '\n')
   

3. Ejecute la aplicación y elija la opción 2 para enumerar a los usuarios.

   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List users
   3. Make a Graph call
   2
   User: Adele Vance
     ID: 05fb57bf-2653-4396-846d-2f210a91d9cf
     Email: AdeleV@contoso.com
   User: Alex Wilber
     ID: a36fe267-a437-4d24-b39e-7344774d606c
     Email: AlexW@contoso.com
   User: Allan Deyoung
     ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0
     Email: AllanD@contoso.com
   User: Bianca Pisani
     ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49
     Email: None
   User: Brian Johnson (TAILSPIN)
     ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4
     Email: BrianJ@contoso.com
   
   ...
   
   More users available? True
   

Código explicado

Tenga en cuenta el código de la get_users función .

• Obtiene una colección de usuarios
• $select Usa para solicitar propiedades específicas
• $top Usa para limitar el número de usuarios devueltos
• $orderBy Usa para ordenar la respuesta

Opcional: agregue su propio código

• 5 minutos restantes

En esta sección agregará sus propias funcionalidades de Microsoft Graph a la aplicación. 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.

Actualizar la aplicación

1. Agregue la siguiente función a graph.py.

   async def make_graph_call(self):
       # INSERT YOUR CODE HERE
       return
   

2. Reemplace la función vacía list_inbox de main.py por lo siguiente.

   async def make_graph_call(graph: Graph):
       await graph.make_graph_call()
   

Elección de una API

Busque una API en Microsoft Graph que le gustaría probar. Por ejemplo, create event API. Puede usar uno de los ejemplos de la documentación de la API o crear su propia solicitud de API.

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 ni cuentas personales de Microsoft, por ejemplo.

• Para llamar a una API con autenticación de usuario (si la API admite la autenticación de usuario (delegado), consulte el tutorial de autenticación de usuario (delegado ).
• 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.

Agregar el código

Copie el código en la make_graph_call función de graph.py.

¡Enhorabuena!

• 100 % completado.

Ha completado el tutorial de Microsoft Graph de Python. 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 Python de Microsoft Graph.
• Visite información general de Microsoft Graph para ver todos los datos a los que puede acceder con Microsoft Graph.

Ejemplos de Python

• Aplicación web de Django
• Ejemplo de API de seguridad