Help guides

Connect a Microsoft 365 tenant

Type the tenant’s domain in ConfigCheckup, have one of their Global Administrators approve read access, and the first assessment and the first report follow on their own.

Before you start

The tenant's domain, such as contoso.com, or any email address at it. Their tenant ID or their onmicrosoft.com name works too, but you do not need to look either up.
Someone in the tenant who is a Global Administrator or Privileged Role Administrator, with the role active when they accept. Only these roles can approve an application for the whole organisation. If the role is only eligible in Privileged Identity Management, they activate it first (see roles that must be active).
A ConfigCheckup account with the Consultant role or higher.

1. Add the tenant

In ConfigCheckup, go to Tenants → Connect a tenant. With no tenants yet, you can type the domain on Home instead.
Type the tenant's domain. As you type, ConfigCheckup asks Microsoft which tenant has it, and shows its tenant ID before anything is added. The tenant's own name and default domain are read once its administrator consents.
Give the tenant a name if you like; left blank, the domain is used until consent brings the tenant's own name. Choose Production, or Pilot or Lab for test tenants, which are left out of your portfolio averages. An Owner or Admin can change it later in the tenant's Settings. Marking a tenant Pilot or Lab does not by itself leave it out of the tenants you pay for: only the free test tenant is not counted.
Select Add tenant. The tenant is created as Waiting for consent, and a page that follows it to its first report opens with the consent link.

If the domain cannot be connected, the form says why before anything is added:

There is no such domain: check the spelling, or copy the domain from an email the tenant sent you.
A personal account: outlook.com, hotmail.com, live.com and gmail.com addresses are personal accounts, which have no Microsoft 365 tenant. Use the tenant's own business domain.
Google Workspace: the domain's email goes to Google and Microsoft has no tenant for it, so there is nothing to connect. If Microsoft does have a tenant for a Google Workspace domain, you are warned: it may be one Microsoft made by itself when someone signed up for a Microsoft service with a work address, and nobody administers those.
No tenant for the domain: the tenant may use Microsoft 365 under another domain. Try the address they sign in to Microsoft 365 with, or their tenant ID.

The lookup is made from ConfigCheckup's server, takes five seconds at most, and is limited to 30 lookups per person every ten minutes. It reads only what Microsoft and public DNS publish for anyone.

If you are a Global Administrator in the tenant, select Grant consent now. Otherwise select Email the consent request on the same page, or in the consent queue: the administrator gets an email in your brand, from you, that explains what is granted and how to take it back, with the link. Their replies come to you. You can also copy the link and send it yourself. When they open it, Microsoft shows the name of the application and every permission it asks for. They sign in, review the list and select Accept.

Tenants → Waiting for consent lists every tenant still waiting, whoever has waited longest first, with failed consents among them. Chase everyone waiting over 7 days emails the request again to where it last went (or to the tenant's primary contact), at most once a day for each tenant. It is only for a first connection: a tenant that was connected before and now needs consent again is left out, so ask its administrator yourself.

While consent is pending, the page that follows the tenant shows what anyone can see from outside: the domain's email protection in public DNS, and how Microsoft says its people sign in. Nothing is read from the tenant until consent is granted.

A short note to send with the link:

This lets us check your Microsoft 365 settings and read activity records such as sign-ins and the audit log. It does not give access to the content of mail, files, chats or meetings. You can remove it at any time in the Entra admin centre under Enterprise applications.

After they accept, Microsoft returns them to ConfigCheckup, the tenant changes to Connected and the first assessment is queued straight away.

3. The first assessment and report

Whoever consents comes straight back to the page that follows the tenant. It shows the connection being checked, then the first assessment: what is being checked and roughly how long is left. You can leave the page; it moves on by itself.

When the assessment finishes, an executive report is made from it in your brand without anyone asking. The person who added the tenant gets a notification and an email, Your first report for Contoso is ready, with a link to download it or send it to the tenant with a read-only link. On Home, Get set up ticks First report and offers Send it to the tenant. If you made a report yourself before it was ready, no second one is made.

4. Check the connection

The tenant’s Settings tab lists every permission that was actually granted under Access granted. If a required permission is missing, the tenant shows Partial access and names what is missing. Optional permissions that were not granted do not stop the assessment: the checks that need them are reported as not assessed, never as passes.

Permissions requested

Every permission is an application permission (not delegated), so assessments run on schedule without anyone signed in. All are Microsoft Graph permissions except SecurityRecommendation.Read.All (Microsoft Defender for Endpoint) and, for the automation app, Exchange.ManageAsApp (Exchange Online).

Required

Permission	Why
`Organization.Read.All`	Tenant profile, verified domains, technical contacts and assigned plans.
`Directory.Read.All`	Users, groups, devices and directory objects that underpin most checks.
`User.Read.All`	Account state, licence assignment (and which licences a group gives), whether a guest accepted their invitation, and sign-in activity per user.
`Group.Read.All`	Microsoft 365 groups, ownership, membership and guest exposure.
`GroupMember.Read.All`	Resolves the membership of groups targeted by Conditional Access.
`Policy.Read.All`	Conditional Access policies, authorization policy, security defaults, auth methods policy, idle session timeout and app credential restrictions.
`RoleManagement.Read.Directory`	Directory role assignments, PIM eligibility and PIM role settings (approval and alerts) — the privileged access picture.
`Application.Read.All`	App registrations, service principals, credential expiry and delegated consent grants, and whether Microsoft has verified the publisher of an app someone consents to.
`AuditLog.Read.All`	Last sign-in timestamps (dormant account detection), directory audit retention, and the audit and sign-in logs read for security event alerts.
`Reports.Read.All`	Authentication method registration, service usage, mailbox and OneDrive sizes and Microsoft 365 Copilot usage reports. Mailbox and OneDrive sizes are read with the users: without this permission the users are still read, without their sizes.
`SecurityEvents.Read.All`	Microsoft Secure Score and its control profiles.

Optional, each widens coverage

Permission	Why
`SecurityAlert.Read.All`	Microsoft Defender security alerts: to flag alerts left unresolved, and to raise new medium and high alerts as security events, with their title, category and the names of the accounts, devices and apps involved. Never mail or file content.
`Files.Read.All`	Which files and folders in people’s OneDrives and Microsoft 365 groups’ libraries anyone can open with a link, without signing in: each one’s name, address and library. Never file content.
`IdentityRiskyUser.Read.All`	Identity Protection risky users and risk detections.
`DeviceManagementConfiguration.Read.All`	Intune compliance and configuration policies, and whether a device with no compliance policy counts as compliant.
`DeviceManagementServiceConfig.Read.All`	Intune enrolment restrictions: whether personally owned devices can enrol. Settings only; no device is read.
`DeviceManagementManagedDevices.Read.All`	Enrolled device inventory, compliance state and OS versions.
`DeviceLocalCredential.ReadBasic.All`	Which Windows devices back up their local administrator password (Windows LAPS). Device names only; passwords are never read.
`MailboxSettings.Read`	Inbox rules, to find mail being forwarded outside the organisation, and, read live on a person’s panel and never stored, whether their automatic reply is on and when. Rule definitions and reply status only; no message content.
`SharePointTenantSettings.Read.All`	Tenant-wide SharePoint and OneDrive sharing configuration.
`DirectoryRecommendations.Read.All`	Microsoft Entra recommendations, including Identity Secure Score, and the objects each one names.
`ServiceMessage.Read.All`	Microsoft 365 message centre posts, to flag changes with an "act by" date.
`ServiceHealth.Read.All`	Microsoft 365 service health: open incidents and advisories.
`Policy.Read.DeviceConfiguration`	Entra ID device settings: who may join devices, the device limit per person, local administrators on joined devices and Windows LAPS.
`AccessReview.Read.All`	Access review definitions: whether guests and privileged roles are reviewed, how often and with what settings. Review decisions are not read.
`Policy.Read.B2BManagementPolicy`	The list of domains guests may, or may not, be invited from.
`OrgSettings-AppsAndServices.Read.All`	Whether people can use the Office Store and start trials of apps and services themselves.
`OrgSettings-Forms.Read.All`	Microsoft Forms settings: whether phishing protection checks forms made in the organisation. Forms and responses are not read.
`SecurityRecommendation.Read.All`	Microsoft Defender for Endpoint security recommendations (WindowsDefenderATP API). Recommendation names and device counts only.

Write permissions, used only by automation

These let approved fixes make changes. They belong to a second app, ConfigCheckup Automation, which the tenant approves with its own consent link, never as part of connecting the tenant. Holding them does nothing on its own: ConfigCheckup writes nothing until automation is switched on for that tenant and each change has been dry-run and approved. The same app reads Exchange Online settings once it holds the Exchange Administrator role (see Exchange Online). See turning on automation.

Permission	Used to
`Device.ReadWrite.All`	Disable or delete inactive end-of-life devices in Entra ID through an approved action.
`DeviceManagementManagedDevices.ReadWrite.All`	Delete the Intune records of inactive end-of-life devices through an approved action.
`Policy.ReadWrite.ConditionalAccess`	Create or amend Conditional Access policies via an approved action.
`User.ReadWrite.All`	Create users, give licences and invite guests when someone asks; disable dormant accounts, revoke sessions, clear licences, delete blocked accounts and remove guests (restorable for 30 days), and create cloud-only admin and emergency access accounts through an approved change.
`User-PasswordProfile.ReadWrite.All`	Reset a user’s password to a one-time password they must change at next sign-in, through an approved change, or give a new person’s account a temporary password where Temporary Access Pass is off. The password is shown once and never stored.
`RoleManagement.ReadWrite.Directory`	Remove stale or redundant privileged role assignments via an approved action.
`Policy.ReadWrite.Authorization`	Tighten tenant user settings (app consent, app registration, guest invitations) via an approved action.
`SharePointTenantSettings.ReadWrite.All`	Change SharePoint and OneDrive sharing settings (Anyone link expiry, guest-only sharing, resharing, sharing only with approved domains) via an approved action.
`Directory.ReadWrite.All`	Remove redundant role assignments and stale directory objects.
`MailboxSettings.ReadWrite`	Turn off inbox rules that forward mail outside the organisation, and set or turn off someone’s automatic reply, via an approved action. The reply already set, its message included, is read and kept with the change so a rollback can put it back; no email is read.
`DeviceManagementConfiguration.ReadWrite.All`	Create the Intune device baseline (compliance, encryption, firewall, antivirus and update policies) through an approved change.
`UserAuthenticationMethod.ReadWrite.All`	Remove MFA methods in an approved change: a leaver’s in an offboarding, a compromised account’s in a containment, or a person’s who lost their phone (Reset MFA); and issue a one-time Temporary Access Pass (shown once, never stored) for an account an approved change created, or, inside the approved run of an MFA reset, for the person whose methods it removed: shown once to the approver who runs it, never when the person who asked for the reset runs it, and never for an account holding an admin role or an emergency access account.
`GroupMember.ReadWrite.All`	Add people to groups and Teams, or set up a new starter in the same groups as a colleague, when someone asks; remove people from groups, or a leaver from all of theirs, through an approved change.
`Files.ReadWrite.All`	Give a leaver’s manager access to their OneDrive as part of an approved offboarding, and remove sharing links anyone can open from the files someone chooses, through an approved change. File contents are not read.
`Application.ReadWrite.All`	Block risky or unused apps from signing in ("Enabled for users to sign in"), and remove app secrets that have already expired, via an approved action.
`DelegatedPermissionGrant.ReadWrite.All`	Revoke delegated consent that gives an app access to mail, files or the directory, through an approved change.
`Group.ReadWrite.All`	Create groups and Teams and add their owners when someone asks; take an owner off, make public groups and Teams private, and delete unused groups, through an approved change. Group content is not read.
`Organization.ReadWrite.All`	Fill in the tenant’s technical and security notification contacts through an approved change.
`Policy.ReadWrite.AuthenticationMethod`	Turn on the Microsoft Authenticator registration campaign, turn off text message, voice and email codes, and show sign-in context in Authenticator, each through an approved change.
`Policy.ReadWrite.ConsentRequest`	Turn on the admin consent workflow, so people can ask for an app they may not approve themselves, through an approved change.
`Policy.ReadWrite.CrossTenantAccess`	Tighten the default cross-tenant access settings (Teams shared channels, partner MFA trust) through an approved change.
`DeviceManagementManagedDevices.PrivilegedOperations.All`	Ask Intune devices to check in now, and lock, wipe, retire, rename or restart a chosen device, each through an approved change. A full wipe always needs two approvers in the console.
`SecurityAlert.ReadWrite.All`	Resolve the Microsoft Defender alerts someone has chosen, with their classification, through an approved change.
`Domain.ReadWrite.All`	Make a verified custom domain the default, or add and verify one, through an approved change.
`Policy.Read.All`	Required by Microsoft beside Policy.ReadWrite.ConditionalAccess to create or change a Conditional Access policy or named location. Read only.
`Exchange.ManageAsApp` (Exchange Online)	Read and change Exchange Online and Defender for Office 365 settings, and Purview's where Purview automation is on. It works only with the Entra role the tenant gives.

Granting consent again

Consent covers the permissions the application had at the time it was given. Grant it again when new permissions have been added, when the tenant removed some, or when the tenant shows Partial access. The automation permissions have their own link, on the tenant's Automation card.

Open the tenant in ConfigCheckup.
In Re-grant admin consent, select Grant consent again if you are the tenant's Global Administrator, or copy the link and send it to them.
After they accept, run an assessment. The granted permissions are checked again at the start of every assessment.

Teams policies

Microsoft has no Graph permission for Teams meeting, external access and app policies. An application can read them once it holds a read-only Teams role. The tenant's admin gives it, by hand or in one sign-in from ConfigCheckup where the one-step role setup is on; ConfigCheckup never gives itself a role. Until then the Teams checks show as not assessed, with this step as the reason.

In the tenant's Entra admin centre, open Roles and administrators.
Select Teams Reader (or Global Reader, if the tenant already uses it for auditors) → Add assignments → the ConfigCheckup application (the read-only one, not ConfigCheckup Automation), as an Active assignment, not Eligible.
On the tenant's Settings, select Read Teams again beside Teams Reader, or run an assessment. The role can take up to an hour to apply. Given in one sign-in from ConfigCheckup, Teams is read again straight away where it was refused.

Exchange Online and Purview automation

Exchange Online and Defender for Office 365 settings are read and changed with Exchange admin commands, and Purview's labels, DLP and retention with Purview's. Microsoft runs those commands for an app only when it holds an Entra role as well as Exchange.ManageAsApp, so the 32 Exchange Online checks run through the ConfigCheckup Automation app once the tenant gives it the Exchange Administrator role; until then they show as not assessed. On Monitor and the trial, ConfigCheckup does not set the automation app up or give it a role; a tenant that gave it access earlier keeps it, and it is used only to read. Exchange.ManageAsApp is granted with the same automation consent as the other automation permissions. The tenant's Settings tab lists Exchange.ManageAsApp with the other automation permissions, and under Roles in this tenant shows whether each role is working, with what Microsoft said. After a role is assigned, select Check Exchange, which asks Exchange (and Purview, where it is on) without rechecking the whole connection: Microsoft can take a while to notice a role, so ConfigCheckup checks again by itself after 5, 15, 30 and 60 minutes.

The tenant's Global Administrator accepts the automation consent link.
The Exchange Administrator role for the ConfigCheckup Automation app. Where role setup and the administrator sign-in at consent are both on, it comes with the automation consent: the sign-in that records who consented also asks for permission to assign roles, and ConfigCheckup makes the assignments there and then as that administrator (Exchange Administrator; Teams Reader for the read-only app, or Global Reader, also read-only, where Microsoft will not give an app Teams Reader; and Compliance Administrator when Purview automation is on), so Entra's audit log records them as the person who did it. The sign-in is used once and not kept, and the permission comes off the app straight afterwards. If a role could not be given, Give the roles now under Settings → Permissions → Roles tries again. Otherwise, in the tenant's Entra admin centre: Roles and administrators → Exchange Administrator → Add assignments → choose the ConfigCheckup Automation app, with the assignment type Active, not Eligible. Either way ConfigCheckup never gives itself a role.
Only for Purview automation: switch it on in the tenant's Settings › Permissions, and assign the Compliance Administrator role the same way. It is off by default because that role can change every Purview policy.

If you run your own installation: the ConfigCheckup Automation app registration needs the Exchange.ManageAsApp permission, and the web service and the worker need the automation app's settings. Both are in the installation's docs/deploy.md. On ConfigCheckup's hosted service this is done for you.

Roles that must be active (PIM)

Many tenants use Privileged Identity Management (PIM), where an administrator's role is eligible: it does nothing until they activate it for a while. Two things follow.

The person. Accepting a consent link, or signing in for Give the roles now, needs Global Administrator or Privileged Role Administrator active at that moment. If theirs is only eligible, Microsoft refuses. They activate it in the Entra admin centre under My roles, then try again.
ConfigCheckup's apps. An app cannot activate a role, so a role given to ConfigCheckup or ConfigCheckup Automation as Eligible never takes effect, and Exchange and Teams stay not assigned. When assigning a role by hand, choose the assignment type Active, permanent or with an end date the tenant is happy with. Give the roles now always makes active assignments.

Many tenants at once

On every plan, if you are a Microsoft partner with GDAP relationships, Tenants → Connect a tenant → Connect from Partner Center lists your customers and adds them in one go, with one tag and one owner for all of them if you choose (each is also tagged partner-center). Each one still needs its own consent; the consent queue tracks which are waiting.

Without GDAP, paste a list of domains or email addresses into Connect several at once on the Connect page. Each is looked up with Microsoft and added to the consent queue, up to 25 at a time and within your plan's number of tenants (a free test tenant marked Pilot or Lab aside, on a plan that has one), and each line says what became of it.

An Admin can set defaults for new tenants in Settings → Workspace: how often they are assessed (every month unless you choose otherwise), who their reports go to (such as it@{domain}), their tags and their account manager. They are applied once, when each tenant's consent completes, and fill in only what the tenant does not have yet.

Connecting one tenant, you can tag it there and then, and, where your plan includes automation, tick Ask for automation consent too. The page that follows the tenant then shows the automation consent link beside the read-only one, for the same administrator. Holding it changes nothing: automation stays off for the tenant until an Admin switches it on in Changes › Automation.

Where your GDAP roles include Global Administrator or Privileged Role Administrator, an admin can connect them too: Sign in to connect tenants in bulk on the same page. You sign in once, tick the tenants, and ConfigCheckup gives its permissions in each one as you, through Partner Center, which is what the tenant’s own administrator would do on Microsoft’s consent screen. You can add the automation permissions and the roles in the same run. Your sign-in is kept only until the run ends, the permissions it needed in each tenant are taken off again there, and every tenant’s outcome is in the audit log. A tenant that cannot be connected this way says why, and can still be sent a consent link. Your account needs the Admin agent role in Partner Center.

Consent errors

Message	What it means and what to do
`AADSTS90094`, “needs admin approval”	The person signing in cannot approve for the whole organisation. A Global Administrator or Privileged Role Administrator must open the link.
`AADSTS650056`	The application is asking for a permission it has not declared. Contact support; this is fixed on our side.
`AADSTS700016`	The application is not in the tenant's directory: consent was never completed, or it was removed. Send the consent link again.
Tenant shows Partial access	A required permission is missing. Grant consent again, then run an assessment.
Many checks “not assessed”	Optional permissions were not granted, the Exchange or Teams role has not been given yet, or the tenant does not have the licence the check needs (Entra ID P1 or P2, Intune).

Disconnecting

Removing a tenant in ConfigCheckup deletes its assessments, findings and reports, but does not remove the application from the tenant's directory. To stop all access, the tenant deletes both ConfigCheckup and ConfigCheckup Automation in the Entra admin centre under Enterprise applications. Access stops immediately. More in data protection.

Trying it out?

Start free trial Take the 2-minute tour

14 days of daily monitoring and alerts, every finding with its fix guide, and reports on up to 3 tenants, from your first connected tenant. No card. Then choose the plan that fits.

Already set up? Sign in