Skip to content

Entra ID Diagnostic Settings

The Entra ID diagnostic setting is a single tenant-wide setting that streams Entra ID sign-in, audit and identity-protection logs into the central Log Analytics workspace. Without it, Entra keeps these logs only briefly, Conditional Access reporting has no data, and there is no long-term record of who signed in or what changed in the directory.

Why it matters

Entra ID keeps its own sign-in and audit logs for a short time only: 7 days on the free tier, 30 days with Entra ID P1 or P2. That is not enough for incident investigation, access reviews or audit. The diagnostic setting copies the logs to a Log Analytics workspace as they are written, where retention is under your control.

It feeds:

  • Conditional Access "Insights and reporting". The workbook queries SigninLogs. Each sign-in records how every Conditional Access policy was evaluated, including what report-only policies would have done. Without the diagnostic setting, the blade has no data source and returns an error.
  • Security tooling. Defender for Cloud, and Sentinel if it is added later, read the same tables.
  • Audit evidence. A durable record of sign-ins and directory changes supports NIST SP 800-53 AU-2 (audit events), AU-6 (audit review) and AU-11 (audit record retention).

Licensing

Exporting sign-in logs needs Entra ID P1 or P2. Audit logs can be exported on any tier.

What is streamed

Category What it contains Why it's enabled
SignInLogs Interactive user sign-ins, including per-policy Conditional Access results Conditional Access Insights, and investigating user sign-ins
AuditLogs Directory changes: users, groups, apps, roles, policies Change evidence for every directory write
NonInteractiveUserSignInLogs Sign-ins made by a client on a user's behalf, such as token refreshes Completes the user sign-in picture. Often the highest-volume category.
ServicePrincipalSignInLogs Sign-ins by service principals, including pipeline identities Shows when and from where each pipeline identity authenticated
ManagedIdentitySignInLogs Sign-ins by managed identities The same, for managed identities
ProvisioningLogs User and group provisioning to and from connected apps Evidence for automated account lifecycle
RiskyUsers Users flagged by Identity Protection Identity risk investigation
UserRiskEvents The individual risk detections behind those flags Identity risk investigation

Other categories exist, for example MicrosoftGraphActivityLogs and the service principal risk categories. They are not enabled today. To add one, add it to the category list in the deployment.

Where the logs go
Workspace log-platform-prod
Resource group rg-monitoring-prod
Subscription Management subscription, under mg-management
Owned by The azure-monitoring deployment
Retention Set per table on the workspace, not on the diagnostic setting. SigninLogs and AuditLogs keep 90 days interactive and about 2 years archive (azure-monitoring, local.table_retention).

How it is deployed

The diagnostic setting is one resource, azurerm_monitor_aad_diagnostic_setting, deployed by its own single-purpose repository, azure-entra-diagnostics. It calls the solution-manage-entra-diagnostics module with the target workspace and the category list.

flowchart LR
    ENTRA["Entra ID<br/>(tenant)"] -->|"diagnostic setting<br/>8 log categories"| LAW["log-platform-prod<br/>(Log Analytics)"]
    LAW --> CA["Conditional Access<br/>Insights and reporting"]
    LAW --> SEC["Defender for Cloud"]
    LAW --> AUD["Audit evidence<br/>(90 days + ~2 years archive)"]
    DEPLOY["azure-entra-diagnostics<br/>(sp-pla-tf-entra-diagnostics-rw)"] -.->|manages| ENTRA

Pipeline identity and permissions

The deployment runs as sp-pla-tf-entra-diagnostics-rw. That identity is created as a roster entry in the tenant root deployment, not through service principal vending.

Grant Type Scope Why
Security Administrator Entra ID directory role Tenant The only way to write Microsoft.AADIAM/diagnosticSettings. There is no Microsoft Graph application permission for it.
Log Analytics Contributor Azure RBAC log-platform-prod only Azure checks that the caller can use the target workspace before it creates the setting. Granted by azure-monitoring.
Storage Blob Data Contributor Azure RBAC Its own state container Terraform state
Reader Azure RBAC rg-terraform-state terraform init

It holds no Graph application permissions and no roles on any subscription.

Why a whole deployment for one resource

Security Administrator is a Tier 0 directory role (see Role Tier Mapping). The platform keeps directory roles like this off shared pipeline identities. So rather than add the role to the monitoring or Conditional Access pipeline, this setting gets its own identity and its own repository. The blast radius of a merge here is this one resource.

If more directory-role-gated Entra configuration moves into code later, such as authentication methods policy or other Microsoft.AADIAM settings, this deployment is where it belongs.

Known exception to Lane A

Under the Security Model, Tier 0 changes go through Lane A: plan-only CI and a PIM-elevated human apply. This deployment is an exception. Its pipeline identity holds Security Administrator as a standing, active assignment, and CI applies after a manual approval job on main.

The mitigations are a single-purpose identity with no Graph permissions and no subscription access, a single-resource repository, OIDC tied to this one project path, a protected main branch, and a narrow CODEOWNERS set.

The residual risk is accepted but real. Security Administrator can manage security-related tenant settings, including Conditional Access policies, and read all identity-protection data. Anyone who can merge to this repository's main and approve the apply job inherits that. The Tier 0 Pipeline Design page explains why a GitLab approval job is weaker than PIM. Review this exception whenever the deployment's scope grows.

Order of operations

Each step needs only what an earlier step produced:

  1. Tenant root bootstrap: creates the management subscription and Terraform state storage.
  2. Tenant root identity roster: creates sp-pla-tf-entra-diagnostics-rw, assigns Security Administrator and creates its state container. This is a human, PIM-elevated apply.
  3. Management groups and subscription vending: build the hierarchy and vend the monitoring pipeline's identity.
  4. azure-monitoring: creates log-platform-prod and grants sp-pla-tf-entra-diagnostics-rw Log Analytics Contributor on it.
  5. azure-entra-diagnostics: creates the diagnostic setting.

LinkedAuthorizationFailed usually means a stale object ID

Step 4 pins the service principal's object ID by hand, because the monitoring pipeline cannot read Entra ID to look it up. Use the service principal object ID, not the application (client) ID. If the identity is ever deleted and recreated, it gets a new object ID and the grant silently goes stale. The symptom is a LinkedAuthorizationFailed (403) error when step 5 applies. This looks like an ordering problem, but the real cause is the wrong ID.

One-time portal step: Conditional Access Insights

Binding the Conditional Access "Insights and reporting" workbook to the workspace is a tenant setting that cannot be managed through Terraform or Graph. Do it once, by hand:

  1. Give your account Log Analytics Reader on rg-monitoring-prod and Monitoring Reader (or Reader) on the management subscription. The workspace picker needs both.
  2. Sign out of the portal and back in, then allow about 10 minutes for the roles to apply.
  3. Go to Entra ID → Security → Conditional Access → Insights and reporting. Choose the management subscription and log-platform-prod, then save.

Verifying it works

Check the setting exists:

az rest --method get \
  --url "https://management.azure.com/providers/microsoft.aadiam/diagnosticSettings?api-version=2017-04-01-preview" \
  --query "value[].{name:name, workspace:properties.workspaceId, categories:properties.logs[?enabled].category}"

Within about 15 minutes of the first apply, data should appear in log-platform-prod:

SigninLogs | take 5
AuditLogs  | take 5

A re-run of terraform plan should show No changes. After provider upgrades, a change that only reorders the enabled_log blocks can appear. It is harmless.

Recommended: alert if the logs stop

If the diagnostic setting is removed or breaks, logs stop arriving without any error. A scheduled Log Analytics alert that fires when no sign-ins have arrived recently catches this:

SigninLogs
| where TimeGenerated > ago(6h)
| count

Alert when the count is zero. Choose the window to suit how busy the tenant is.