Add AWS STS authentication tutorial and cross-references by jhrozek · Pull Request #550 · stacklok/docs-website

jhrozek · 2026-02-13T15:18:38Z

Description

Tutorial covering end-to-end setup of ToolHive as an authentication proxy for the AWS MCP Server on Kubernetes. Users register their OIDC provider with AWS IAM, create IAM roles with the aws-mcp permission model, configure MCPExternalAuthConfig with type: awsSts, and deploy an MCPRemoteProxy pointing to the AWS MCP Server endpoint.

Type of change

New documentation

Related issues/PRs

#510

Screenshots

N/A

Submitter checklist

Content and formatting

I have reviewed the content for technical accuracy
I have reviewed the content for spelling, grammar, and style

Navigation

New pages include a frontmatter section with title and description at a minimum
Sidebar navigation (sidebars.ts) updated for added, deleted, reordered, or renamed files
Redirects added to vercel.json for moved, renamed, or deleted pages (i.e., if the URL slug changed)

Reviewer checklist

Content

I have reviewed the content for technical accuracy
I have reviewed the content for spelling, grammar, and style

Tutorial covering end-to-end setup of ToolHive as an authentication proxy for the AWS MCP Server on Kubernetes. Users register their OIDC provider with AWS IAM, create IAM roles with the aws-mcp permission model, configure MCPExternalAuthConfig with type: awsSts, and deploy an MCPRemoteProxy pointing to the AWS MCP Server endpoint. Also adds cross-references from existing token exchange and remote proxy docs so readers discover the AWS-specific auth path: - concepts/backend-auth: mention AWS STS in the federation section, add "Built-in AWS STS support" subsection - guides-k8s/token-exchange-k8s: link in Related information - guides-k8s/remote-mcp-proxy: tip admonition after token exchange section Fixes: #510

vercel · 2026-02-13T15:21:14Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Feb 13, 2026 3:21pm

Copilot

Pull request overview

Adds new ToolHive documentation describing how to use AWS STS (via OIDC) to authenticate to the AWS MCP Server, and links to this new tutorial from existing Kubernetes/token-exchange documentation and the sidebar navigation.

Changes:

Added a new end-to-end tutorial for AWS STS authentication to the AWS MCP Server on Kubernetes.
Updated Docusaurus sidebar to include the new tutorial.
Added cross-references/tips in existing token exchange, remote proxy, and backend-auth concept docs.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
`sidebars.ts`	Adds the new AWS STS tutorial to the Tutorials sidebar navigation.
`docs/toolhive/tutorials/aws-sts-integration.mdx`	New tutorial covering AWS IAM OIDC provider setup, role/policy examples, and ToolHive resources for AWS STS-based auth.
`docs/toolhive/guides-k8s/token-exchange-k8s.mdx`	Links token exchange guide readers to the AWS STS tutorial.
`docs/toolhive/guides-k8s/remote-mcp-proxy.mdx`	Adds a tip steering AWS users toward `type: awsSts` and the new tutorial.
`docs/toolhive/concepts/backend-auth.mdx`	Adds conceptual mention of built-in AWS STS support and links to the tutorial.

Copilot · 2026-02-13T15:25:25Z

docs/toolhive/tutorials/aws-sts-integration.mdx

+        "Federated": "arn:aws:iam::<YOUR_AWS_ACCOUNT_ID>:oidc-provider/<YOUR_OIDC_ISSUER_HOST>"
+      },


The OIDC provider ARN placeholder <YOUR_OIDC_ISSUER_HOST> is likely misleading for issuers that include a path (common with Okta/Keycloak). In AWS, the oidc-provider/... segment must match the provider URL without the scheme and including any path; consider renaming the placeholder and clarifying this here.

Copilot · 2026-02-13T15:25:25Z

docs/toolhive/tutorials/aws-sts-integration.mdx

+spec:
+  type: awsSts
+  awsSts:
+    region: <YOUR_AWS_REGION>


The docs now instruct users to set spec.type: awsSts with an awsSts: block, but the current CRD reference lists MCPExternalAuthConfigSpec.type enum values without awsSts and doesn’t document an awsSts field (see docs/toolhive/reference/crd-spec.md around the MCPExternalAuthConfigSpec table). Either update the CRD reference (and ensure the operator actually supports awsSts), or gate this tutorial behind the ToolHive version that introduces it.

Copilot · 2026-02-13T15:25:25Z

docs/toolhive/guides-k8s/remote-mcp-proxy.mdx

+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


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 · 2026-02-13T15:25:26Z

docs/toolhive/tutorials/aws-sts-integration.mdx

+```bash
+aws iam create-open-id-connect-provider \
+  --url https://<YOUR_OIDC_ISSUER> \
+  --client-id-list <YOUR_OIDC_AUDIENCE>
+```


aws iam create-open-id-connect-provider typically requires --thumbprint-list, and the placeholder usage is inconsistent: the command hard-codes https:// but the <YOUR_OIDC_ISSUER> example below includes https://..., which would lead to a doubled scheme if copied literally. Update the command/placeholders to be unambiguous and include the required thumbprint input.

Copilot · 2026-02-13T15:25:26Z

docs/toolhive/tutorials/aws-sts-integration.mdx

+        "StringEquals": {
+          "<YOUR_OIDC_ISSUER_HOST>:aud": "<YOUR_OIDC_AUDIENCE>"
+        }


Similarly, the IAM trust policy condition key should match the full OIDC provider identifier (host plus any issuer path) used when creating the provider (for example issuer.example.com/oauth2/default:aud). Clarify that <...>:aud must include the same path portion if present.

Copilot · 2026-02-13T15:25:26Z

docs/toolhive/tutorials/aws-sts-integration.mdx

+  --auth-method client_secret_basic \
+  --response-mode form_post \
+  --response-types code \
+  --pkce | jq -r '.access_token')


This example pipes oauth2c output through jq, but the tutorial doesn’t mention jq as a prerequisite. Add it to prerequisites or show an alternative that doesn’t require jq.

Copilot · 2026-02-13T15:25:26Z

docs/toolhive/guides-k8s/token-exchange-k8s.mdx

+  services, ToolHive has built-in STS support using `MCPExternalAuthConfig` with
+  `type: awsSts`


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 · 2026-02-13T15:25:27Z

docs/toolhive/concepts/backend-auth.mdx

+### 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.
+


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.

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.

Copilot · 2026-02-13T15:25:27Z

docs/toolhive/tutorials/aws-sts-integration.mdx

+  [Kubernetes quickstart guide](./quickstart-k8s.mdx))
+- `kubectl` configured to access your cluster
+- An AWS account with permissions to create IAM roles, policies, and OIDC
+  identity providers


The tutorial uses aws CLI commands later, but the prerequisites don’t mention installing/configuring the AWS CLI (and credentials for running IAM commands). Add AWS CLI as an explicit prerequisite so readers can follow Step 1/2 without getting blocked.

Suggested change

identity providers

identity providers

- The AWS CLI installed and configured with IAM credentials that can create

IAM roles, policies, and OIDC identity providers

Copilot AI review requested due to automatic review settings February 13, 2026 15:18

Copilot started reviewing on behalf of jhrozek February 13, 2026 15:19 View session

Copilot AI reviewed Feb 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add AWS STS authentication tutorial and cross-references#550

Add AWS STS authentication tutorial and cross-references#550
jhrozek wants to merge 1 commit intomainfrom
aws_sts

jhrozek commented Feb 13, 2026

Uh oh!

vercel bot commented Feb 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 13, 2026

Uh oh!

Copilot AI Feb 13, 2026

Uh oh!

Copilot AI Feb 13, 2026

Uh oh!

Copilot AI Feb 13, 2026

Uh oh!

Copilot AI Feb 13, 2026

Uh oh!

Copilot AI Feb 13, 2026

Uh oh!

Copilot AI Feb 13, 2026

Uh oh!

Copilot AI Feb 13, 2026

Uh oh!

danbarr Feb 13, 2026

Uh oh!

Copilot AI Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		"Federated": "arn:aws:iam::<YOUR_AWS_ACCOUNT_ID>:oidc-provider/<YOUR_OIDC_ISSUER_HOST>"
		},

		services, ToolHive has built-in STS support using `MCPExternalAuthConfig` with
		`type: awsSts`

Conversation

jhrozek commented Feb 13, 2026

Description

Type of change

Related issues/PRs

Screenshots

Submitter checklist

Content and formatting

Navigation

Reviewer checklist

Content

Uh oh!

vercel bot commented Feb 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

danbarr Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants