[DNS Security] Umbrella integration uses deprecated Basic Auth against the Reporting API — Cisco now requires OAuth2 client-credentials token exchange, causing every sync to fail with 401 regardless of key type

[cisspUser01]

Description

The Umbrella DNS Security integration fails every sync attempt with a 401 Unauthorized from Cisco's
own API — confirmed NOT a credentials issue: tested against four different Umbrella key types
(Umbrella API key, Legacy Network Devices, Umbrella Reporting, Umbrella Management), all fail
identically, including a direct curl reproduction outside of Breeze entirely using confirmed-active
credentials. Root cause: UmbrellaProvider sends Basic Auth directly to the reports data endpoint,
but Cisco's current Reporting API v2 requires a two-step OAuth2 client-credentials flow instead.

Steps to Reproduce

1. Create a DNS Security integration with provider: umbrella, any valid apiKey/apiSecret pair
   generated from Umbrella's console, and a correct config.organizationId.
2. Trigger a sync: POST /dns-security/integrations/:id/sync
3. Sync fails. API logs show:
   [DnsSyncJob] sync failed (upstream HTTP error) {"status":401,"statusText":"Unauthorized",
   "responseBody":"{"meta":{},"data":{"error":"unauthorized"}}"}
4. Reproduced independently outside Breeze entirely, confirming this is not a Breeze-side bug in
   how credentials are stored/decrypted:
   curl -u ":"
   "https://reports.api.umbrella.com/v2/organizations//security-activity?from=...&to=...&limit=10"
   -> also returns 401 directly from Cisco, with the exact same credentials.
5. Tried regenerating credentials from all 4 available Umbrella key categories in Admin > API Keys
   (Umbrella API Keys, KeyAdmin Keys, Static Keys, Legacy Keys > Umbrella Reporting / Umbrella
   Management / Umbrella Network Devices / Legacy Network Devices) — every single one produces the
   identical 401, both through Breeze and via direct curl.

Expected Behavior

The Umbrella integration should authenticate successfully using valid, active Umbrella credentials
and begin syncing DNS security events.

Actual Behavior

Every sync attempt fails with 401, regardless of Umbrella key type, confirmed via direct API testing
outside Breeze with the identical credentials. Root cause identified from Cisco's own current
OpenAPI spec for this endpoint (developer.cisco.com/docs/cloud-security/umbrella-api-api-reference-
reports-reporting-api-activity-get-activities-all/):

"security": [{"oauthFlow": ["reports.granularEvents:read"]}],
"securitySchemes": {"oauthFlow": {"type": "oauth2", "description": "client credential flow",
"flows": {"clientCredentials": {
"tokenUrl": "https://api.umbrella.com/auth/v2/token",
"scopes": {"reports.granularEvents:read": "Read reports granular events"}
}}}}

Cisco's current Reporting API v2 requires:

1. POST https://api.umbrella.com/auth/v2/token with Basic Auth (apiKey:apiSecret) to obtain a
   short-lived Bearer access token
2. Use that Bearer token (Authorization: Bearer ) on the actual data endpoint

Confirmed from apps/api/src/services/dnsProviders/umbrella.ts that UmbrellaProvider does neither
step — it sends Basic Auth directly to the data endpoint:

basicAuthHeader() {
const token = Buffer.from(${this.apiKey}:${this.apiSecret}).toString("base64");
return Basic ${token};
}
...
const url = new URL(https://reports.api.umbrella.com/v2/organizations/${orgId}/security-activity);
...
const payload = await requestJson(url, { headers: { Authorization: this.basicAuthHeader() } });

Also worth noting: the base URL/path used (reports.api.umbrella.com/v2/organizations/{orgId}/
security-activity) differs from what Cisco's current spec documents (api.umbrella.com/reports/v2/
activity, org scoping handled via the token's own claims rather than a path segment) — this
integration appears to have been written against an older generation of Cisco's Reporting API that
has since been superseded.

Component

API Server

Version

Web/API 0.103.0, self-hosted via Docker Compose

Relevant Logs

[DnsSyncJob] sync failed (upstream HTTP error) {"integrationId":"...","status":401,
"statusText":"Unauthorized","responseBody":"{\"meta\":{},\"data\":{\"error\":\"unauthorized\"}}"}
[DnsSyncJob] Job sync-integration-... failed: DnsProviderHttpError: HTTP 401 Unauthorized
    at async UmbrellaProvider.syncEvents (/app/apps/api/dist/index.cjs:223002:27)

Additional Context

Suggested fix: implement the OAuth2 client-credentials token exchange (POST to
https://api.umbrella.com/auth/v2/token with Basic Auth to obtain a Bearer token, cache it for its
stated expiry, then use Authorization: Bearer on subsequent report requests) rather than
sending Basic Auth directly to the data endpoint. May also need to update the base URL/path to
match Cisco's current api.umbrella.com/reports/v2 structure if the legacy reports.api.umbrella.com
host is deprecated alongside the auth change (untested — worth confirming whether that host still
resolves/functions at all once OAuth2 is implemented, or whether both the host and auth need
updating together).

This affects any self-hosted Breeze instance attempting to integrate Cisco Umbrella for DNS
Security — not something fixable via configuration on the operator's end, confirmed by testing
against 4 separate Umbrella key categories, all failing identically both through Breeze and via
direct API testing with the same credentials.

[bdunncompany]

Picking this up unless you're already on it, @ToddHebebrand — say the word and I'll drop it.

@cisspUser01 that is an unusually complete report; the direct-curl repro outside Breeze with the same credentials is what makes it actionable, since it rules out storage/decryption on our side.

Confirmed the shape against origin/main: services/dnsProviders/umbrella.ts builds a single basicAuthHeader() (:22-23) and uses it at five call sites — the reports endpoint you hit (:52, reports.api.umbrella.com/v2/.../security-activity) plus four api.umbrella.com/policies/v2/destinationlists calls (:158, :176, :188, :205).

Two things I want to establish before writing code rather than assume:

1. Whether the policies endpoints also require the OAuth2 flow, or only the Reporting API. Your report and Cisco's spec cover reports; if policies moved too, a reports-only fix leaves block/allow-list sync broken in the same way. I'll verify both against Cisco's current published spec rather than infer from one.
2. Token lifetime and caching. A client-credentials token is short-lived, so this needs a cached token with refresh-on-401, not an exchange per request.

One limitation I'll be upfront about: I can implement and unit-test the exchange, but I have no live Umbrella tenant, so I cannot verify end-to-end that Cisco accepts it. If you're able to retest against a build once there's a PR, that would close the loop properly — otherwise the PR will say plainly that it's verified by construction and unit tests only.

[cisspUser01]

"Appreciate the thorough fix and root-cause writeup. I don't have a safe way to test an unmerged branch build against my production instance right now — I'll retest once this lands in an official release. Happy to confirm results then, including the destination-list sync you flagged."

[ToddHebebrand]

Fixed in #3275, now merged to main — thanks for the precise report, the deprecated-Basic-against-the-OAuth2-endpoint diagnosis was exactly right.

The integration now does a proper client_credentials exchange, caches the token, and refreshes it 60s ahead of the 3600s expiry. One detail from your thread that made it into the fix: Umbrella returns 400, not 401, for an expired token, so the retry path keys off both.

GitHub auto-closed this when the PR merged. It hasn't shipped in a release yet — if you'd rather keep it open until you've confirmed it against your own Umbrella tenant, say so and I'll reopen. Otherwise please do re-test once the next release is out and reopen if anything's still off.

[cisspUser01]

Follow-up: with the OAuth2 fix from #3275 live in 0.105.1 and a fresh "Umbrella API Keys" (modern, scoped) credential, authentication now succeeds — but sync still fails, reproduced consistently across multiple attempts:

{"errors":[{"param":"from","value":"2026-08-14T00:30:00.151Z","error":"invalid timestamp specified"},{"param":"to","value":"2026-08-15T00:30:00.151Z","error":"invalid timestamp specified"}]}

Per Cisco's own OpenAPI spec for this endpoint (umbrella-api-reference-reports-reporting-api-activity-get-activities-all), from/to should be Unix epoch milliseconds as a numeric string (e.g. "1639146300000"), not ISO 8601. UmbrellaProvider.syncEvents appears to send since.toISOString()/until.toISOString() — likely just needs String(since.getTime())/String(until.getTime()) instead.