Identity provider

Identity is the recommended first connection. It resolves every AI action Reagent sees to a person, and it lights up the AI app sign-up and OAuth grant signals that the rest of Discover builds on. On the Connections page (Reagent → Connections) this is section 01, Identity provider. Connecting requires the manage integrations permission (Administrator, MSSP Admin, or a custom role with it). Each tile below opens its own connection form.

Okta

Connector: okta-management · Auth: OAuth 2.0 client credentials with private key JWT against the Org Authorization Server (/oauth2/v1/token) · Requires: any plan

Reagent reads your Okta directory (users, groups, and app assignments), the OAuth grants users have given to apps, and System Log events. That is how it tells which AI apps your people reach through Okta SSO and which apps they have authorized. With the optional manage scopes, Reagent can also take response actions in Okta.

Lights up: AI App Sign-Ups & OAuth Grants (live-validated); AI Utilization in Sanctioned SaaS, for AI apps reached through Okta SSO (live-validated).

Before you start

• An Okta administrator who can create an API Services app integration, grant API scopes, and assign admin roles.
• Any Okta plan.
• Decide whether you want response actions. The read scopes and the Read-Only Administrator role cover discovery, entity sync, and alerts. Response actions need the manage scopes and the Organization Administrator role.
• In Reagent, the manage integrations permission.

Setup

Create the API Services app in Okta:

1. In Okta Admin, go to Applications → Create App Integration.
2. Select API Services as the Sign-in method.
3. Give it a name and click Save.
4. In the Client Credentials section, click Edit.
5. Select Public key / Private key as Client authentication.
6. Leave DPoP unchecked. Do not require Demonstrating Proof of Possession.
7. Click Add key, then Generate new key.
8. Copy the JWK (JSON format). It contains both the private key and the kid.
9. Click Done, then Save.
10. Copy the Client ID from the General tab.
11. Open the Okta API Scopes tab and grant the scopes in the tables below.
12. Open the Admin Roles tab and assign Read-Only Administrator, or Organization Administrator if you granted the manage scopes for response actions.

Then connect it in Reagent:

13. Open Connections, click the Okta tile, enter the values below, and save.

Okta Admin API access requires private_key_jwt authentication with the Org Authorization Server (/oauth2/v1/token). Reagent handles that token exchange with the key you paste.

Permissions

Read scopes. Required for discovery, entity sync, and alerts.

Manage scopes. Optional. They enable response actions.

If you skip the manage scopes, discovery and alerts still work in full. Response actions (suspending a user, revoking sessions, changing group assignments) are not available until you grant them and assign Organization Administrator.

What Reagent reads

• Users, groups, and app assignments, used to resolve AI activity to a person and to inventory the AI apps assigned through Okta SSO.
• OAuth app grants, which show which AI apps each user has authorized.
• System Log events, including sign-ins to AI apps through Okta SSO.
• Authentication and access policies, and admin role assignments.
• Okta groups also sync into Zaun Agent Gateway access rules on a 15-minute sweep, so the IdP groups a person belongs to become tool-level authorization.

---

Google Workspace

Connector: google-workspace · Auth: Standard: admin sign-in through your own OAuth client. Full: service account with domain-wide delegation, using a JSON key or keyless Workload Identity Federation with Okta · Requires: any plan

Reagent reads your Workspace directory (users, groups, org units, devices), the admin audit and usage reports, and the OAuth token census, which lists every third-party app each user has authorized. That is how it finds AI apps signed up with Google accounts, Gemini use inside Workspace, bots joining Meet calls, and Workspace Studio flows. Full access adds Alert Center alerts plus Gmail and Drive metadata, and lets Reagent take response actions on users, groups, and mobile devices.

Lights up: AI App Sign-Ups & OAuth Grants, with three live-validated packs (AI OAuth grants, the OAuth grant census, domain-wide delegation grants); AI Meeting Bots (bots in Meet calls, live-validated; calendar agents, template); AI Utilization in Sanctioned SaaS (Gemini in Workspace, live-validated); Custom Agents on Builder Platforms (Workspace Studio flows, live-validated); AI Desktop Apps (Chrome AI extensions, template). The Gemini tile on the AI tools page is a separate connector with its own credential. After a Full connection, open the Gemini tile, paste the same service-account JSON key and delegated admin address, and click Enable Gemini monitoring. Standard has no service account to reuse.

Before you start

• Choose an access level (next section). Standard is recommended.
• A Google Cloud project where you can enable APIs and create an OAuth client or a service account.
• For Standard: the Workspace admin account Zaun will run as, holding the privileges in the checklist the Connections page shows. Most existing Workspace admins already do.
• For Full: a Super Admin available for three one-time actions, and a dedicated delegated admin account (below). If your Google Cloud organization policy blocks service-account keys, plan on the WIF with Okta path, which needs an Okta org.
• In Reagent, the manage integrations permission.

Access levels

Your choice controls the exact Google permissions the Connections page shows throughout setup.

Standard is visibility-focused, but Google ships one required permission only as a read-write scope: admin.directory.user.security can list and revoke user OAuth tokens. The apps.alerts scope in Full also permits processing Alert Center records, because Google provides no read-only alternative.

Delegated admin account and custom role

Full runs as a delegated admin account, which Google calls the subject or impersonated account. Standard runs as the admin who signs in, so the custom role is optional there: skip it if the account you sign in with already holds every privilege in the checklist, or build it if you would rather Zaun used a dedicated account than a person's. A dedicated account keeps the audit trail unambiguous and lets you revoke Zaun's access without touching anyone's day-to-day admin rights.

Use a dedicated account rather than a person's admin account. It survives personnel changes, nobody signs into it interactively, its custom role stays limited to Zaun, and Workspace audit logs attribute Zaun's actions to the integration instead of a named person.

A Super Admin completes three one-time actions: create the custom role, assign it to the dedicated account, and (Full only) authorize domain-wide delegation. After that the Super Admin has no ongoing role in the connection. The runtime account uses the limited custom role and is never a Super Admin. Every setup path produces a copyable handoff message covering all three actions (Copy message for your Super Admin).

The custom role is named Zaun Integration (least privilege). Standard needs the first six privileges; Full needs all twelve. The Connections page shows the same checklist for the level you chose, with a copy button.

1. In Admin console → Directory → Users, choose Add new user. Give it a name you will recognize in audit logs, such as Zaun Integration, at an address like [email protected]. It consumes one Workspace license.
2. Leave it a normal user. Do not make it a super admin. It gets exactly the privileges in the checklist and nothing else.
3. In Admin console → Account → Admin roles, choose Create new role and name it Zaun Integration (least privilege).
4. On Select Privileges, tick exactly the privileges in the table above for your access level (Copy privilege checklist on the Connections page), then finish the role.
5. Open the role you just created, click Assign role in the Admins pane, find the account you created, and assign the role to it.
6. Enter the account's address in Admin account to connect on the Connections page.

Authorizing domain-wide delegation (Full only, once the service account exists): the Connections page shows the service account's Client ID and the scope list with copy buttons and an Open Domain-wide delegation link. The Super Admin adds that Client ID with the full scope list. A DWD grant lets the service account's client ID impersonate any user in the domain for the granted scopes, so the subject email is configuration, not a security boundary. Anyone holding the service account key could point it at another user, including a Super Admin, within those scopes. The granted scope list is the real boundary. The WIF path removes the long-lived key this concern depends on.

Standard OAuth sign-in

Complete these steps in one Google Cloud project. Zaun stores the OAuth client and the refresh token returned when an authorized admin approves access.

1. On the Connections page, click Google Workspace, choose Standard, and click Enable these APIs in Google Cloud. The link opens Google Cloud with both APIs, admin.googleapis.com and chromemanagement.googleapis.com, already selected. Pick the project you want to use for Zaun in the picker at the top, then click Enable. Or open Cloud Shell from inside that project and run the API command the page generates as-is: gcloud services enable admin.googleapis.com chromemanagement.googleapis.com. If gcloud says no project is set, run gcloud config set project PROJECT_ID first.
2. Write down the project you picked. Step 3 must use the same project. If the APIs are enabled in one project and the OAuth client is created in another, sign-in fails with a permission error even though your admin privileges are correct.
3. Open OAuth clients (https://console.cloud.google.com/auth/clients). Check that the project picker at the top shows the same project, then click Create Client. Set Application type to Web application and name it zaun-workspace-standard (Copy client name on the page).
4. If this project has never had an OAuth client, Google asks you to configure the consent screen first. Choose Internal for the audience, so the app stays inside your organization and skips Google's external app verification. The other fields are your own labels and contacts.
5. Under Authorized redirect URIs, click Add URI and paste the redirect URI from the page (Copy redirect URI). The URI is specific to your Zaun deployment, so take it from the page rather than typing it. Copy it exactly: a different scheme, host, port, path, or trailing slash causes Google to return redirect_uri_mismatch.
6. Click Create. In the OAuth client created dialog, copy both Client ID and Client secret before closing it. Google shows the client secret only once, so copy it now and keep it secure.
7. Paste the Client ID and Client secret into the page.
8. Click Sign in and approve. Sign in as the account Zaun should run as, not as your super admin. Its identity and admin authority come from this approval, so Standard does not use a subject email or domain-wide delegation.

Cloud Shell

Fastest path, about 5 to 10 minutes, with nothing to install. One command creates a service account, a non-human Google identity dedicated to Zaun, and sends it back to Reagent.

1. Choose Full, enter the delegated admin account, open the Cloud Shell tab, and click Generate your Cloud Shell command. The page generates the whole script, with a single-use token embedded. Nothing is hidden.
2. Click Save as .sh, open Cloud Shell (https://shell.cloud.google.com), and run the saved file. Pasting a script with prompts directly into Cloud Shell can terminate the session. Copy safe launcher avoids that: it pastes the whole script as a quoted heredoc that writes it to zaun-workspace-setup.sh and runs the saved file, so nothing is fetched. The optional Prefer a one-line command entry (Copy command) downloads and runs the same script; use that one only if you are happy running a fetched script without re-reading it at the prompt.
3. The script enables the required APIs, creates a dedicated service account, mints a key, and sends that key back to Zaun. The page waits for the service account to arrive. If the script printed Auto-send to Zaun failed, copy the JSON block under Paste into Zaun and paste it into the page.
4. Authorize domain-wide delegation with the Client ID and scope list the page now shows (see the previous section).
5. Click Test and activate.

If the command says service-account key creation is blocked, your Google Cloud organization policy does not allow key files. Switch to WIF with Okta, or ask your policy administrator to allow keys for this project and rerun. If the page reports that Cloud Shell could not be prepared, switch to Manual if your organization allows service-account keys, or to WIF with Okta if it blocks them.

Manual console

About 15 to 20 minutes. Click through Google Cloud yourself. This suits teams that want to review each setting and are allowed to store a service-account key file.

1. Open the API Library (https://console.cloud.google.com/apis/library) in the Google Cloud project that will host this connection and enable the eight services Full needs: admin.googleapis.com, alertcenter.googleapis.com, chromemanagement.googleapis.com, drive.googleapis.com, drivelabels.googleapis.com, gmail.googleapis.com, iam.googleapis.com, and iamcredentials.googleapis.com. The page also offers an optional gcloud command shortcut that enables all eight in one go. Enable all eight even where the page's API Library chips name fewer; a missing Chrome Management or Drive Labels API returns 403 later. A SERVICE_DISABLED error later means one of them is still off.
2. Open Create service account (https://console.cloud.google.com/iam-admin/serviceaccounts/create) and name it zaun-workspace.
3. Open the service account, choose Advanced settings, enable Google Workspace Domain-wide Delegation, and save the change.
4. Copy the numeric Client ID from Advanced settings and paste it into Service-account Client ID on the page.
5. On the service account, open Keys, choose Add key, then Create new key > JSON. If Create new key is disabled, your organization blocks service-account keys. Use the WIF with Okta tab, or ask your Google Cloud policy administrator to allow keys for this project.
6. Load the JSON key into the page: paste it, or drop the .json file. The page shows the service account email once the key is accepted.
7. Authorize domain-wide delegation (see the section above).
8. Click Test access, then Save the connection.

WIF with Okta

About 25 to 35 minutes. Best for organizations that block service-account keys. Workload Identity Federation (WIF) lets Zaun exchange short-lived Okta and Google tokens, so there is no key file to store or rotate. Step numbers match the Connections page, and the troubleshooting table refers to them.

1. In Okta Admin Console, open Applications > Create App Integration, choose API Services, then save the Client ID and Client Secret for step 13.
2. Open Security > API > default > Scopes, add zaun.wif, and select Set as a default scope.
3. In the same default authorization server, open Access Policies and add a rule that allows client_credentials for the application. Use the default authorization server token path /oauth2/default/v1/token. The shorter /oauth2/v1/token endpoint returns an opaque token that Google rejects.
4. Enable the required Google APIs. The page's link opens Google Cloud with all of them already selected: the eight Full services listed under Manual console step 1, plus sts.googleapis.com, which WIF uses for short-lived tokens. Pick your project in the picker at the top and click Enable, or run the API command in Cloud Shell launched from that project, as-is.
5. Open Workload Identity Federation (https://console.cloud.google.com/iam-admin/workload-identity-pools), choose Create Pool, and name it zaun-okta-pool.
6. Add an OIDC provider to the pool and enter the values the page shows: Issuer URL https://YOUR-DOMAIN.okta.com/oauth2/default (with your Okta domain in place of YOUR-DOMAIN), Allowed audience api://default, and Attribute mapping google.subject = assertion.sub.
7. Open Create service account (https://console.cloud.google.com/iam-admin/serviceaccounts/create) and name it zaun-okta-wif. This is the non-human Google identity Zaun becomes after Okta signs in.
8. Open the service account's Advanced settings, enable Google Workspace Domain-wide Delegation, and save the change.
9. Copy the numeric Client ID from Advanced settings and paste it into Service-account Client ID on the page.
10. Grant the identity pool access to the service account. Run the pool binding command from the page after replacing the project number, pool ID, and service-account email. The project number is numeric, not the project id: a principalSet built with the name silently never matches.

    SA="zaun-okta-wif@YOUR_PROJECT.iam.gserviceaccount.com"
    POOL="projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID"
    
    gcloud iam service-accounts add-iam-policy-binding "$SA" \
      --role="roles/iam.workloadIdentityUser" \
      --member="principalSet://iam.googleapis.com/$POOL/*"

11. Allow the service account to sign Workspace tokens. Run the second command from the page. Its principal is the same service account, not the pool, because Workspace requires the account to sign the delegated-admin token. This role exists only for that signing step, so a GCP-only WIF setup could skip it; this one cannot.

    SA="zaun-okta-wif@YOUR_PROJECT.iam.gserviceaccount.com"
    
    gcloud iam service-accounts add-iam-policy-binding "$SA" \
      --role="roles/iam.serviceAccountTokenCreator" \
      --member="serviceAccount:$SA"

12. Authorize domain-wide delegation (see the section above).
13. Enter the Okta application details: Okta Client ID, Okta Client Secret, and Okta Token URL in the form https://your-domain.okta.com/oauth2/default/v1/token. Use the /oauth2/default/v1/token path so Okta does not redirect the request to a sign-in page.
14. Enter the Workload Identity provider audience. In the provider's details page, copy its full resource name, for example projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider. Zaun accepts the path beginning with projects or the form beginning with //iam.googleapis.com/. It must include /providers/PROVIDER_ID; a single leading slash is invalid.
15. Enter the Google service-account email from step 7, for example [email protected]. It must end in .iam.gserviceaccount.com. The delegated admin account Zaun acts as is the separate address entered above the setup tabs.
16. Click Test Full access. Run the test before saving: saving cannot detect a missing Google IAM binding or Okta access policy until Zaun attempts the full token exchange.
17. Save the connection.

Domain-wide delegation scopes

Standard requests the Standard scopes when the admin signs in and approves your OAuth client. Full grants the whole list to the service account through domain-wide delegation. The Connections page shows the exact list for the level you chose, with a copy button.

What Reagent reads

• Directory: users, groups and who belongs to them, organizational units, domains, admin roles, calendar resources, and Chrome OS and mobile devices, used to resolve AI activity to a person.
• Admin audit and usage reports, which carry sign-ins and OAuth grants to AI apps, Gemini activity inside Workspace, bots joining Meet calls, and Workspace Studio flows.
• The OAuth token census: the third-party apps, including AI apps, each user has authorized, plus domain-wide delegation grants in the domain.
• Chrome management reports, which surface AI browser extensions.
• Full only: Alert Center security alerts and Gmail and Drive metadata.

---

Microsoft Graph

Connector: microsoft-graph · Auth: Azure app registration with client credentials, or consent to a Zaun-managed app · Requires: any Microsoft 365 plan for directory reads; the sign-in and OAuth-grant signals need Entra ID P1 (Business Premium, E3, or E5); the Defender group of managed apps needs Business Premium, E3, or E5

Reagent reads Entra ID users, groups, and sign-ins, the app registrations and OAuth consent grants in your tenant, and the detected-apps inventory Intune keeps for managed devices. With Defender for Endpoint licensing it also reads the software inventory Defender collects. That is how it sees which AI apps your people sign in to, which AI apps have been granted access to Microsoft 365 data, and which AI desktop apps are installed.

Lights up: AI App Sign-Ups & OAuth Grants (live-validated); AI Utilization in Sanctioned SaaS (AI app sign-ins, live-validated; Purview Copilot audit, template); AI Desktop Apps (Intune detected-apps inventory, live-validated; Defender for Endpoint software inventory, live-validated); Platform Agent Registries (Entra agent identities, template).

Licensing shapes what lights up. The sign-in and audit-log APIs require Entra ID P1, so the AI app sign-up, OAuth grant, and AI app sign-in signals need Business Premium, E3, or E5; on Business Standard only user, group, and device reads work. The Intune detected-apps inventory needs Intune-managed devices plus the Intune / Device Management capability (Bring Your Own) or a managed app from the Defender group. On E3, Defender for Endpoint P1 has no EDR or alert API, so add the Defender for Endpoint capability only with an MDE P2 or Defender for Business add-on. The Entra agent identities pack needs the AgentIdentity.Read.All application permission, which the standard credential does not carry by default; grant it on the app registration before activating that pack.

One credential backs four tiles: Microsoft Graph here, Microsoft Defender for Endpoint on the EDR page, and Microsoft 365 Copilot and Microsoft 365 Copilot Cowork on the AI tools page. Those three tiles use the same credential as this one. Connect Microsoft Graph first and they activate on their own once the tier you chose includes their permissions.

Before you start

• A Global Administrator in the Azure tenant to run the setup command or grant admin consent.
• Pick a mode. Bring Your Own Azure App keeps the app registration entirely in your control. Use Zaun-Managed App needs no Azure admin setup beyond consent.
• Pick what to grant. Bring Your Own: five capabilities (Entra ID & Identity; Defender for Endpoint (MDE); Defender XDR; Intune / Device Management; Email & Collaboration), each at Read only or Read + Response actions, with license presets for Business Standard, Business Premium, Microsoft 365 E3, and Microsoft 365 E5 to start from. Zaun-managed: an app card under Microsoft 365 Business Standard for environments without Defender, or under Microsoft 365 with Defender for Business Premium, E3, and E5.
• Use Zaun-Managed App: if this environment already has an active Microsoft Graph credential, delete it first. You cannot reconnect or change tiers while it exists. Bring Your Own: saving or activating a new app replaces the active connection after you confirm (Replace & Save or Replace & Activate).
• In Reagent, the manage integrations permission.

Bring Your Own Azure App

The first step is a capability picker. Each of the five capabilities has a Read only or Read + Response actions radio, and a license preset pre-fills the picker; you can adjust freely afterwards.

1. Open Connections, click Microsoft Graph, and choose Bring Your Own Azure App.
2. Select capabilities. Start from the preset that matches your Microsoft 365 license, then adjust each capability's level. The generated script requests exactly the permissions for the capabilities you selected (see Permissions below).
3. Click Generate. The page produces a single one-line command for Azure Cloud Shell that works in both Bash and PowerShell.
4. Open Azure Cloud Shell (https://shell.azure.com) as a Global Administrator and run the one line. You are already signed in there, so it runs with no extra login. It creates the app, grants admin consent, and prints Tenant ID, Client ID, and Client Secret under ==== Paste into Zaun ====. If you paste the full script by hand instead, match the tab (Azure CLI (Bash) or PowerShell) to your shell. A Bash script in a PowerShell prompt, or the reverse, errors line by line.
5. Prefer to configure manually? In the Azure Portal (https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade), register an app, add the Application permissions the page lists (Copy permission list), then grant admin consent. After creating the app and pasting its Client ID and Tenant ID into the page, grant admin consent with the consent link the page generates.
6. Paste your app details. The page waits for the script to send them automatically and shows Received app details from your shell when they arrive; click Activate connection (or Replace & Activate if a connection is already active) and you are done. Otherwise paste the ==== Paste into Zaun ==== block to auto-fill Tenant ID, Client ID, and Client Secret, or fill the three fields by hand, and continue to step 8.
7. Optional: set Secret expires on. The script output fills it automatically. Zaun reminds you 30, 7, and 1 days before the secret lapses.
8. Save (paste path only; the shell path activates in step 6). Reagent tests the connection and activates it.

Permissions

The Connections page lists the exact Application permissions for the capabilities you selected, grouped by resource, with a Copy permission list button. The generated script requests only those. Read only covers discovery and sign-in visibility. Read + Response actions adds the permissions response actions need. All of them are Application permissions.

Use Zaun-Managed App

Grant consent to one of Zaun's managed Azure apps. No Azure app setup on your side; pick the card that matches your security requirements. The page groups five managed apps under two permission levels, and each card has its own Generate Authorization URL button.

1. Open Connections, click Microsoft Graph, and choose Use Zaun-Managed App.
2. Under Select Permission Level, pick Microsoft 365 Business Standard for environments without Microsoft Defender, or Microsoft 365 with Defender for Business Premium, E3, and E5 environments.
3. Select the environment, then on the card you want click Generate Authorization URL. The button needs an environment selected first.
4. Click Grant Permissions and consent as an administrator who can grant tenant-wide admin consent, or use Copy Link to hand the URL to that administrator.
5. Back in Reagent, the credential appears under Existing Credentials.

What Reagent reads

• Users, groups, and admin roles in Entra ID, used to resolve AI activity to a person.
• Sign-in activity, including sign-ins to AI apps.
• App registrations, enterprise applications, and OAuth consent grants: which AI apps have been granted access to your tenant, and by whom.
• Detected apps on Intune-managed devices (needs the Intune / Device Management capability, or a managed app from the Defender group), and software inventory from Defender for Endpoint when your tier includes it.
• Purview Copilot audit and Entra agent identities (template packs). Entra agent identities need AgentIdentity.Read.All granted on the app registration first.