Document authServerRef field and combined auth patterns#702
Document authServerRef field and combined auth patterns#702tgrunnagle wants to merge 3 commits intomainfrom
Conversation
Implements changes for issue #671: - Update auth-k8s.mdx to use authServerRef as primary example in Step 5 - Add backward compatibility note for externalAuthConfigRef - Add combined embedded auth + AWS STS section in aws-sts.mdx - Add authServerRef configuration section in embedded-auth-server.mdx - Update MCPServer vs VirtualMCPServer table with authServerRef info - Add combined auth pattern reference in backend-auth.mdx
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
| resources: | ||
| limits: | ||
| cpu: '500m' | ||
| memory: 512Mi | ||
| memory: '512Mi' | ||
| requests: | ||
| cpu: 100m | ||
| memory: 128Mi | ||
| cpu: '100m' | ||
| memory: '128Mi' |
There was a problem hiding this comment.
Are the resource settings actually relevant to the topic/example? Consider removing if not - or validate that these are in fact the right recommended resources for MCPRemoteProxy; I think these are the same as carried forward from other full MCPServer examples.
|
|
||
| audit: | ||
| enabled: true | ||
|
|
||
| resources: | ||
| limits: | ||
| cpu: '500m' | ||
| memory: '512Mi' | ||
| requests: | ||
| cpu: '100m' | ||
| memory: '128Mi' |
There was a problem hiding this comment.
Are the audit and resource settings actually relevant to the example? Consider removing if not.
danbarr
left a comment
danbarr
left a comment
There was a problem hiding this comment.
The content and accuracy of the new authServerRef documentation looks good, but the placement of the new "Combine embedded auth with AWS STS" section in aws-sts.mdx needs fixing before this merges.
The section is inserted between Step 4 and Step 5 of the numbered tutorial. A reader following the main path hits an advanced/optional topic mid-flow before completing the tutorial. It should sit after all the main tutorial steps are complete - either after Step 5 or at the end of the page before "Next steps" - as an optional advanced section.
Low-priority: the new authServerRef section in concepts/embedded-auth-server.mdx states "This is the preferred configuration method" in the opening sentence and then restates "The authServerRef field is the preferred way to configure the embedded auth server" two paragraphs later. One instance can be dropped.
| embedded authorization server, and `oidcConfig` validates the JWTs that the | ||
| embedded authorization server issues. Unlike approaches 1-3 where `oidcConfig` | ||
| points to an external identity provider, here it points to the embedded | ||
| authorization server itself—the `oidcConfig` issuer must match the `issuer` in |
There was a problem hiding this comment.
Remove em dash
| authorization server itself—the `oidcConfig` issuer must match the `issuer` in | |
| authorization server itself. The `oidcConfig` issuer must match the `issuer` in |
| [Set up embedded authorization server authentication](../guides-k8s/auth-k8s.mdx#set-up-embedded-authorization-server-authentication) | ||
| (steps 1 through 4). Then deploy the `MCPRemoteProxy` with both references: | ||
|
|
||
| ```yaml {10-12,14-15} title="aws-mcp-remote-proxy-combined.yaml" |
There was a problem hiding this comment.
Highlight is misaligned. Tip: using the # highlight-start and # highlight-end comments is usually easier than using the numbered indicators (especially for LLMs that can't count).
| ```yaml {10-12,14-15} title="aws-mcp-remote-proxy-combined.yaml" | |
| ```yaml {10-12,15-16} title="aws-mcp-remote-proxy-combined.yaml" |
| but `authServerRef` is preferred for consistency. When you need both incoming | ||
| and outgoing auth on the same resource, you must use `authServerRef` for the | ||
| embedded auth server so that `externalAuthConfigRef` remains available for the | ||
| outgoing auth configuration. |
There was a problem hiding this comment.
should we document the old way if we want to make it obsolete more or less?
| configuration separate from outgoing auth types like AWS STS or token exchange. | ||
| If you need both incoming and outgoing auth on the same resource, you must use | ||
| `authServerRef` for the embedded auth server so that `externalAuthConfigRef` | ||
| remains available for the outgoing auth configuration. |
There was a problem hiding this comment.
same comment about only documenting our preferred way of configuring the authserver
| embedded auth server. This separates the two configurations so they don't | ||
| compete for the same field: | ||
| Use `authServerRef` for the embedded auth server and `externalAuthConfigRef` for | ||
| outgoing auth (such as AWS STS) on the same resource. This is the primary use |
There was a problem hiding this comment.
I know the reason you did all the work was AWS STS, but should we make it more explicit that any outgoing auth can be configured using the same mechanism?
3 participants
Closes #671
Summary
Document the new
authServerReffield onMCPServerandMCPRemoteProxyresources, which separates embedded authorization server configuration (incoming auth) fromexternalAuthConfigRef(outgoing auth). This enables configuring both the embedded auth server and an outgoing auth type like AWS STS on the same resource, as introduced in RFC-0050.Changes made
Kubernetes auth guide (
guides-k8s/auth-k8s.mdx)authServerRefas the primary configuration field, with highlighted YAML showingkindandnameexternalAuthConfigRefwithtype: embeddedAuthServerstill worksauthServerRef+externalAuthConfigRefas the primary patternauthServerRef.nameandexternalAuthConfigRef.nameEmbedded auth server concept page (
concepts/embedded-auth-server.mdx)authServerRef" section explaining the field, itsTypedLocalObjectReferencesyntax, and when to use it vs.externalAuthConfigRefauthServerRefand add a "Combined auth" rowauthServerRefis not available onVirtualMCPServerAWS STS integration tutorial (
integrations/aws-sts.mdx)MCPRemoteProxyYAML example showingauthServerRefandexternalAuthConfigReftogetherBackend auth concept page (
concepts/backend-auth.mdx)Testing
npm run buildto verify all pages build without errorsnpm run startauthServerRefsyntax withkindandnameAdditional notes
externalAuthConfigRefwithtype: embeddedAuthServercontinues to work and is explicitly documented as backward compatible.reference/crd-spec.md) is not modified here; it will be regenerated from the toolhive repo.