Identity federation: add user and service account examples, correct stale claims (DOCS-2516) by mdlinville · Pull Request #3165 · wandb/docs

mdlinville · 2026-08-31T21:48:18Z

Resolves DOCS-2516 (migrated from WBDOCS-1473, split from WB-19908 "Identity Federation Enhancements").

The ticket asked for a user-account example, a service-account example, notes on known usability issues, and removal of the "Preview" label. Everything except the Preview label is here — see the open question at the bottom.

Corrections to existing content

While sourcing the examples against wandb/core@master, four statements on the page turned out to be wrong or stale:

Page said	Source	Reality
The `sub` claim must equal the user's email address	`services/gorilla/internal/oidc/storage.go` (`CreateAccessTokenSession`)	Email is resolved as `sub` → `email` claim → any claim whose name contains `email`. Shipped for WB-27624 in server v0.74.0.
Settings → Set up JWT Issuer (one issuer)	`frontends/app/src/pages/OrgDashboard/AuthenticationSettings/AuthenticationSettings.tsx`	UI is a JWT Issuers list with Add JWT Issuer. Multiple issuers per org are supported.
Service account: pick Federated Identity, provide Subject	`frontends/app/src/pages/Billing/AccountSettings/ServiceAccountsTab/CreateServiceAccountDrawerForm.tsx`	The drawer also requires selecting a JWT Issuer, the option is disabled until an issuer exists, and the flow is reachable from org account settings as well as the team tab.
Set `FEDERATED_AUTH_AUDIENCES=wandb` to skip audience validation	`services/gorilla/cmd/gorilla_api.go:326`, `cmd/config.go:65`	That only sets the expected audience to its default. `SKIP_AUDIENCE_VALIDATION` is the actual skip flag.

New content

Examples — a user-account example and an external-service-account example, each with a decoded JWT payload and the matching workload config (shell + wandb.init(); Kubernetes projected service account token).
JWT validation reworked into a claim-by-claim table, adding three requirements that weren't documented: iat is required, exp − iat must be ≤ 24 hours (fosite default, not overridden in gorilla), and jti is optional but replay-checked.
Audience requirements split by deployment. Multi-tenant Cloud requires exactly one aud value, the org name, and it isn't configurable — WB-39012 (Mistral) is still open for that.
Troubleshooting — four failures seen in support this month:
- jti_known replay when login() and init() resolve WANDB_CREDENTIALS_FILE differently (EA, 2026-08-26).
- "No public JWK was registered for issuer … and subject …" usually meaning a bad aud, not a bad sub (Mistral, WB-39012).
- Deleted federated service accounts permanently claiming issuer+subject (WB-39165, open).
- Public API support landing later than wandb.init() support.
Scope note that Weave and Serverless Inference don't support identity federation yet (WB-37733).

Also updated

platform/hosting/env-vars.mdx and platform/hosting/iam/advanced_env_vars.mdx: WANDB_IDENTITY_TOKEN_FILE was described as "the absolute path to the local directory where Java Web Tokens (JWTs) are stored" — it's a file path, and they're JSON Web Tokens. Added WANDB_CREDENTIALS_FILE, FEDERATED_AUTH_AUDIENCES, and SKIP_AUDIENCE_VALIDATION, none of which were in the env var reference.

Open question for review

The "Preview" label is still on the page. The ticket asked to remove it, but I couldn't find a GA decision anywhere, and there's some evidence against: Weave and Inference support is still in flight, MT Cloud aud configurability is an open FR, and there's an open service-account deletion bug. @RyanBuccellato — is identity federation GA? If so I'll drop the note in a follow-up commit.

Two smaller things worth a second pair of eyes:

I state that the JWT Issuer and Subject are fixed at creation time. I inferred that from oauth.ts exposing only createClient/revokeClient with no update mutation.
I state that a federated service account can still be issued an API key afterward via the row menu, since ServiceAccountsTabContent.tsx:493 gates Create API key only on isApiKeyCreationDisabled and apiKeyCount.

🤖 Generated with Claude Code

…2516) Add a user-account example and an external-service-account example, and correct four statements that no longer matched wandb/core@master: - Email is resolved as sub, then the email claim, then any claim whose name contains "email" (WB-27624, server v0.74.0). The page still said sub must equal the user's email address. - The org settings UI is a JWT Issuers list supporting multiple issuers, not a single "Set up JWT Issuer" action. - Creating an external service account also requires selecting a JWT issuer, and is reachable from org account settings as well as the team tab. - FEDERATED_AUTH_AUDIENCES sets the expected audience; SKIP_AUDIENCE_ VALIDATION is the flag that skips the check. Document three previously unstated validation rules (iat required, exp - iat capped at 24 hours, jti replay-checked), split audience requirements by deployment type, and add troubleshooting for four failures seen in support: jti_known replay from a split credentials cache, a misleading "No public JWK was registered" error caused by a bad aud, WB-39165, and Public API version skew. Also fix WANDB_IDENTITY_TOKEN_FILE in both env var tables, which described a file path as a directory, and add WANDB_CREDENTIALS_FILE, FEDERATED_AUTH_AUDIENCES, and SKIP_AUDIENCE_VALIDATION. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

mintlify · 2026-08-31T21:48:21Z

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

Project	Status	Preview	Updated (UTC)
wandb	🟢 Ready	View Preview	Aug 31, 2026, 9:51 PM

Page	Change
Env Vars	Changed · +2 −1
Advanced Env Vars	Changed · +4 −1
Identity Federation	Changed · +222 −34

_{Updated 2026-09-08 20:43:07 UTC for deployment · b14c0d8.}

github-actions · 2026-08-31T21:49:27Z

Readability impact

Word-weighted Flesch-Kincaid grade change across 3 changed pages: -0.5 (easier).

Lower Flesch-Kincaid grade and higher reading ease both mean easier to read. This check is informational and never blocks a PR.

Human readability

Page	FK grade before	FK grade after	FK Δ	Reading ease Δ	Direction
`platform/hosting/env-vars.mdx`	12.6	12.6	+0.0	+0.0	unchanged
`platform/hosting/iam/advanced_env_vars.mdx`	14.3	14.3	+0.0	+0.0	unchanged
`platform/hosting/iam/identity_federation.mdx`	10.6	10.0	-0.6	+2.2	easier

AI agent comprehension

Rated 0-3 (higher is easier for an agent to parse and act on).

Page	Before	After	Δ
`platform/hosting/iam/identity_federation.mdx`	2	3	+1
`platform/hosting/env-vars.mdx`	3	3	+0
`platform/hosting/iam/advanced_env_vars.mdx`	3	3	+0

_{Curated-docs baseline median FK grade by type: conceptual 10.5, procedural 8.8, reference 9.4.}

From workflow run 34276106495

w-b-hivemind · 2026-08-31T21:49:58Z

HiveMind Sessions

1 session · 35m · $12

Session	Agent	Duration	Tokens	Cost	Lines
Investigating DOCS-2516 via Glean and Core `06a05099-59e2-4799-88fa-86886d8731a3`	claude	35m	65.3K	$12	+0 -0
Total		35m	65.3K	$12	+0 -0

View all sessions in HiveMind →

Run claude --resume 06a05099-59e2-4799-88fa-86886d8731a3 to pickup where you left off.

github-actions · 2026-08-31T21:52:09Z

🔗 Link Checker Results

✅ All links are valid!

No broken links were detected.

Preview: https://wb-21fd5541-docs-2516.mintlify.site

ckacal · 2026-09-01T22:42:17Z

-Identity federation is available in preview for Multi-tenant Cloud, Dedicated Cloud, and Self-Managed. An [Enterprise license](/platform/hosting/enterprise-licenses) is required. For details or assistance, contact your AISE or [support](mailto:support@wandb.com).
+Identity federation is available in preview for Multi-tenant Cloud, Dedicated Cloud, and Self-Managed. It requires an [Enterprise license](/platform/hosting/enterprise-licenses). For details or assistance, contact your AISE or [support](mailto:support@wandb.com).
+
+Identity federation covers W&B Models. W&B Weave and Serverless Inference don't support it yet. Use an API key for those products.


@RyanBuccellato just added support for Weave

It might also be helpful to call out that sandboxes do not support FI

yes though it will need to be next Weave SDK release and 0.85

and yeah sandboxes do not support it

Let's aim to hold these docs for 0.85.0 and also add a release note for this functionality.

ckacal · 2026-09-02T15:30:23Z

 JWTs are short-lived credentials that address the shortcomings of long-lived credentials such as API keys and passwords. The JWT expiry time depends on your identity provider's configuration. Refresh the JWT before it expires, and ensure that it's stored in the file referenced by the environment variable `WANDB_IDENTITY_TOKEN_FILE`.

-The W&B access token also has a default expiry duration, after which the SDK or CLI tries to refresh it using your JWT. If the user JWT has also expired by that time and isn't refreshed, authentication fails. If possible, implement the JWT retrieval and post-expiry refresh mechanism as part of the AI workload that uses the W&B SDK or CLI.
+The W&B access token expires after 14 days, after which the SDK or CLI uses your JWT to refresh it. If the user JWT has also expired by that time and isn't refreshed, authentication fails. If possible, implement the JWT retrieval and post-expiry refresh mechanism as part of the AI workload that uses the W&B SDK or CLI.


Because of a library default we use in JWT validation, a JWT is only accepted for a maximum of 24 hours after creation. It ensures the exp (expiry) time is less than 24 hours after the iat (issued at)
Though this is easily changed, a JWT can't currently be in a scenario where it is accepted 14 days later, not even 24+ hours.
(I see this information is included below)

So I'd just mention the "isn't refreshed" here.? Or remove the "by that time" which implies a JWT could be used after 14 days .

ah so we can't have one super long expiry JWT, maybe this is what I was vaguely remembering w.r.t. not being able to get around some sort of JWT update mechanism

Co-authored-by: Matt Linville <matt@linville.me>

mdlinville · 2026-09-03T20:47:57Z

 JWTs are short-lived credentials that address the shortcomings of long-lived credentials such as API keys and passwords. The JWT expiry time depends on your identity provider's configuration. Refresh the JWT before it expires, and ensure that it's stored in the file referenced by the environment variable `WANDB_IDENTITY_TOKEN_FILE`.

-The W&B access token also has a default expiry duration, after which the SDK or CLI tries to refresh it using your JWT. If the user JWT has also expired by that time and isn't refreshed, authentication fails. If possible, implement the JWT retrieval and post-expiry refresh mechanism as part of the AI workload that uses the W&B SDK or CLI.
+When W&B access token expires, the SDK or CLI uses your JWT to refresh it. If the user JWT has also expired, authentication fails. If possible, implement JWT retrieval and post-expiry refresh as part of the AI workload that uses the W&B SDK or CLI.


@ckacal PTAL

mdlinville requested a review from a team as a code owner August 31, 2026 21:48

mdlinville requested a review from RyanBuccellato August 31, 2026 21:48

Merge branch 'main' into DOCS-2516

601ee4a

mintlify Bot deployed to staging August 31, 2026 21:51 View deployment

mintlify Bot deployed to staging August 31, 2026 21:52 View deployment

Merge branch 'main' into DOCS-2516

3dd67a7

mintlify Bot deployed to staging September 1, 2026 20:05 View deployment

Merge branch 'main' into DOCS-2516

61c5467

mdlinville requested a review from ckacal September 1, 2026 21:54

mintlify Bot deployed to staging September 1, 2026 21:54 View deployment

ckacal reviewed Sep 1, 2026

View reviewed changes

ckacal reviewed Sep 2, 2026

View reviewed changes

Merge branch 'main' into DOCS-2516

5548bd0

mdlinville commented Sep 3, 2026

View reviewed changes

Comment thread platform/hosting/iam/identity_federation.mdx Outdated

Apply batched suggestions from code review

54e9f0d

Co-authored-by: Matt Linville <matt@linville.me>

mdlinville commented Sep 3, 2026

View reviewed changes

mintlify Bot deployed to staging September 3, 2026 20:55 View deployment

Merge branch 'main' into DOCS-2516

558f892

mdlinville marked this pull request as draft September 4, 2026 18:22

mintlify Bot deployed to staging September 4, 2026 18:25 View deployment

Merge branch 'main' into DOCS-2516

b14c0d8

mdlinville marked this pull request as ready for review September 8, 2026 20:39

mintlify Bot deployed to staging September 8, 2026 20:43 View deployment

ckacal approved these changes Sep 8, 2026

View reviewed changes

Uh oh!

Conversation

mdlinville commented Aug 31, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Corrections to existing content

New content

Also updated

Open question for review

Uh oh!

mintlify Bot commented Aug 31, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Readability impact

Human readability

AI agent comprehension

Uh oh!

w-b-hivemind Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

HiveMind Sessions

Uh oh!

github-actions Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Link Checker Results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ckacal Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mdlinville commented Aug 31, 2026 •

edited by atlassian Bot

Loading

mintlify Bot commented Aug 31, 2026 •

edited by github-actions Bot

Loading

github-actions Bot commented Aug 31, 2026 •

edited

Loading

w-b-hivemind Bot commented Aug 31, 2026 •

edited

Loading

github-actions Bot commented Aug 31, 2026 •

edited

Loading

ckacal Sep 2, 2026 •

edited

Loading