microsoft-graph-helpers 0.2.0

Helper functions for interacting with Microsoft Graph API

Microsoft Graph Helpers

A lightweight Python module for calling selected Microsoft Graph endpoints. This is not intended to replace Microsoft’s official SDKs. It exists to provide small, focused helpers for scripts and applets that only need a handful of Graph calls without pulling in a large dependency chain.

The module is not comprehensive. It only contains functions that I’ve needed in other internal utilities.

Design Goals

• Minimal dependencies
• Script-friendly usage
• Straightforward authentication model
• Thin wrappers over common Graph endpoints

Authentication is handled using bearer tokens. Most functions expect a valid Microsoft Graph access token with the appropriate delegated or application permissions already granted. Application tokens can be generated using api_token.get_bearer_token(tenant_id, client_id, client_secret)

Module Overview

core.py

Contains shared helper utilities used by other modules. This includes common request handling, header construction, and small abstractions to keep the endpoint-specific modules simple.

api_token.py

get_bearer_token(tenant_id, client_id, secret, ...)
Obtains a Microsoft Graph bearer token and stores it in an in-memory cache for reuse during runtime. Intended for short-lived scripts where persisting tokens beyond process lifetime is unnecessary.

app.py

get_app_secret_expiration(token, secret_id)
Retrieves the expiration date for a specific application secret (credential) by its SECRET_ID.

Useful for:

• Monitoring expiring client secrets
• Alerting workflows
• Administrative audits

Requires appropriate application permissions such as Application.Read.All.

email.py

send_message_as(token, user_principal_name, subject, body, ...)
Sends an email as the specified user. Intended for service or automation accounts where delegated permissions have been granted.

retrieve_message(token, message_id)
Retrieves message metadata by searching sequentially through the following mail stores:

• Messages
• DeletedItems
• RecoverableItemsDeletions
• RecoverableItemsPurges
• RecoverableItemsDiscoveryHolds

This is useful in investigations where a message may have been deleted or moved and its current location is unknown.

groups.py

get_group_guid(token, display_name)
RReturns the GUID of a group given its display name. Useful when scripts need to convert human-readable names into object IDs for subsequent calls.

get_group_members(token, group_guid)
Retrieves all members of a group using its GUID. Handles member enumeration through Graph.

security.py

run_hunting_query(token, kql_query)
Executes a KQL hunting query through Microsoft Graph security endpoints and returns the results. Intended for Microsoft Defender hunting scenarios and scripted investigations.

users.py

verify_user_exists(token, user_principal_name)
Confirms whether a user exists in the directory.

revoke_ms_sessions(token, user_principal_name)
Revokes active sign-in sessions for the specified user. Useful in account compromise response workflows.

reset_ms_password(token, user_principal_name, new_password, ...)
Resets a user’s password. Requires appropriate directory permissions.

get_user_direct_group_memberships(token, user_principal_name) Retrieves groups that the user is directly a member of (non-transitive).

Authentication and Permissions

Most functions require a valid Microsoft Graph access token with sufficient permissions granted in Azure AD / Entra ID. Common permission scopes used by these helpers may include:

• Application.Read.All
• Directory.Read.All
• Mail.Send
• User.ReadWrite.All
• Group.Read.All
• SecurityEvents.Read.All

The required scope depends on the specific function being called.

Example Usage

from microsoft_graph_helpers.api_token import get_bearer_token
from microsoft_graph_helpers.users import verify_user_exists

token = get_bearer_token(...)
exists = verify_user_exists(token, "[e-mail]")

print(exists)

Intended Use

This module is designed for:

• Administrative scripts
• Incident response tooling
• Scheduled automation tasks
• Small internal utilities

It is not a full SDK and does not attempt to wrap every Graph endpoint.