Shadow AI Onboarding & Enrollment

Dream big, build fast. This guide explains how AgentWatch brings shadow AI — the ChatGPT, Claude, Gemini, Copilot and other AI tools your people already use — under governance, for managed laptops, unmanaged laptops, and guest phones, on and off the corporate network. It covers exactly what each person experiences, what the tenant admin must configure, and the one decision that determines how much you can see.

1. The one thing that decides everything: the root CA

AI traffic is HTTPS. There are two levels of visibility, and which one you get depends on a single factor — whether the AgentWatch root CA is trusted on the endpoint:

	Without the CA (visibility-only)	With the CA (full governance)
You see	Which AI service (domain/SNI), volume, timing	Full prompts & responses, per-message audit
You can enforce	Nudge/enroll, org-level attribution	DLP redaction/blocking, per-user identity, guardrails
How identity attaches	Org-level (by network egress IP)	Per-person (`X-Zscaler-User` / MDM `$EMAIL`)
Endpoint change	None	Trust one root CA (via MDM, portal profile, or Connect)

Takeaway. Steering AI domains to AgentWatch (via DNS) gives you metadata — a list of who-is-using-what at the org level. Seeing and controlling content (DLP) requires the CA on the endpoint. Everything below is a way to get the CA (and identity) onto a device with the least friction for that device type.

If AI domains are steered to the gateway but the CA is not trusted, the browser will show TLS certificate errors — so either install the CA (full inspection) or run the gateway in SNI-passthrough mode (metadata only, no decryption).

2. The building blocks

AgentWatch DNS steering — a DoH/DoT resolver that returns the AgentWatch gateway IP for a curated set of browser AI-chat domains (chatgpt.com, claude.ai, gemini.google.com, copilot.microsoft.com, perplexity.ai, …). It deliberately does not steer API hosts (api.openai.com), downloads/CDNs, or dual-use tools (pip, brew, Claude Code) — those validate their own certificates and would break.
Root CA — the trust anchor that lets the gateway inspect content. Same CA whether delivered by MDM, the portal profile, or the Connect client.
Connect client (agentwatch-connect) — a lightweight endpoint agent (macOS/Windows/Linux) that installs the CA, steers AI domains locally, stamps the user’s identity, and forwards to the gateway. Best for laptops; works off-network too.
Enrollment portal — a per-tenant, branded captive/landing page at /portal that identifies the user (SSO / email-OTP / domain / name-only) and hands out the right installer or profile for the device.
Captive-portal trigger — makes the OS “Sign in to network” sheet pop automatically when a device joins the network, landing them on your portal.
Admit webhook — an HMAC-signed callback to your NAC/Wi-Fi when a device finishes enrolling, so you can lift a walled garden (“block until enrolled”).
Egress-IP → org attribution — maps your network’s public egress IP to your tenant, so even CA-less traffic is attributed to your organization.

3. What each person experiences

3a. Employee on a managed laptop (MDM) — fully transparent

Your MDM (Jamf / Intune / JumpCloud / Workspace ONE) silently pushes: (1) the AgentWatch root CA, (2) a DoH DNS profile pointing at the AgentWatch resolver, and optionally the Connect client pre-configured with the user’s identity.

The employee sees nothing. They open ChatGPT/Claude as usual; traffic is inspected, DLP applies, and every request is attributed to them (via the MDM’s $EMAIL/{{mail}} variable or Connect’s X-Zscaler-User). Works on and off the corporate network.

Device checks in to MDM → CA + DNS profile installed silently.
User opens an AI site → DNS steers it to the gateway → TLS trusted (CA present) → content inspected + DLP enforced.
Usage appears in Usage Insights attributed to the user.

3b. Employee on an unmanaged laptop — portal self-serve (a few clicks)

With no MDM, the device is nudged to your portal (captive trigger or a link you share).

Portal loads (your branding). Step 1 — verify identity: SSO sign-in, or corporate email + OTP.
Step 2 — install: the portal detects the OS and offers:
- Recommended — Connect client (e.g. AgentWatch-Connect-1.0.140-macos-universal.dmg): one download, installs CA + steering + identity.
- Alternative — configuration profile (.mobileconfig): CA + DoH DNS, no thick client.
The user approves the profile/installer once (trusting the CA when prompted). Done — full inspection + per-user identity.

3c. Guest on iOS (personal phone) on corporate Wi-Fi

On joining Wi-Fi, iOS captive detection fires → the OS opens your portal automatically.
Guest verifies identity per your policy (name-only, email-OTP, or SSO).
Portal offers a configuration profile (.mobileconfig) — iOS installs it in a few taps (Settings → Profile Downloaded → Install). It carries the CA + DoH DNS.
Once installed and the CA trusted → full visibility + content on that device.

iOS profiles are user-removable on a personal device — you cannot lock a BYOD phone. Treat guest coverage as consent-based.

3d. Guest on Android (personal phone) on corporate Wi-Fi

Captive portal appears the same way.
Limitation: Android has no equivalent to the Apple .mobileconfig for auto-installing a system CA + system DoH, and modern Android ignores user-installed CAs in most apps. So a guest who won’t/can’t install the CA yields visibility-only: the gateway sees the domain/SNI + volume/timing, attributed at the org level (by egress IP) — no content, no reliable per-user identity.
To get content on Android you need either a managed (MDM/Android Enterprise) device or the Connect client with consent (below).

3e. Guest who consents to the Connect client — identity without a corporate account

If you allow it (allowGuestConnectKey, off by default) and identity is verified (OTP or SSO), the portal mints a per-device, revocable gateway key bound to the verified email — never the shared org key. The Connect client then stamps X-Zscaler-User: <that email> on every request, so a guest is attributed to a real person even without a directory account. Unverified (name-only/domain) guests are refused a Connect key.

Guests install Connect with consent and, on their own device, can remove it themselves — by design. On a company-owned device pushed via MDM, interception is enforced and the client can’t be toggled off.

4. Does it need the new DNS container, or is the hosted `dns.interplay.iterate.ai` enough?

Both are valid — the difference is functional, not a version number. The hosted resolver isn’t an “old version”; it’s a shared, generic resolver. Capabilities that depend on your own tenant context require you to run your own dns-server container (authenticated to your tenant with a Connect key):

Capability	Hosted `dns.interplay.iterate.ai/dns-query`	Your own `dns-server` container
Steer default AI-chat domains → gateway	✅	✅
Content inspection (with CA on endpoint)	✅	✅
Captive-portal auto-pop on network join (`AGENTWATCH_DNS_CAPTIVE=1`)	❌ (can’t steer OS probe hosts for all tenants)	✅
Per-tenant redirect list / gateway IP / source-IP routing	❌ (generic set)	✅
Egress-IP → org attribution (attribute CA-less traffic to your org)	❌ (single Iterate egress, no tenant key)	✅

Rule of thumb:

Hosted DoH is enough for a quick pilot: push a DoH profile to managed devices → default AI-chat domains steer to a gateway → content inspection works because the CA (not DNS) carries identity via X-Zscaler-User. You lose captive auto-pop, per-tenant tuning, and org attribution of un-instrumented traffic.
Your own dns-server container is the production choice: you get captive auto-pop, per-tenant domain/gateway config, and egress-IP→org attribution. Cost: run the container, point corporate DNS/DHCP at it, register your egress ranges.

Two caveats that hold either way:

DNS only nudges — it never enforces. DNS cannot block arbitrary HTTPS. “Block until enrolled” is always a NAC / inline-gateway function; AgentWatch drives it via the admit webhook, not DNS.
Content inspection always needs the CA on the endpoint (§1). The DNS choice is orthogonal to CA trust.

5. Tenant-admin setup checklist

Everything below is in Settings → Enrollment Portal (company-admin) unless noted.

Enable + brand the portal. Toggle it on (off by default), set logo/colors/welcome/support email. Each tenant has its own portal.
Choose identity mode. sso (recommended) / otp (email one-time code) / domain (any allowed corporate email) / none (name-only guest). Set allowed domains and, for SSO, the provider.
Connect + DNS config. Set the DoH host + DNS IP (hosted or your container), the Connect version to advertise, and — for “block until enrolled” — the admit webhook URL + secret. Turn on allowGuestConnectKey only if guests may install Connect.
Point corporate DNS. Set DHCP option 6 / router DNS to the AgentWatch DoH resolver (hosted or your container). Enable captive steering (AGENTWATCH_DNS_CAPTIVE=1) on your container. Push a browser policy to disable “Secure DNS” so devices honor your resolver.
Register egress for attribution. Run your dns-server container with your server URL + Connect API key; it auto-registers your public egress IP against your org.
Author the MDM profile. Download the bulk CA + DoH DNS profile (and/or the templated Connect profile that emits $EMAIL/{{mail}} per user) and push it via your MDM.
Distribute Connect. Push via MDM (managed, enforced) or let users self-download from the portal.
Wire the admit webhook (optional). If you want block-until-enrolled, point the webhook at your NAC bridge; AgentWatch POSTs an HMAC-signed callback when a device enrolls so you can lift the walled garden.

6. FAQ

Can we see which AI sites people use without reading content? Yes — steer AI domains via DNS and run the gateway in passthrough. You get domain + volume + timing, org-attributed. Reading content requires the CA.

Do we have to inspect everything to attribute usage to a person? No content is needed for org-level attribution (egress IP). Per-person identity needs either the CA-injected X-Zscaler-User (MDM/Connect) or an OTP/SSO-verified portal enrollment.

Will steering break pip, brew, or Claude Code? No — the steer set is browser-chat domains only and explicitly excludes API/CLI/dual-use hosts, which validate their own certificates.

Can a guest remove the profile/agent? On a personal device, yes — BYOD is consent-based. On a company-owned MDM device, interception is enforced and cannot be toggled off.