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

Merged
jhrozek merged 2 commits into from
Feb 18, 2026
+690 −2
Merged

Add AWS STS authentication tutorial and cross-references #550

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8afe588
Add AWS STS authentication tutorial and cross-references
jhrozek Feb 13, 2026
67e46d5
Address PR review feedback on AWS STS tutorial
jhrozek Feb 16, 2026
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.

## 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
[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`
Loading