Skip to content

Add AWS STS authentication tutorial and cross-references #550

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jhrozek wants to merge 1 commit into
base: main
Choose a base branch
from
+671 −2
Open

Add AWS STS authentication tutorial and cross-references #550

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions docs/toolhive/concepts/backend-auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,8 +110,9 @@ flowchart LR

When the backend service trusts a different IdP, but federation is configured
between the two IdPs, ToolHive can use the federated identity service to issue
short-lived tokens. An example is Google's Security Token Service (STS), which
can issue tokens for Google Cloud services based on your corporate identity.
short-lived tokens. Examples include Google's Security Token Service (STS) for
Google Cloud services and AWS STS for AWS services—both can issue tokens based
on your corporate identity.

```mermaid
flowchart LR
Expand Down Expand Up @@ -306,6 +307,16 @@ call and how that backend service accepts credentials:
obtaining tokens that the MCP server can use to access those APIs on behalf of
the user.

### Built-in AWS STS support

For AWS services like the
[AWS MCP Server](https://docs.aws.amazon.com/aws-mcp/), ToolHive has built-in
support for exchanging OIDC tokens for temporary AWS credentials using
`AssumeRoleWithWebIdentity`. This handles the STS exchange and SigV4 request
signing automatically, with claim-based IAM role selection. See the
[AWS STS integration tutorial](../tutorials/aws-sts-integration.mdx) for a
step-by-step setup guide.

Comment on lines +310 to +319
Copy link

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

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

This section claims built-in AWS STS support, but the current CRD spec documentation for MCPExternalAuthConfig doesn’t include an awsSts type/config. Please align this concept doc with the actual shipped CRD (or update the CRD reference docs in the same change) to avoid documenting unsupported configuration.

Suggested change
### Built-in AWS STS support
For AWS services like the
[AWS MCP Server](https://docs.aws.amazon.com/aws-mcp/), ToolHive has built-in
support for exchanging OIDC tokens for temporary AWS credentials using
`AssumeRoleWithWebIdentity`. This handles the STS exchange and SigV4 request
signing automatically, with claim-based IAM role selection. See the
[AWS STS integration tutorial](../tutorials/aws-sts-integration.mdx) for a
step-by-step setup guide.

Copilot uses AI. Check for mistakes.
Copy link
Collaborator

@danbarr danbarr Feb 13, 2026

Choose a reason for hiding this comment

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

I assume this (and other similar comments from Copilot) are because a release hasn't been cut with these new fields yet? That will auto-update the CRD reference.

## Related information

- For client authentication concepts, see
Expand Down
10 changes: 10 additions & 0 deletions docs/toolhive/guides-k8s/remote-mcp-proxy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -431,6 +431,16 @@ spec:
Now the proxy exchanges validated company tokens for remote service tokens
before forwarding requests.

:::tip[AWS services]

For AWS services like the AWS MCP Server, use `type: awsSts` instead of
`type: tokenExchange`. This exchanges OIDC tokens for temporary AWS credentials
via `AssumeRoleWithWebIdentity` and signs requests with SigV4. See the
Comment on lines +436 to +438
Copy link

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

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

This tip suggests switching MCPExternalAuthConfig.spec.type to awsSts, but the CRD reference currently doesn’t list awsSts as a supported enum value for MCPExternalAuthConfigSpec.type. Either update the reference/CRD docs alongside this change or add an explicit minimum ToolHive version requirement.

Suggested change
For AWS services like the AWS MCP Server, use `type: awsSts` instead of
`type: tokenExchange`. This exchanges OIDC tokens for temporary AWS credentials
via `AssumeRoleWithWebIdentity` and signs requests with SigV4. See the
In ToolHive installations where `MCPExternalAuthConfig.spec.type` supports the
`awsSts` mode (check your installed CRD or reference docs), you can use
`type: awsSts` instead of `type: tokenExchange` for AWS services like the AWS
MCP Server. This exchanges OIDC tokens for temporary AWS credentials via
`AssumeRoleWithWebIdentity` and signs requests with SigV4. See the

Copilot uses AI. Check for mistakes.
[AWS STS integration tutorial](../tutorials/aws-sts-integration.mdx) for
details.

:::

### Inject custom headers

Some remote MCP servers require custom headers for tenant identification, API
Expand Down
3 changes: 3 additions & 0 deletions docs/toolhive/guides-k8s/token-exchange-k8s.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,3 +261,6 @@ Key points in this example:
servers in Kubernetes
- [CRD specification](../reference/crd-spec.md) - complete CRD reference
including MCPExternalAuthConfig
- [AWS STS integration](../tutorials/aws-sts-integration.mdx) - for AWS
services, ToolHive has built-in STS support using `MCPExternalAuthConfig` with
`type: awsSts`
Comment on lines +265 to +266
Copy link

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

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

This guide recommends type: awsSts, but the CRD reference currently doesn’t list awsSts as a valid MCPExternalAuthConfigSpec.type value. Please update the CRD reference (or adjust the guidance) so readers don’t end up with manifests rejected by the API server.

Suggested change
services, ToolHive has built-in STS support using `MCPExternalAuthConfig` with
`type: awsSts`
services, ToolHive has built-in STS support; see this tutorial and the
MCPExternalAuthConfig CRD reference for the correct configuration

Copilot uses AI. Check for mistakes.
Loading
Loading