Microsoft Entra ID

On this page

Microsoft Entra ID connects through a Microsoft admin-consent screen rather than a sign-in. A tenant administrator approves read-only access once, and from then on Governax reads your directory audit log every ten minutes. No credential of yours is stored.

Before you start#

What you need
ItemDetail
An administrator who can grant tenant-wide consentThe consent screen asks for Microsoft Graph application permissions across the whole tenant. In practice that means a Global Administrator or Privileged Role Administrator. Anyone with less sees Microsoft refuse, before Governax is involved.
An organisational tenantPersonal Microsoft accounts have no directory and no audit log to read, and the consent flow excludes them.
Entity operator access in GovernaxConnecting and disconnecting need operator grade on the entity.

What you are approving#

The consent screen lists four application permissions on Microsoft Graph. All four are read-only, and each one maps to something Governax actually does:

Permissions on the consent screen
PermissionUsed for
AuditLog.Read.AllThe event stream. Reads the directory audit log, which is where every event on this page comes from.
Directory.Read.AllThe baseline snapshot: the list of users and who holds each directory role.
RoleManagement.Read.DirectoryThe least-privileged way to read directory role members. Directory.Read.All also covers it; this keeps the role snapshot working if the broader grant is ever narrowed.
Organization.Read.AllYour tenant's display name, so the connection shows a name rather than a GUID. Best-effort: without it the tenant id is shown instead.

Governax reads audit records and directory objects only. It never reads mailboxes, files or passwords, and it never writes to your directory.

Connecting#

  1. Open the entity, then Integrations, then Microsoft Entra ID

    Click Connect. You are sent to Microsoft.

  2. Sign in as an administrator and accept the consent

    Microsoft shows the four permissions above and asks you to accept them on behalf of your organisation. Declining sends you back to Governax with nothing connected.

  3. Governax proves it can authenticate to your tenant

    Before anything is saved, Governax requests a token for your tenant using the consent you just granted. A consent that Microsoft accepted but that Governax cannot actually use is refused here, rather than becoming a connection that fails silently on its first background poll.

  4. The baseline snapshot starts

    You are returned to the integration page and the connection shows as connected. The snapshot runs in the background so a large tenant does not hold your browser open. The tenant's display name appears once it has resolved; until then the tenant id is shown.

A Microsoft tenant can be connected to one entity at a time. If it is already connected to another organisation the consent is refused outright; if it is connected to another entity in your organisation, disconnect it there first. See Connecting a tool.

Nothing of yours is stored#

Consent is recorded on Microsoft's side, against Governax's own app registration. Governax then mints short-lived, tenant-specific tokens from that registration whenever it needs to read. The only thing stored on the connection is your tenant id, which is not a secret.

What that means in practice
ConsequenceDetail
No per-customer secretThere is nothing to rotate, nothing that can expire, and nothing to leak.
No stale tokenTokens are minted on demand and cached for under an hour, so a connection cannot quietly go stale.
Revocation is yoursRemoving Governax under Enterprise applications in the Microsoft Entra admin centre withdraws the consent. Every read from Governax fails from that moment.

The baseline snapshot#

The event stream says what changed. The snapshot says what is true now, which is the question an access review actually asks. Without it, anyone who has held Global Administrator since before you connected would appear nowhere. Two things are captured, as access.baseline_observed events:

Baseline contents
SetDetail
Every userDisplay name, user principal name, and whether the account is enabled.
Every holder of every activated directory roleIncluding service principals. An automation holding a directory role is the finding that matters most in this snapshot, so the principal type is recorded alongside the role.

Group membership is deliberately not in the snapshot, for volume. Group changes from connect time forward are captured by the event stream.

How polling works#

Entra ID polling behaviour
PropertyValue
IntervalEvery 10 minutes
First pollBackfills the previous 7 days, or as much as your tenant retains
Each subsequent pollRe-reads a 1-hour trailing window, because Microsoft makes records queryable some minutes after they happen
Per passUp to 20,000 records; anything beyond that is picked up on the next pass

Events captured#

Actor and subject are recorded by user principal name, which is a real email address, so Entra events need no identity mapping to read.

Entra ID event types by area
AreaEvent types
Directory rolesaccess.admin_role_granted, access.admin_role_revoked. The payload names the role, whether the holder is a user or a service principal, and whether the assignment is active or a PIM-eligible one.
Group membership and ownershipaccess.group_member_added, access.group_member_removed, access.group_member_role_changed for an owner added to or removed from a group, application or service principal
User lifecycleresource.user_created, resource.user_deleted, resource.user_restored, access.user_deactivated, access.user_activated, access.member_invited for an external user
Credentials and MFAsecurity.password_changed, security.mfa_factor_added, security.mfa_factor_removed, security.mfa_reset
Applications and service principalsresource.app_created, resource.app_deleted, access.app_assigned, access.app_unassigned, and access.api_token_created / access.api_token_revoked when a client secret or certificate is added to or removed from an app
Consent grantsaccess.third_party_app_granted, access.third_party_app_revoked. The payload lists the permissions that were actually granted.
Conditional Accessresource.policy_created, resource.policy_changed, resource.policy_deleted
Groups and domainsresource.group_created, resource.group_deleted, resource.workspace_domain_changed for a domain added, verified or removed

What is deliberately dropped#

Records that produce no ledger event
RecordWhy
Failed attemptsEntra records a denied role grant under the same activity name as a successful one. Without this filter the ledger would show a privilege escalation that never happened.
Account state that did not changeEntra restates whether an account is enabled on unrelated updates. Only a real transition, enabled to disabled or the reverse, is recorded.
Profile editsJob title, manager, address and similar changes on a user are not access changes.
Routine service activityThe directory audit log carries a large volume of service chatter. Activities the connector does not recognise are counted internally rather than appended, so the governance signal stays readable.

Disconnecting#

Reconnecting later keeps the previous poll position, so a reconnect does not re-import everything.

Troubleshooting#

Common Entra ID connection problems
SymptomCause and fix
Consent was not grantedThe account that signed in at Microsoft cannot grant tenant-wide consent. Repeat the flow as a Global Administrator or Privileged Role Administrator.
Microsoft approved the consent, but Governax could not authenticateGovernax's own registration could not mint a token for your tenant, and the connection was not saved. Try again; if it persists, contact support.
That Microsoft tenant is already connected to another organisationA tenant can be live on one Governax organisation at a time. Contact support if this is unexpected.
This entity is already at its integration limitThe entity's plan caps how many connectors it can hold. Disconnect one, or upgrade the entity.
Nothing appears for 15 minutesExpected. Up to 10 minutes of poll interval, plus the time Microsoft takes to make a record queryable.
Events stop and the last error mentions a 403The consent was removed in your tenant, or was granted without AuditLog.Read.All. Reconnect to grant it again.
History from before the connection is missingExpected. The first poll reads back 7 days at most, and only what your tenant still retains.

General connector behaviour is covered in Connecting a tool.