msgraph-py

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

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

• Install the latest version of the package:

  python3 -m pip install msgraph-py
  

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

Certificate-based authentication

For improved security, consider migrating to certificate-based authentication instead of a static client secret. The simplest way to do this is using the openssl command to create a self-signed certificate and private key:

hostname=$(hostname -s)
fqdn=$(hostname -f)

openssl req \
    -x509 \
    -newkey rsa:2048 \
    -sha256 \
    -days 3650 \
    -subj "/CN=${fqdn}" \
    -keyout "${hostname}_key.pem" \
    -out "${hostname}_cert.pem" \
    -noenc \
    &> /dev/null

[!NOTE]
Remove the -noenc option if you want to encrypt the private key with a passphrase. Adjust options such as -days and -subj according to your requirements.

Upload the certificate PEM-file to the app registration in Microsoft Entra ID. Make a note of the certificate thumbprint, as we will be needing this in the next step. See Microsofts documentation on adding credentials for more info.

Remove AAD_CLIENT_SECRET from your configuration and set the following environment variables (or settings.py) instead:

os.environ["AAD_PRIVATE_KEY_PATH"] = "path/to/private_key.pem"

# Alternatively pass the key data directly (only PEM-format supported)
os.environ["AAD_PRIVATE_KEY"] = "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----"

# Required if the private key is password-protected
os.environ["AAD_PRIVATE_KEY_PASSPHRASE"] = "key-passphrase-value"

# Required if the private key does not contain a X.509 certificate
os.environ["AAD_CERT_THUMBPRINT"] = "cert-thumbprint-value"

[!NOTE]
You may omit setting AAD_CERT_THUMBPRINT if the certificate and private key are bundled together, as the required thumbprint will be retrieved from the certificate automatically at runtime.

PKCS#12 format (.pfx or .p12) is also supported in addition to PEM when using AAD_PRIVATE_KEY_PATH. In order to convert a PEM-formatted private key and certificate to a single PKCS#12-formatted file, you can use the following command:

openssl pkcs12 -inkey private-key.pem -in certificate.pem -export -out bundled-key-cert.pfx

Usage examples

Get a single user by objectId or userPrincipalName

from msgraph import get_user

user = get_user("[e-mail]")

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="[e-mail]",
    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="[e-mail]",
    recipients=[
        "[e-mail]",
        "[e-mail]",
    ],
    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