Cloud Tenant Integrations — Google Workspace & Microsoft 365

The Cloud tenants tab of the Breeze Integrations page (formerly Identity) is where you connect a customer’s Google Workspace or Microsoft 365 tenant to Breeze. It has two sub-tabs — Google Workspace and Microsoft 365. Microsoft 365 offers two connection methods: consent-based (Read access, plus optional Admin actions) uses customer-administrator consent without asking you for a reusable secret, while Legacy direct accepts a tenant-specific app client secret for existing read and action workflows.

Open it at Integrations → Cloud tenants (/integrations#cloud-tenants; the old /integrations#identity link still works). The two sub-tabs deep-link to /integrations#google (Google Workspace) and /integrations#m365 (Microsoft 365).

This page is about *connecting* a tenant

This page documents the connection step only — the credential fields and the connect/verify/disconnect flow. For what you can do once a tenant is connected (viewing identity posture, the full list of read and mutating AI actions, guided offboarding, and the approval gate), see the Identity Console. This page and the Identity Console describe the same two connectors from two angles: setup here, day-to-day use there.

Off by default

Both provider sub-tabs are feature-flagged off by default. A host operator must enable GOOGLE_WORKSPACE_ENABLED (Google Workspace) and/or M365_ENABLED (Microsoft 365). Consent-based Microsoft 365 connections have an additional organization allowlist; if they are not enabled for your organization and nothing is connected yet, the sub-tab shows the legacy direct card followed by a single line: “Consent-based connection isn’t available on this Breeze instance yet.” Host operators self-hosting Breeze: the environment variables that turn Customer Graph Read on are documented under Customer Microsoft 365 Graph-read consent.

---

Connecting a tenant

There is one Google Workspace connection per organization. Microsoft 365 can have one Customer Graph Read connection and one separate legacy direct connection per organization. Connecting, re-consenting, retesting, or disconnecting requires organization write permission and current MFA where shown.

Google Workspace

Google Workspace lives on the sub-tab at /integrations#google. Breeze authenticates as a Google Cloud service account that uses domain-wide delegation to impersonate a super-admin in the customer’s domain.

Credentials required

Field	Description
Primary domain	The customer’s domain, e.g. example.com
Super-admin email (impersonated)	A super-admin account in the domain that the service account impersonates
Service-account JSON key	The full service-account JSON key file, pasted into a masked field

Connect

1. Set your scope to the customer organization, then open Integrations → Cloud tenants → Google Workspace.
2. In the Google Cloud Console, open IAM & Admin → Service Accounts and create (or pick) a service account.
3. On that service account, open the Keys tab and choose Add key → Create new key → JSON. The JSON downloads once — that file is what you paste into Breeze. Note the service account’s numeric Client ID (its unique ID); you will need it in the next step.
4. Enable the APIs the identity tools use: Admin SDK, Gmail, Calendar, and Enterprise License Manager.
5. In the Google Admin Console, go to Security → Access and data control → API controls → Manage domain-wide delegation. Add the service account’s Client ID and authorize the exact OAuth scopes Breeze shows in the walkthrough (copy them straight from the card).
6. Back in Breeze, enter the Primary domain, the Super-admin email to impersonate, and paste the service-account JSON key.
7. Click Save & Verify. Breeze makes a live Directory API call to confirm the key works and that domain-wide delegation is correctly authorized, then stores the connection.

Domain-wide delegation scopes

The walkthrough card displays the exact comma-separated OAuth scope list to authorize. It covers directory user/group read and write, user security, aliases, mobile-device actions, Gmail settings (basic and sharing), Calendar ACLs, and Apps licensing — the scopes the Google identity tools actually call. Authorize the full list so every supported action works.

Microsoft 365

Microsoft 365 lives on the sub-tab at /integrations#m365. What you see depends on what this Breeze instance offers:

• Consent available: a tenant panel leads the sub-tab. Its header shows the connected tenant (name, tenant ID with a copy button, last verified) or “No Microsoft 365 tenant connected to organization”. Below it are two steps: Step 1 · Read access and Step 2 · Admin actions. The legacy direct method sits under Advanced: use your own app registration (legacy) at the bottom.
• Consent not available: the legacy direct card is the main card, followed by a one-line note that consent-based connection isn’t available on this instance.
• Legacy connection already exists: the legacy card is always shown expanded with a Legacy badge. When a legacy direct connection and a consent connection exist for the same tenant, the legacy direct connection takes precedence.

The two steps are independent consents; connecting or disconnecting one does not change the other. Read access is recommended first because AI lookups and reports depend on it.

Step 1 · Read access (Customer Graph Read)

Customer Graph Read uses Breeze’s dedicated multitenant, certificate-backed application. You do not enter a tenant ID, client ID, client secret, certificate, scope, or vault location. A customer Global Administrator or Privileged Role Administrator reviews Microsoft’s permission screen and grants consent.

1. Set your Breeze scope to the customer organization and find Step 1 · Read access in the tenant panel.
2. Review what it enables (open Show Microsoft permissions to see the thirteen required permissions), then choose Connect tenant.
3. Complete Breeze MFA and sign in to Microsoft as a Global Administrator or Privileged Role Administrator of the customer’s tenant. Breeze verifies who you are and which tenant your account belongs to before anything is consented. An account without either role stops here.
4. Breeze shows the tenant you signed in to (tenant ID and username) and asks you to confirm it. If it is your own MSP tenant rather than the customer’s, choose Cancel, wrong tenant and sign in again with the customer’s admin account. Otherwise choose Continue to Microsoft consent.
5. Review Microsoft’s consent screen carefully and accept only if it shows the expected application and exact permissions below. The screen is for the tenant you just confirmed and no other.
6. Breeze verifies its own access to that tenant (application token, organization probe, exact grants) and only then connects the tenant to the organization.
7. Confirm Read access shows Active, the tenant panel header shows the expected tenant, the manifest is version 3, and there are no missing or unexpected permissions.

Guest accounts sign in to their own tenant

Microsoft signs an account in to the tenant it belongs to. If you are a guest administrator in the customer’s tenant, signing in with that account verifies your home tenant, and the confirm step shows that tenant. Cancel and use an account that belongs to the customer’s tenant.

Reconnecting a tenant that is still connected, or approving new permissions, signs in at that tenant directly and skips the confirm step: the tenant is already known. Signing in there with another tenant’s administrator stops with a tenant-mismatch message before any consent screen.

If the customer’s Conditional Access policy interrupts the sign-in (for example a device check), the card says so instead of reporting a generic failure. Try again from a browser the tenant trusts, or ask the customer’s administrator.

Customer Graph Read requests exactly these Microsoft Graph application permissions:

Permission	Why it is requested
Application.Read.All	Read the dedicated application’s authoritative app-role assignments for drift detection
AuditLog.Read.All	Read audit and sign-in inventory
Device.Read.All	Read Entra device inventory
DeviceManagementConfiguration.Read.All	Read Intune configuration inventory
DeviceManagementManagedDevices.Read.All	Read Intune managed-device inventory
Group.Read.All	Read groups and memberships
Organization.Read.All	Verify and read the customer organization
Sites.Read.All	Read SharePoint site inventory
User.Read.All	Read users and directory profiles
AuditLogsQuery.Read.All	Run unified audit log queries on request
Policy.Read.All	Read Conditional Access policies and named locations
RoleManagement.Read.Directory	Read directory role assignments to identify administrators
SecurityEvents.Read.All	Read Microsoft Secure Score and its control profiles

The card shows required, observed, missing, and unexpected grants. Active requires exact equality. If Microsoft cannot complete authoritative reconciliation—for example, because Application.Read.All was removed—the card becomes Degraded and labels the retained observed list Last-known, rather than presenting it as current.

Use Retest to check an already-bound tenant. Use Re-consent when permissions were changed or the manifest is stale. Customer Graph Read is read-only and does not authorize password resets, user disablement, other Graph mutations, Exchange PowerShell, or delegated mail/Teams access.

Tenant sync and “as of” semantics

Once a tenant is connected, Breeze keeps a scheduled snapshot of it rather than querying Microsoft on every page load. Six domains sync independently:

Domain	Default cadence	What it stores
Users	6 hours	Directory profile, licenses, MFA registration state, admin roles
Intune devices	6 hours	Managed devices, compliance state, and the link to the Breeze device
Conditional Access	24 hours	Policy definitions and enabled / report-only / disabled state
Licenses	24 hours	Purchased and consumed seats per SKU
Secure Score	24 hours	Daily score and per-control detail, backfilled 90 days on first sync
Sign-in activity	24 hours	Last successful interactive sign-in per user

Every figure Breeze shows carries an as of time — the last run that completed a full enumeration of that domain, not the last time anything was written. A domain that returned only part of the tenant (a very large tenant, or Microsoft throttling mid-pull) is labelled partial and never causes a user or device to be marked as gone. A domain whose permission has not been approved yet is labelled needs consent and is simply not scheduled; the other five keep running.

Cadences adapt on their own: a domain that truncates or runs slowly backs off, a domain that has been quiet drifts back toward its default. You can force a refresh from the card at most once every 15 minutes per organization.

Sign-in activity requires Microsoft Entra ID P1 or higher. On a tenant without it, Breeze shows “Sign-in activity needs Entra ID P1” rather than an empty or zero value — the data does not exist to be read. Sign-in activity is also the one domain Microsoft rate-limits per application rather than per tenant, so on large fleets it refreshes less often than the others and its “as of” date is the honest answer to how current it is.

Disconnecting a tenant deletes the stored users, devices, policies and license rows immediately. Secure Score history and the daily posture rollups are kept and stay stamped with the tenant they came from, so reconnecting a different tenant never mixes the two.

Breeze stores no sign-in logs, no IP addresses, and no audit-log rows. User records are customer data of the customer’s own tenant: they are included in an organization export, erased with the organization, deleted on disconnect, and purged 30 days after a user disappears from the tenant.

Step 2 · Admin actions (Customer Graph Actions)

Admin actions uses a separate Breeze application with write permissions (User.ReadWrite.All and User-PasswordProfile.ReadWrite.All) so the AI assistant can reset user passwords and disable user sign-in, always behind the approval step described under After connecting. It can be granted at any time, but AI lookups and reports need Read access, so connect Step 1 first.

1. In the tenant panel, choose Grant admin actions…. Nothing is sent to Microsoft yet.
2. Read the pre-flight panel: what Breeze will be able to do, who must sign in (a Global Administrator or Privileged Role Administrator for the customer tenant), and how to revoke it later.
3. Choose Continue to Microsoft (or Cancel / Esc to back out), complete Breeze MFA, and sign in as an administrator of the customer’s tenant.
4. Confirm the tenant Breeze shows is the customer’s (the same confirm step as Read access), then grant consent on Microsoft’s screen.
5. Confirm Admin actions shows Active for the same tenant.

Legacy direct (existing client-secret method)

When consent-based connection is available, this method is under Advanced: use your own app registration (legacy) at the bottom of the sub-tab. Disconnecting it asks for confirmation.

Legacy direct uses a customer-specific Entra app registration and the client-credentials flow. You create the app in the customer’s tenant, grant its permissions, and give Breeze the tenant ID, client ID, and client secret. This method remains available for existing identity read and action workflows.

Credentials required

Field	Description
Tenant ID	The tenant’s Directory (tenant) ID — a GUID. The contoso.onmicrosoft.com domain form is rejected; use the GUID from the Entra app registration’s Overview page
App (client) ID	The Application (client) ID of the Entra app registration
Client secret	The app’s client secret value (not the secret ID), entered in a masked field

Connect legacy direct

1. Set your scope to the customer organization, then open Integrations → Cloud tenants → Microsoft 365.
2. In the Microsoft Entra admin center (entra.microsoft.com) or the Azure portal, open Microsoft Entra ID → App registrations and pick an existing app or click New registration. Give it a name and choose “Accounts in this organizational directory only.”
3. On the app’s Overview page, copy the Directory (tenant) ID and the Application (client) ID into the Breeze fields.
4. Go to Certificates & secrets → Client secrets → New client secret. Set a description and expiry (24 months max), then copy the secret Value immediately — not the secret ID; it is shown only once.
5. Under API permissions, add the Microsoft Graph application permissions listed below, then click Grant admin consent.
6. Back in Breeze, enter the Tenant ID, App (client) ID, and the client secret.
7. Click Save & Verify. Breeze acquires a token and makes a live Microsoft Graph call to confirm the credentials and admin consent are in place, then stores the connection.

Legacy direct Microsoft Graph permissions

The connection card spells out which permissions back which capabilities:

Capability	Graph application permissions
Reads (user lookup, group memberships, sign-in activity)	User.Read.All, Group.Read.All, AuditLog.Read.All
Disable user / reset password	additionally User.ReadWrite.All + User-PasswordProfile.ReadWrite.All, plus the User Administrator Entra role

Grant admin consent for these in the app registration before saving, or the live verification (and later actions) will fail.

Tip

Google Workspace and legacy direct secrets are encrypted at rest and never returned to the browser. Customer Graph Read never asks the browser for a reusable Microsoft credential: its certificate is confined to a private executor and only safe connection health is returned.

---

Remove Customer Graph Read consent

Disconnect from Breeze immediately revokes Breeze’s local connection, clears its executable tenant/grant state, and rejects delayed callbacks. It does not delete the Microsoft Enterprise application or remove tenant-wide admin consent.

To remove Microsoft consent separately, a customer Entra administrator must:

1. First choose Disconnect from Breeze in Step 1 · Read access and confirm it shows Revoked.
2. Open the Microsoft Entra admin center for the verified customer tenant.
3. Go to Identity → Applications → Enterprise applications, find the dedicated Breeze Customer Graph Read application by its verified name and application ID, and open it. Do not modify an unrelated app registration.
4. Use the Enterprise application’s delete/remove option to remove that tenant’s service principal and tenant-wide application consent. Microsoft labels can vary by portal version; verify the tenant and application before confirming.
5. Confirm the Enterprise application is no longer present. If Breeze had not already been disconnected, a subsequent Retest would report an application verification failure; local status alone is not proof that Microsoft consent was removed.

Removing an individual permission is different from removing tenant-wide consent. In particular, removing only Application.Read.All prevents Breeze from authoritatively reading the current assignment set, so the card reports reconciliation unavailable and retains the prior list as last known.

---

After connecting

Once a sub-tab shows Connected, technicians work with the directory through the in-app AI assistant rather than through this Integrations page. Read-only lookups (user details, group memberships, security posture, Microsoft 365 sign-in activity) run automatically; anything that changes an account is gated behind a human approval step with a mandatory reason and a full audit trail. The two providers are not at parity — Google Workspace exposes a much broader mutating action set than Microsoft 365.

For the complete list of what you can view and do — including guided offboarding, the security-drift report, and the read-vs-mutating tiers — see the Identity Console.

---

Troubleshooting

The Google Workspace or Microsoft 365 sub-tab shows “not enabled on this instance.” The connector is feature-flagged off. Ask your host operator to enable GOOGLE_WORKSPACE_ENABLED or M365_ENABLED on the API server, then reload the page.

The Microsoft 365 sub-tab says “Consent-based connection isn’t available on this Breeze instance yet.” Consent-based onboarding is turned off on this Breeze instance, or your organization is not on its allowlist. It is not something you can change from the organization. Self-hosting operators enable it with the variables under Customer Microsoft 365 Graph-read consent; this also requires the Graph executor sidecar to be deployed.

The connection fails to save with a credentials error. Both providers verify credentials live before storing them. For Google Workspace, confirm the service-account JSON key is valid and that domain-wide delegation was authorized with the exact scopes shown on the card, using the service account’s numeric Client ID. For Microsoft 365, confirm the tenant ID and client ID are correct, the client secret Value (not the secret ID) was copied and has not expired, and admin consent has been granted for the required Graph permissions.

Customer Graph Read says an eligible administrator is required. Sign in as a Global Administrator or Privileged Role Administrator of the customer tenant. Breeze checks the role when you sign in, before any consent screen; other directory roles stop there.

The confirm step shows the wrong tenant. You signed in with an account that belongs to a different tenant, usually your own MSP tenant or, for a guest account, its home tenant. Choose Cancel, wrong tenant, then Connect tenant again and sign in with an account from the customer’s tenant. Nothing is consented or connected until you continue past the confirm step.

Microsoft blocked the sign-in (Conditional Access). The customer’s Conditional Access policy interrupted the sign-in, for example with a device check. Nothing was connected. Try again from a browser or device the tenant trusts, or ask the customer’s administrator to complete the sign-in.

Customer Graph Read is degraded. Review missing and unexpected grants on the card. Restore the exact thirteen-permission manifest, choose Re-consent, then Retest. If the card says reconciliation is unavailable, restore Application.Read.All first; the displayed observed list is last known, not a current assignment inventory.

Retest says the verification service is unavailable. This does not mean Microsoft consent was removed. Existing active state is preserved during a transient executor outage. Ask the Breeze operator to restore the private verification service, then Retest again.

Save is disabled. A fresh connection requires all fields. For Google Workspace: primary domain, super-admin email, and the service-account key. For Microsoft 365: tenant ID, client ID, and client secret. When updating an existing connection, the secret field may be left blank to keep the stored value.

I connected a tenant but AI identity actions still do not work. A verified connection is required in addition to the feature flag being on. Re-open the sub-tab and confirm the badge reads Connected. Also confirm the service account or app registration carries the write permissions and admin role required for the specific action (see the permissions tables above).

---

Related

• Identity Console — viewing identity posture and running AI-assisted identity actions once a tenant is connected
• AI Assistant — how read and mutating actions, approvals, and the audit trail work
• Integrations — the full Integrations page and its other tabs