Skip to content

[DOCS-13085] Add per-permission rationale and security FAQ to Azure Graph API permissions doc#36337

Open
buraizu wants to merge 1 commit intomasterfrom
docs13085/azure-graph-permissions-transparency
Open

[DOCS-13085] Add per-permission rationale and security FAQ to Azure Graph API permissions doc#36337
buraizu wants to merge 1 commit intomasterfrom
docs13085/azure-graph-permissions-transparency

Conversation

@buraizu
Copy link
Copy Markdown
Contributor

@buraizu buraizu commented Apr 28, 2026

What does this PR do? What is the motivation?

Fixes DOCS-13085

Expands azure-graph-api-permissions.md to address security-team escalations on the Datadog-Azure integration's Microsoft Graph permission requirements. The previous doc listed five required permissions with no rationale, no scoping information, and no statement of what data the integration does not access. Security reviewers (notably regulated-customer security teams) have escalated concerns about Group.Read.All granting access to Microsoft 365 group conversations and shared mailboxes; the existing doc gives them no answer.

Changes in content/en/integrations/guide/azure-graph-api-permissions.md:

  • Adds a new ## Required permissions section with a rationale table for each of the five Application permissions. The Setup section now references this table instead of inlining the bare permission list.
  • Adds a new ## What Datadog does not access section that explicitly states the integration does not read mailbox content, Office 365 group conversations, email bodies, calendar items, OneDrive/SharePoint/Teams files, or message attachments — addressing the most common security-review concern head-on.
  • Adds a new ## Reviewing for security teams FAQ section with three entries: "Does Datadog read emails or chat content?", "Why is Group.Read.All required?", "Can these permissions be reduced?".

REQUIRES SME REVIEW BEFORE MERGE

The per-permission rationale table is a starting draft for SME correction, not a verified reference. Each row claims something about what the Datadog-Azure integration reads and uses. I do not have first-hand knowledge of the integration's data-access logic; the rationales are my best inference from public scope documentation.

Specifically, please verify or correct each of the following before merging:

  • Application.Read.All — claim: app registration metadata used to associate Azure resources with their owning applications.
  • Directory.Read.All — claim: tenant directory metadata (organization details, read-only access to directory objects) used for tenant-level discovery context. (Revised from an earlier draft that incorrectly mentioned subscriptions/resource groups, which are in Azure Resource Manager, not Microsoft Graph.)
  • Group.Read.All — claim: group identifiers and display names used for resource ownership context.
  • Policy.Read.All — claim: identity-related policies in the tenant (Conditional Access, sign-in policies) used for security and compliance context. (Revised from an earlier draft that conflated Microsoft Graph identity policies with Azure cloud policies — these are different concepts.)
  • User.Read.All — claim: user identifiers and display names used for resource ownership context.

In addition, please verify the claims in the "What Datadog does not access" section, the "Why is Group.Read.All required?" answer (specifically, whether Microsoft Graph really has no narrower read-only permission for the integration's group-metadata use case), and the "Can these permissions be reduced?" claim that all five permissions are individually load-bearing.

Merge instructions

Merge readiness:

  • Ready for merge

Additional notes

This is the third of six planned PRs under DOCS-13085. Marked WORK IN PROGRESS pending the SME review noted above. Branched directly off master (no dependency on PRs 1 or 2).

@buraizu buraizu requested a review from a team as a code owner April 28, 2026 21:32
@buraizu buraizu added the WORK IN PROGRESS No review needed, it's a wip ;) label Apr 28, 2026
@github-actions github-actions Bot added the Guide Content impacting a guide label Apr 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

Preview links (active after the build_preview check completes)

Modified Files

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Guide Content impacting a guide WORK IN PROGRESS No review needed, it's a wip ;)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant