Build Python apps with Microsoft Graph and app-only authentication

This tutorial teaches you how to build a Python console app that uses the Microsoft Graph API to access data using app-only authentication. App-only authentication is a good choice for background services or applications that need to access data for all users in an organization.

In this tutorial, you will:

• List users

Prerequisites

Before you start this tutorial, you should have Python and pip installed on your development machine.

You should also have a Microsoft work or school account with the Global administrator role. If you don't have a Microsoft 365 tenant, you might qualify for one through the Microsoft 365 Developer Program; for details, see the FAQ. Alternatively, you can sign up for a 1-month free trial or purchase a Microsoft 365 plan.

Register the app in the portal

• 18 minutes remaining

In this exercise you will register a new application in Azure Active Directory to enable app-only authentication. You can register an application using the Microsoft Entra admin center, or by using the Microsoft Graph PowerShell SDK.

Register application for app-only authentication

In this section you will register an application that supports app-only authentication using client credentials flow.

Create a Python console app

• 15 minutes remaining

Begin by creating a new Python file.

1. Create a new file named main.py and add the following code.

   print ('Hello world!')
   

2. Save the file and use the following command to run the file.

   python3 main.py
   

   If it works, the app should output Hello world!.

Install dependencies

Before moving on, add some additional dependencies that you will use later.

• Azure Identity client library for Python to authenticate the user and acquire access tokens.
• Microsoft Graph SDK for Python (preview) to make calls to the Microsoft Graph.

Run the following commands in your CLI to install the dependencies.

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

Load application settings

In this section you'll add the details of your app registration to the project.

1. Create a file in the same directory as main.py named config.cfg and add the following code.

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

2. Update the values according to the following table.

   Setting	Value
   clientId	The client ID of your app registration
   clientSecret	The client secret of your app registration
   tenantId	The tenant ID of your organization

   Tip

   Optionally, you can set these values in a separate file named config.dev.cfg.

Design the app

In this section you will create a simple console-based menu.

1. Create a new file named graph.py and add the following code to that file.

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

   This code is a placeholder. You will implement the Graph class in the next section.

2. Open main.py and replace its entire contents with the following code.

   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. Add the following placeholder methods at the end of the file. You'll implement them in later steps.

   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. Add the following line to call main at the end of the file.

   # Run main
   asyncio.run(main())
   

This implements a basic menu and reads the user's choice from the command line.

Add app-only authentication

• 10 minutes remaining

In this section you will add app-only authentication to the application. This is required to obtain the necessary OAuth access token to call the Microsoft Graph. In this step you will integrate the Azure Identity client library for Python into the application and configure authentication for the Microsoft Graph SDK for Python (preview).

The Azure Identity library provides a number of TokenCredential classes that implement OAuth2 token flows. The Microsoft Graph SDK uses those classes to authenticate calls to Microsoft Graph.

Configure Graph client for app-only authentication

In this section you will use the ClientSecretCredential class to request an access token by using the client credentials flow.

1. Open graph.py and replace its entire contents with the following code.

   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
   

   This code declares two private properties, an ClientSecretCredential object and a GraphServiceClient object. The __init__ function creates a new instance of ClientSecretCredential, then uses that instance to create a new instance of GraphServiceClient. Every time an API call is made to Microsoft Graph through the app_client, it will use the provided credential to get an access token.

2. Add the following function to 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. Replace the empty display_access_token function in main.py with the following.

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

4. Build and run the app. Enter 1 when prompted for an option. The application displays an access token.

   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...
   

   Tip

   For validation and debugging purposes only, you can decode app-only access tokens using Microsoft's online token parser at https://jwt.ms. This can be useful if you encounter token errors when calling Microsoft Graph. For example, verifying that the role claim in the token contains the expected Microsoft Graph permission scopes.

List users

• 7 minutes remaining

In this section you will add the ability to list all users in your Azure Active Directory using app-only authentication.

1. Add the following function to 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. Replace the empty list_users function in main.py with the following.

   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. Run the app and choose option 2 to list users.

   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: [email protected]
   User: Alex Wilber
     ID: a36fe267-a437-4d24-b39e-7344774d606c
     Email: [email protected]
   User: Allan Deyoung
     ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0
     Email: [email protected]
   User: Bianca Pisani
     ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49
     Email: None
   User: Brian Johnson (TAILSPIN)
     ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4
     Email: [email protected]
   
   ...
   
   More users available? True
   

Code explained

Consider the code in the get_users function.

• It gets a collection of users
• It uses $select to request specific properties
• It uses $top to limit the number of users returned
• It uses $orderBy to sort the response

Optional: add your own code

• 5 minutes remaining

In this section you will add your own Microsoft Graph capabilities to the application. This could be a code snippet from Microsoft Graph documentation or Graph Explorer, or code that you created. This section is optional.

Update the app

1. Add the following function to graph.py.

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

2. Replace the empty list_inbox function in main.py with the following.

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

Choose an API

Find an API in Microsoft Graph you'd like to try. For example, the Create event API. You can use one of the examples in the API documentation, or create your own API request.

Configure permissions

Check the Permissions section of the reference documentation for your chosen API to see which authentication methods are supported. Some APIs don't support app-only, or personal Microsoft accounts, for example.

• To call an API with user authentication (if the API supports user (delegated) authentication), see the user (delegated) authentication tutorial.
• To call an API with app-only authentication (if the API supports it), add the required permission scope in the Azure AD admin center.

Add your code

Copy your code into the make_graph_call function in graph.py.

Congratulations!

• 100% complete!

You've completed the Python Microsoft Graph tutorial. Now that you have a working app that calls Microsoft Graph, you can experiment and add new features.

• Learn how to use user (delegated) authentication with the Microsoft Graph Python SDK.
• Visit the Overview of Microsoft Graph to see all of the data you can access with Microsoft Graph.

Python samples

• Django web app
• Security API sample