Skip to content

Document workload identity federation - #771

Merged
rgarcia merged 6 commits into
mainfrom
hypeship/wif-docs
Nov 19, 2026
Merged

rgarcia merged 6 commits into
mainfrom
hypeship/wif-docs

Conversation

@rgarcia

@rgarcia rgarcia commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Do not merge until the dashboard screens are live (Keys sidebar section, Connect workload, service account pages, authentication events). The docs describe them as available, and they are the only way to set up federation. The other two dependencies are done: the workload identity API is deployed, and the SDKs with federation support are released as 0.151.0. See "What each page depends on" below.

Summary

Adds customer-facing docs for workload identity federation and steers readers toward it everywhere they decide how to authenticate. A workload exchanges a short-lived token from its own identity provider for a five-minute KERNEL access token, so there's no stored API key to leak.

API keys are not described as deprecated. The docs say plainly that they remain the right tool for local development and for environments with no identity provider, and that service account API keys are the fallback for workloads that can't federate.

Pages added

Page What it covers
info/authentication "Which should I use": federation vs API keys, a per-environment chooser, and when a key is still right.
info/workload-identity/overview Why, concepts (service accounts, issuers, rules), how the exchange works, the Connect workload flow, SDK usage in three languages, precedence, lifetime and refresh, turning access off, visibility.
info/workload-identity/service-accounts What a service account is and can't do, last used, archiving, and service account API keys.
info/workload-identity/github-actions Dashboard setup, workflow YAML, token claims, how a rule matches, manual exchange.
info/workload-identity/aws Outbound identity federation, the IAM policy, the aws_sts source, nested claims.
info/workload-identity/google-cloud Unique ID lookup, the gcp_metadata source, reuse behavior, claim conditions.
info/workload-identity/microsoft-entra App registration audience, v1.0 vs v2.0, callback with Azure Identity, what's accepted.
info/workload-identity/kubernetes Projected token volume, the file source, reuse, private clusters with inline keys.
info/workload-identity/custom-oidc Token requirements, key sources, rules, file, callback, and static token sources.
info/workload-identity/migrate-from-api-keys Moving one workload from a stored key to federation without downtime, and rollback.
info/workload-identity/reference Token exchange request, response, and errors; discovery; SDK environment variables, sources, and options; issuer, rule, and service account fields; authentication events; auth context; management endpoints; limits.
info/workload-identity/troubleshooting Finding out why an exchange was refused, replayed tokens, SDK configuration, provider notes.

Pages changed

Page Change
docs.json Adds info/authentication and a Workload Identity Federation group (with a Providers subgroup) to Manage, ahead of API keys.
info/api-keys Recommendation to use federation near the top; list filters (status including expired, principal_type, service_account_id, created_by, project_id) and the note that active no longer includes expired keys; a Service account API keys section.
info/api-key-permissions Retitled Scoping Permissions (URL unchanged), because the page now applies to federation rules and service account API keys as well as scoped API keys. New intro and a "Where policies apply" table.
start/quickstart Tip in "Set your API key" to switch to federation when the code moves to CI or a cloud service.
info/projects Federation rules and service account API keys are limited to one project.
introduction/manage Card for workload identity federation; multi-tenant bullet mentions federation rules.
reference/cli/auth The CLI authenticates with kernel login or KERNEL_API_KEY and doesn't exchange workload identity tokens; use federation for SDK workloads.
reference/cli/api-keys Recommendation tip; the list shows active (not deleted, not expired) keys. No new CLI commands are documented, because the CLI has none for federation.
reference/mcp-server/authentication Tip that automation calling the API through an SDK doesn't need an API key.

What each page depends on

Page API SDKs Dashboard
info/authentication Yes Yes Yes
info/workload-identity/overview Token exchange, GET /auth/context, authentication events All three Keys section, Connect workload, Issuers, Rules, Authentication events
info/workload-identity/service-accounts Service accounts, service account API keys, last_used_at, API key list filters No Service accounts pages, Linked account on Create API key
Provider guides (six pages) Token exchange, issuer and rule validation per provider All three; aws_sts needs the optional AWS dependency in each SDK Connect workload tiles and rule fields, Register issuer, Edit issuer
info/workload-identity/migrate-from-api-keys Token exchange, GET /auth/context All three Connect workload, Authentication events, API keys list
info/workload-identity/reference Everything, including the management endpoints and discovery documents All three No
info/workload-identity/troubleshooting Token exchange errors, authentication events, issuer key check All three Authentication events, Check signing keys
info/api-keys (changes) API key list filters and status=expired; service account API keys No Federation prompt, Linked account, list filters and status tabs
info/api-key-permissions, start/quickstart, info/projects, introduction/manage, reference/cli/*, reference/mcp-server/authentication (changes) Federation being available Federation support No

Compatibility with other docs changes

  • The IP allowlisting docs are merged into this branch. The API key comparison and the "when an API key is still a reasonable choice" guidance now mention limiting a key to IP ranges.
  • The open change that expands scoped key permissions rewrites the top of info/api-key-permissions, so it conflicts with the retitle and new intro here. Whichever merges second needs a small manual merge in that file's header. Existing link text that says "API key permissions" in info/api-keys is left as is to avoid widening that conflict.

Testing

  • mint broken-links: no broken links found.
  • mint dev: all 12 new pages and 8 changed pages return 200 with no parse errors in the server log.
  • Internal anchors: every /page#anchor link in the changed files resolves to a heading on the target page.
  • Code samples: all 16 TypeScript, 16 Python, and 16 Go snippets on the new pages type-check against the SDK sources with federation support (tsc, pyright, go vet).
  • The sequence diagram renders with the Mermaid CLI.
  • No screenshots are included; dashboard steps are described in text with the labels from the UI.

Add an API authentication chooser, a workload identity federation section
(overview, service accounts, six provider guides, a migration guide,
reference, and troubleshooting), and point the API key pages, quickstart,
CLI, and MCP authentication pages at federation for non-interactive
workloads.
@mintlify

mintlify Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

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

Project Status Preview Updated
Kernel 🟢 Ready View Preview Nov 19, 2026, 11:15 PM

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

…wlists

The permissions page now covers federation rules and service account API
keys as well as scoped API keys, so it is titled Scoping Permissions and
opens with where policies apply. The API key comparison and guidance
mention limiting a key to IP ranges.

@ulziibay-kernel ulziibay-kernel left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the full diff (21 files) and checked it against the current SDK sources, provider documentation, and the Mintlify preview. This is a strong PR: the structure is right, the writing is clear, and every technical claim I could verify checks out. Findings below are nits; nothing blocks once the merge gates in the description clear.

What I verified independently

  • All internal links and anchors in the 21 changed files resolve (scripted check over every ](...) and href=), and docs.json covers all 12 new pages.
  • Code samples match the SDK sources on main in all three languages: exported names (oidcFederationProvider, identityTokenFromValue/StaticIdentityToken, exchangeFederationAssertion/exchange_federation_assertion, option.IdentityTokenFile, awssts.IdentityToken, etc.), env vars and the fallback order for identity token sources, credential precedence (API key wins with one warning; both-in-code throws in TS/Python and last-wins in Go; the missing-source failure point per SDK), refresh thresholds (min(120s, 40%) advisory / min(30s, 10%) blocking), the single 401 retry, exchange result fields, auth.context fields, and the API key list filters including project_id="org" and the status values.
  • Provider facts: aws iam enable-outbound-web-identity-federation and the account issuer URL shape, GitHub OIDC claims (repository_id/repository_owner_id, jti, the repo:owner@id/name@id:ref: subject), Entra v1.0/v2.0 issuer+audience pairs, uti as the token ID, the idtyp optional-claim requirement, the GCP numeric uniqueId subject and absent jti, and the Kubernetes projected-token audience pitfall.
  • The new card icons (aws, microsoft, dharmachakra, right-left, fingerprint) all resolve on the preview deployment.

Findings

  1. info/api-key-permissions.mdx — the retitle re-scopes the page, but the body still speaks only of keys. The new intro says three credential kinds share the policy format, while the Resources section still says "Resources must be inside the new key's organization, or its project for a project-scoped key. Kernel checks that every object ID exists when you create the key" (wrong subject for rules and service account keys), the Conditions section says "To restrict a whole key…", and the section heading "Not available to scoped keys" now reads oddly since service account keys and rules are also restricted. A light pass replacing "key" with "credential" where the statement applies to all three would finish the job the retitle started.

  2. info/authentication.mdx — the "If it leaks" row is ambiguous on first read. "It works until you revoke it: from any machine, or from inside the IP ranges you limited it to." The second half reads like a contradiction until you realize it means "unless you set an IP allowlist". Something like "from any machine — or only from the IP ranges you limited it to, if you set them" would be clearer.

  3. Question — reference "Who can call it" vs the SDKs. The page says the management endpoints accept only a signed-in person: no API key and no federated token. All three SDKs ship WorkloadIdentityIssuer/WorkloadIdentityAuthenticationEvent (and service account) resources, and SDK clients can only authenticate with an API key or federation. If the docs are right, those SDK resources are unreachable; if the API actually accepts admin keys for reads, the "No API key can call them" paragraph overstates. One of the two probably deserves a tweak — worth confirming which.

  4. Nit: info/workload-identity/overview.mdx opens with "Use it for every workload that isn't a person at a keyboard", but pools, app deployments/invocations, and API key management are closed to service accounts (covered later on the same page and on the authentication page). A pointer at the "every workload" claim would keep readers who only skim the intro from planning a migration the closures block.

Everything else — the merge gate in the description, the deliberate IP-allowlist integration, and the conflict callout for the scoped-permissions PR — looks right.

@sjmiller609

Copy link
Copy Markdown
Contributor

[automation] A review has been submitted by another reviewer, but I haven't looked at this PR yet, so I'm un-requesting my review. If you want me to also review, no problem just re-request it! Thanks.

@sjmiller609
sjmiller609 removed their request for review November 19, 2026 22:44
… the management API

The permissions page now says credential where a rule applies to keys, federation rules and service account keys alike. The leak comparison row and the overview's opening claim are clearer. The management API is described as not currently accessible with an API key or a federated token.

@ulziibay-kernel ulziibay-kernel left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed 82f976e against my earlier findings — all four are addressed, and the anchor/link check still passes across the changed files.

  • api-key-permissions.mdx: the "credential's boundary" phrasing now matches the intro table, and the rest of the page speaks of credentials. ✔
  • authentication.mdx: the "If it leaks" row now parses on first read. ✔
  • Management API: listing the endpoints as reference-only with the explicit 403 for API keys and federated tokens (including through the SDK methods) resolves my question — the SDK resources just mirror the spec, and the docs are the accurate side. ✔
  • Overview opener now points at the service-account closures before telling readers to migrate. ✔

One residual hair, not worth blocking on: "A credential with a policy gets 403 with insufficient_scope" — a project-scoped key without a policy is also blocked from these endpoints (they're not covered by the actions at all), so the criterion is really "scoped credentials" rather than "credentials with a policy". If you want to close that edge, "A scoped credential gets…" or "A credential limited to a project…" does it.

Approving from the docs side; the merge gates in the description still apply.

@rgarcia
rgarcia merged commit 9cd63ed into main Nov 19, 2026
3 checks passed
@rgarcia
rgarcia deleted the hypeship/wif-docs branch November 19, 2026 23:18

This branch was successfully deployed

1 active deployment
staging — da9a3d06 Deployed Nov 19, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants