Repository navigation
Document workload identity federation - #771
Conversation
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.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 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
left a comment
There was a problem hiding this comment.
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
](...)andhref=), anddocs.jsoncovers 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.contextfields, and the API key list filters includingproject_id="org"and thestatusvalues. - Provider facts:
aws iam enable-outbound-web-identity-federationand the account issuer URL shape, GitHub OIDC claims (repository_id/repository_owner_id,jti, therepo:owner@id/name@id:ref:subject), Entra v1.0/v2.0 issuer+audience pairs,utias the token ID, theidtypoptional-claim requirement, the GCP numericuniqueIdsubject and absentjti, and the Kubernetes projected-token audience pitfall. - The new card icons (
aws,microsoft,dharmachakra,right-left,fingerprint) all resolve on the preview deployment.
Findings
-
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. -
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. -
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. -
Nit:
info/workload-identity/overview.mdxopens 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.
|
[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. |
… 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
left a comment
There was a problem hiding this comment.
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
403for 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.
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
info/authenticationinfo/workload-identity/overviewinfo/workload-identity/service-accountsinfo/workload-identity/github-actionsinfo/workload-identity/awsaws_stssource, nested claims.info/workload-identity/google-cloudgcp_metadatasource, reuse behavior, claim conditions.info/workload-identity/microsoft-entrainfo/workload-identity/kubernetesinfo/workload-identity/custom-oidcinfo/workload-identity/migrate-from-api-keysinfo/workload-identity/referenceinfo/workload-identity/troubleshootingPages changed
docs.jsoninfo/authenticationand a Workload Identity Federation group (with a Providers subgroup) to Manage, ahead of API keys.info/api-keysstatusincludingexpired,principal_type,service_account_id,created_by,project_id) and the note thatactiveno longer includes expired keys; a Service account API keys section.info/api-key-permissionsstart/quickstartinfo/projectsintroduction/managereference/cli/authkernel loginorKERNEL_API_KEYand doesn't exchange workload identity tokens; use federation for SDK workloads.reference/cli/api-keysreference/mcp-server/authenticationWhat each page depends on
info/authenticationinfo/workload-identity/overviewGET /auth/context, authentication eventsinfo/workload-identity/service-accountslast_used_at, API key list filtersaws_stsneeds the optional AWS dependency in each SDKinfo/workload-identity/migrate-from-api-keysGET /auth/contextinfo/workload-identity/referenceinfo/workload-identity/troubleshootinginfo/api-keys(changes)status=expired; service account API keysinfo/api-key-permissions,start/quickstart,info/projects,introduction/manage,reference/cli/*,reference/mcp-server/authentication(changes)Compatibility with other docs changes
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" ininfo/api-keysis 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./page#anchorlink in the changed files resolves to a heading on the target page.tsc,pyright,go vet).