msgraph-py

Description

This package contains API wrappers to simplify interaction with Microsoft Graph API through Python functions.

Some of the benefits of msgraph-py are:

• Automatic caching and renewal of access tokens, avoiding unnecessary API-calls.
• Sets the correct headers and parameters for you when required (advanced queries).
• Pages results automatically when retrieving large datasets.
• Useful logging and error messages with the Python logging module.
• Optional integration with Django settings.py for reading environment variables.

Note

The latest published version of this package can be found at pypi.org/project/msgraph-py

List of available functions

Identity

• get_user()
• get_user_risk()
• revoke_refresh_tokens()
• list_auth_methods()
• delete_auth_method()
• reset_strong_auth()
• get_signin()

Groups

• get_group()
• list_group_members()
• add_group_member()
• remove_group_member()

Devices

• get_device()
• delete_device()
• list_owned_devices()
• get_laps_password()

Mail

• send_mail()

Getting Started

1. Create an app registration in Entra ID with the necessary Graph application permissions for the functions you intend to use:
   Authentication and authorization steps

2. Install the latest version of the package:

   python3 -m pip install msgraph-py

3. Configure environment variables:

   • If used within a Django project, msgraph-py will by default first attempt to load the following variables from the project's settings.py:

     # project/settings.py
     
     AAD_TENANT_ID = "00000000-0000-0000-0000-000000000000"
     AAD_CLIENT_ID = "00000000-0000-0000-0000-000000000000"
     AAD_CLIENT_SECRET = "client-secret-value"

   • Alternatively you will need to set the following key-value pairs in os.environ:

     import os
     
     os.environ["AAD_TENANT_ID"] = "00000000-0000-0000-0000-000000000000"
     os.environ["AAD_CLIENT_ID"] = "00000000-0000-0000-0000-000000000000"
     os.environ["AAD_CLIENT_SECRET"] = "client-secret-value"

Warning

You should never store sensitive credentials or secrets in production code or commit them to your repository. Always load them at runtime from a secure location or from a local file excluded from the repository.

Usage examples

Get a single user by objectId or userPrincipalName

from msgraph import get_user

user = get_user("user@example.com")

List of returned properties for user resource type.

Get a list of users using advanced query parameters

from msgraph import get_user

filtered_users = get_user(
    filter="startsWith(department, 'sales')",
    select=[
        "displayName",
        "department",
        "createdDateTime",
    ],
    orderby="createdDateTime desc",
    all=True,
)

List of returned properties for user resource type.

Get a users Entra ID joined devices

from msgraph import list_owned_devices

user_devices = list_owned_devices(
    user_id="user@example.com",
    filter="isManaged eq true and trustType eq 'AzureAd'",
    select=[
        "deviceId",
        "displayName",
        "isCompliant",
        "approximateLastSignInDateTime",
    ],
    orderby="approximateLastSignInDateTime desc",
)

List of returned properties for device resource type.

Send an e-mail with attachments

from msgraph import send_mail

send_mail(
    sender_id="noreply@example.com",
    recipients=[
        "john.doe@example.com",
        "jane.doe@example.com",
    ],
    subject="Mail from Graph API",
    body="<h1>Content of the mail body</h1>",
    is_html=True,
    priority="high",
    attachments=[
        "/path/to/file1.txt",
        "/path/to/file2.txt",
    ],
)

API documentation

• Authentication and authorization basics
• Use query parameters to customize responses
• Microsoft Entra authentication methods API overview

Resource types and properties

• authenticationMethod resource type
• device resource type
• directoryObject resource type
• group resource type
• riskyUser resource type
• signIn resource type
• user resource type