Document additionalAuthorizationParams with Google refresh-token example#731
Document additionalAuthorizationParams with Google refresh-token example#731
Conversation
Add coverage for the additionalAuthorizationParams field on upstream OIDC and OAuth 2.0 providers, using Google's access_type=offline as the motivating refresh-token recipe. Extend the existing Google OIDC example, and add a dedicated subsection to the Kubernetes auth guide covering scope interaction with the default offline_access scope. Closes #726 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
Documents how to use additionalAuthorizationParams for upstream OIDC/OAuth2 providers in the embedded authorization server, motivated by Google’s requirement for access_type=offline to obtain refresh tokens.
Changes:
- Extends the existing Google OIDC example to set explicit scopes and add
additionalAuthorizationParams.access_type: 'offline'. - Adds a new “Upstream-specific authorization parameters” section with a standalone Google example and a note about default-scope interaction (
offline_access).
| additionalAuthorizationParams: | ||
| access_type: 'offline' |
There was a problem hiding this comment.
For Google, access_type=offline is necessary but refresh tokens are typically only returned the first time the user consents; subsequent logins often require prompt=consent (or revoking prior consent) to get a refresh token again. Consider adding prompt: 'consent' under additionalAuthorizationParams or explicitly noting this limitation so readers don't assume access_type=offline alone guarantees a refresh token.
There was a problem hiding this comment.
in other words, this means that existing users who already logged in wouldn't magically get a refresh token, but would need to wait for their token to expire. It seemed better than require a consent every time. But I don't really mind one way or the other.
| upstreamProviders: | ||
| - name: google | ||
| type: oidc | ||
| oidcConfig: | ||
| issuerUrl: 'https://accounts.google.com' | ||
| clientId: '<YOUR_GOOGLE_CLIENT_ID>' | ||
| clientSecretRef: | ||
| name: upstream-idp-secret | ||
| key: client-secret | ||
| scopes: | ||
| - openid | ||
| - profile | ||
| additionalAuthorizationParams: | ||
| access_type: 'offline' |
There was a problem hiding this comment.
The example YAML here starts at upstreamProviders: without showing the surrounding MCPExternalAuthConfig / spec.embeddedAuthServer structure. Consider either (a) including the minimal enclosing keys (or ... placeholders) to make it clear where this snippet belongs, or (b) labeling it explicitly as a partial snippet; otherwise readers may copy/paste it as-is and end up with an invalid manifest.
| upstreamProviders: | |
| - name: google | |
| type: oidc | |
| oidcConfig: | |
| issuerUrl: 'https://accounts.google.com' | |
| clientId: '<YOUR_GOOGLE_CLIENT_ID>' | |
| clientSecretRef: | |
| name: upstream-idp-secret | |
| key: client-secret | |
| scopes: | |
| - openid | |
| - profile | |
| additionalAuthorizationParams: | |
| access_type: 'offline' | |
| apiVersion: toolhive.stacklok.dev/v1alpha1 | |
| kind: MCPExternalAuthConfig | |
| metadata: | |
| name: external-auth-config | |
| spec: | |
| embeddedAuthServer: | |
| upstreamProviders: | |
| - name: google | |
| type: oidc | |
| oidcConfig: | |
| issuerUrl: 'https://accounts.google.com' | |
| clientId: '<YOUR_GOOGLE_CLIENT_ID>' | |
| clientSecretRef: | |
| name: upstream-idp-secret | |
| key: client-secret | |
| scopes: | |
| - openid | |
| - profile | |
| additionalAuthorizationParams: | |
| access_type: 'offline' |
| additionalAuthorizationParams: | ||
| access_type: 'offline' |
There was a problem hiding this comment.
Same as the earlier Google snippet: if the goal is to help users obtain refresh tokens reliably, consider adding prompt: 'consent' (or a short note explaining when it's needed) alongside access_type: 'offline', since Google often only returns a refresh token on the first consent without an explicit re-consent prompt.
Add a "First consent only" note explaining that access_type=offline issues a refresh token on the user's first consent only, and point to prompt=consent as the opt-in escape hatch when that's not enough. Addresses review feedback on PR #731. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add a title= attribute to the standalone upstreamProviders YAML block in the "Upstream-specific authorization parameters" subsection so readers recognize it as a partial configuration to nest inside an MCPExternalAuthConfig, matching the pattern used for other close-up snippets in this guide. Addresses review feedback on PR #731. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Description
Document the
additionalAuthorizationParamsfield on upstream OIDC and OAuth 2.0 providers in the embedded authorization server. Google'saccess_type=offlinemechanism is the motivating example — without it, Google won't issue refresh tokens even ifoffline_accessis in the scopes.Changes to
docs/toolhive/guides-k8s/auth-k8s.mdx:additionalAuthorizationParams: access_type: 'offline', reorder scopes toopenid, email, profile, and add a comment explaining why scopes must be set explicitly in this case.### Upstream-specific authorization parameterssubsection at the end of Approach 5 with a standalone example and a "Scope interaction" note covering the defaultoffline_accessscope conflict.The CRD reference page (
docs/toolhive/reference/crd-spec.md) is autogenerated from the toolhive Go types, so it'll update automatically once stacklok/toolhive#4862 ships.Type of change
Related issues/PRs
Closes #726
Depends on stacklok/toolhive#4862 — do not merge this PR until that change ships in a ToolHive release so docs don't reference a field that isn't yet available to users.
Submitter checklist
Content and formatting