docs(oidc): Snowflake External OAuth guide + custom claims

[bsod90]

What

• New guide: /admin/deployment/oidc/snowflake — connecting the Snowflake driver through OIDC workload identity via Snowflake External OAuth. Every step was verified end-to-end against a live Snowflake account: token config (custom audience + scp custom claim), CREATE SECURITY INTEGRATION … TYPE = EXTERNAL_OAUTH, service user mapped via sub → LOGIN_NAME, deployment env vars, and the SNOWFLAKE.INFORMATION_SCHEMA.LOGIN_HISTORY_BY_USER verification query (logins show OAUTH_ACCESS_TOKEN). Includes a failure-mode table for the four errors actually hit while setting it up.
• OIDC overview: documents the new Custom Claims field on token configs (Snowflake authorizes session roles exclusively through scp — the driving case), adds a Snowflake card to the per-provider guide list, registers the page in the nav.
• Snowflake data-source page: OIDC workload identity subsection under Cube Cloud (parallel to the Athena/Redshift/BigQuery pages from docs(oidc): document OIDC auth on Redshift, Athena, and BigQuery driver pages #11056), prerequisites mention, and honest CUBEJS_DB_USER/CUBEJS_DB_PASS required-flags (footnoted — not required with SNOWFLAKE_JWT/OAUTH).

Notes

• The Custom Claims capability ships in cubedevinc/cubejs-enterprise#12570 + #12569 — this PR should merge after those.
• Reference links checked bidirectionally; docs.json validated.

🤖 Generated with Claude Code

[claude]

Claude finished @bsod90's task in 1m 4s —— View job

---

Review — docs(oidc): Snowflake External OAuth

Docs-only PR; no code paths touched. Verified anchors (#token-lifecycle, #custom-claims), cross-refs, and docs.json registration. The Snowflake guide is thorough — the scp gotcha callout, the failure-mode table, and the verification query all match how External OAuth actually behaves.

Details — nothing blocking; a few minor suggestions

Tasks

• Read full diff and new snowflake.mdx
• Validate cross-references and nav registration in docs.json
• Sanity-check Snowflake SQL/integration setup against Snowflake docs
• Review OIDC overview "Custom claims" section

Findings

docs-mintlify/admin/deployment/oidc/index.mdx:174-176 — array-claim wording is hard to parse

"Values are emitted as strings; to emit an array claim, comma-separate the values (a trailing comma forces a one-element array)."

The trailing-comma rule is a real implementation behavior but reads as a footnote-in-passing. Consider an explicit example, e.g.:

• scp = session:role-any → string claim
• scp = session:role-any,role:reader → array of two
• scp = session:role-any, → one-element array

Otherwise readers may not realize a bare session:role-any value emits a string (which Snowflake happens to accept for scp, but other consumers may require an array).

docs-mintlify/admin/deployment/oidc/snowflake.mdx:76 — EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE'
The body text below says this lets the driver request any role granted to the user, and that pinning the role in the token requires 'DISABLE'. Worth noting that Snowflake also supports 'ENABLE_FOR_PRIVILEGE' (allows any role only with USE_ANY_ROLE privilege) — not required, but a one-line "see Snowflake docs for the third mode" pointer would help readers in stricter shops. Optional.

docs-mintlify/admin/deployment/oidc/snowflake.mdx:140 — token path placeholder
The guide says "if you don't know your numeric tenant ID, contact Cube support." If there's a way to surface it in the console (e.g. a copyable value on the OIDC admin page), worth linking — otherwise this is a real point of friction for self-service setup. Not a blocker.

docs-mintlify/admin/connect-to-data/data-sources/snowflake.mdx:108-109 — footnote marker on required column
Rendering ✅<sup>1</sup> inside a markdown table works but is visually noisy; some Mintlify themes strip the <sup>. The current rendering is fine, just flagging for visual QA.

Nit: docs-mintlify/docs.json — the whitespace fix-ups (alignment on oidc/snowflake, the blank-line scrub, trailing newline) are good house-keeping. No issues.

Things that look right

• Anchors #token-lifecycle and #custom-claims both resolve to real sections in the overview.
• Bidirectional cross-refs: overview lists Snowflake → guide; guide links back to overview; data-sources page links to guide and overview.
• TYPE = SERVICE callout (line 109) is correct and worth keeping — Snowflake silently downgraded this in past releases, and it's a legitimate security win to mention.
• The four-row failure-mode table maps to the actual error strings Snowflake emits (Invalid OAuth access token, is not listed in the Access Token, etc.).
• The "Notes" in the PR body correctly state this should merge after cubedevinc/cubejs-enterprise#12570 + #12569 since the Custom Claims UI field is documented as already present.

• `docs/snowflake-oidc`

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Jun 10, 2026, 7:07 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @bsod90's task in 58s —— View job

---

Review — docs(oidc): Snowflake External OAuth (follow-up sync)

New commit a8071af cleanly removes the hand-written CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH from all three pages and replaces it with the Target Env Var mechanism. The story now hangs together: overview defines it, Snowflake guide uses it in step 1, data-source page reflects the simpler env config, and the failure-mode table is updated to point at the right misconfiguration. No blockers.

Details — minor nits only, nothing blocking

Tasks

• Re-read diff for new commit a8071af
• Verify Target Env Var is consistent across all three pages
• Check anchors and cross-refs
• Sanity-check failure-mode table updates

Findings

docs-mintlify/admin/deployment/oidc/snowflake.mdx:66-72 — consider linking to #custom-token-configs
The step-1 callout explains the Target Env Var inline, which is good, but the overview now has a dedicated Custom token configs section that goes deeper (why pods/dev/test-connection differ). A one-line see [Custom token configs][ref-...] link would let readers jump to the rationale without bloating the guide. Optional.

docs-mintlify/admin/connect-to-data/data-sources/snowflake.mdx:85-89 — same suggestion
The "Cube sets CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH automatically via the token config's Target Env Var" paragraph could similarly link to the overview's #custom-token-configs anchor for readers who land here first. Already links to the Snowflake guide, which is the more important link — this is purely a nice-to-have.

docs-mintlify/admin/deployment/oidc/snowflake.mdx:67 — screenshot TODO is fine to merge with
The {/* TODO: screenshot — Add OIDC Token Config dialog filled in for Snowflake ... */} comment is a JSX comment (won't render). Worth tracking so it doesn't ship indefinitely, but doesn't block merge.

docs-mintlify/admin/deployment/oidc/snowflake.mdx:171 — failure-mode row reads well
The updated row ("Target Env Var isn't set on the token config (or a stale hand-written path is configured)") is more actionable than the old tenant/deployment-ID hint. Good change.

Re-confirmed from prior review

The earlier suggestions on the original commit (array-claim wording example at index.mdx:174-176, the ENABLE_FOR_PRIVILEGE pointer at snowflake.mdx:76, footnote-marker rendering on snowflake.mdx:108-109) still apply on this revision — none are blockers, listing here so they aren't lost.

• `docs/snowflake-oidc`

[claude]

Claude Code is working…

I'll analyze this and get back to you.

View job run

[claude]

Claude finished @bsod90's task in 1m 11s —— View job

---

Review — docs(oidc): Snowflake External OAuth (screenshot pass)

Two new commits since the last review (e68d9da adds the dialog screenshot to the Snowflake guide and replaces the TODO; 54476ed reuses it as a worked example in the overview's Custom token configs section). Both land cleanly — the screenshot now shows both the scp claim and the CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH Target Env Var, which is exactly the pair the surrounding prose introduces. No blockers.

Details — minor nits only

Findings on the new commits

docs-mintlify/admin/deployment/oidc/index.mdx:208-210 — alt text duplicates wording from the snowflake.mdx Frame
The two <img> strings are nearly identical (~50 words each). Not wrong, but if you ever tweak one phrasing you'll want to update both. Optional: pull the alt text into a shared variable or just accept the duplication — it's docs.

docs-mintlify/admin/deployment/oidc/index.mdx:203-206 — nice framing
"combines both fields" is a good signpost since the section just introduced Target Env Var and Custom Claims came up earlier under [[index.mdx#custom-claims]]. The forward link to the Snowflake guide is correctly bracketed via [ref-oidc-snowflake].

Screenshot legibility — visual QA only
Worth eyeballing the rendered preview (cubed3-docs-snowflake-oidc.mintlify.app) at default zoom — Snowflake account URLs and env-var names can become hard to read in a downsized PNG. If it's tight, <Frame caption="…"> with a one-line caption is a cheap accessibility win.

Still-applicable from prior reviews (none are blockers, just so they don't get lost)

• Array-claim wording at index.mdx:173-176 could use a concrete 1-vs-2-element example.
• ENABLE_FOR_PRIVILEGE pointer at snowflake.mdx:76.
• Footnote marker rendering on snowflake.mdx:108-109 — visual QA.
• Optional links to #custom-token-configs from the Snowflake guide and data-source page.

Things that look right

• The new screenshot replaces the JSX TODO comment — no stale placeholder ships.
• <Frame> usage matches the conventions in docs-mintlify/CLAUDE.md.
• File path /images/admin/deployment/oidc/snowflake-token-config-dialog.png matches the asset added in e68d9da.
• The overview narrative now: defines Custom Claims → defines Target Env Var → shows them together in one screenshot → links to the full guide. Good progression.

• `docs/snowflake-oidc`

[claude]

Claude finished @bsod90's task in 2m 1s —— View job

---

Review — docs(oidc): Snowflake guide folded into data-source page

The new commit a56c1e5 deletes the standalone admin/deployment/oidc/snowflake.mdx and moves the entire verified setup (token config, External OAuth integration, service user, deployment env vars, verification, failure table) under a new #### OIDC workload identity subsection on the Snowflake data-source page. The overview's [ref-oidc-snowflake] and the in-page <sup>1</sup> footnote are repointed consistently. No blockers.

Details — minor nits only

Findings on a56c1e5

Cross-references — all resolve correctly

• docs-mintlify/admin/deployment/oidc/index.mdx:371 → /admin/connect-to-data/data-sources/snowflake#oidc-workload-identity ✓ (heading at snowflake.mdx:69)
• docs-mintlify/admin/connect-to-data/data-sources/snowflake.mdx:228 uses bare #oidc-workload-identity for the footnote — same target, in-page ✓
• docs-mintlify/admin/connect-to-data/data-sources/snowflake.mdx:360 defines [ref-oidc-overview]: /admin/deployment/oidc ✓
• No dangling references to the deleted /admin/deployment/oidc/snowflake path anywhere in the repo.
• docs.json cleanly drops the deleted page from the OIDC group; still valid JSON.

docs-mintlify/admin/connect-to-data/data-sources/snowflake.mdx:69 — heading is H4 under "Cube Cloud" (H3)
The slug oidc-workload-identity is unique on the page, so the anchor resolves. Worth eyeballing the rendered preview: H4 sections sometimes get tucked into the right-rail TOC less prominently than H2/H3, and this is a fairly long subsection. Not a correctness issue — visual QA only.

docs-mintlify/admin/connect-to-data/data-sources/snowflake.mdx:87-94 — table inside <Step>
Mintlify supports tables inside <Step> but they can render tight inside the stepper rail. The same applies to the failure-mode table at lines 192-197 (this one is outside Steps — fine). Worth a visual pass on the preview.

docs-mintlify/admin/connect-to-data/data-sources/snowflake.mdx:90 — "Name" row dropped the file-name hint
The deleted standalone guide said: snowflake — becomes the token file name, cube_cloud_token_snowflake. The folded version is just snowflake. Probably intentional (the data-source audience doesn't need to teach broker internals — the overview's Token configs covers that), but flagging in case it was an accidental drop.

docs-mintlify/admin/deployment/oidc/index.mdx:209 and snowflake.mdx:97 — alt-text divergence
The two <img> alt strings now differ slightly ("…for a custom Snowflake audience" vs "…for Snowflake"). Both are accurate; just a heads-up if you ever update one and expect the other to track.

PR body is now slightly stale (informational, no action needed)
The body claims the OIDC overview "adds a Snowflake card to the per-provider guide list" and "registers the page in the nav" — both reverted by a56c1e5 (correctly: the CardGroup at index.mdx:270-280 stays AWS/GCP/Azure, and docs.json has Snowflake removed from the OIDC group). Worth updating the body before merge so future readers of the PR history aren't confused. Not blocking.

Still-applicable from prior reviews

• Array-claim wording at index.mdx:173-176 — a concrete 1-vs-2-element example would help.
• ENABLE_FOR_PRIVILEGE pointer at snowflake.mdx:105 (formerly line 76 in the standalone page).
• Footnote-marker rendering on snowflake.mdx:228 (was 108-109) — visual QA.

Things that look right

• Consolidation reduces user navigation: a Snowflake user lands on the data-source page and sees the full OIDC path inline.
• [ref-oidc-overview] correctly carries the conceptual links (issuer, token configs, custom claims, target env var) — readers needing depth jump there.
• Verification SQL, failure-mode table, and TYPE = SERVICE callout all preserved verbatim.
• Image asset path /images/admin/deployment/oidc/snowflake-token-config-dialog.png is unchanged and still referenced from both pages.

• `docs/snowflake-oidc`