[DOCS-13085] Add per-permission rationale and security FAQ to Azure Graph API permissions doc#36337
Open
[DOCS-13085] Add per-permission rationale and security FAQ to Azure Graph API permissions doc#36337
Conversation
…raph API permissions doc
Contributor
Preview links (active after the
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do? What is the motivation?
Fixes DOCS-13085
Expands
azure-graph-api-permissions.mdto 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 aboutGroup.Read.Allgranting 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:## Required permissionssection 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.## What Datadog does not accesssection 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.## Reviewing for security teamsFAQ section with three entries: "Does Datadog read emails or chat content?", "Why isGroup.Read.Allrequired?", "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.Allrequired?" 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:
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).