Skip to content

Add Redis Sentinel session storage tutorial and TLS docs #606

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
Mar 16, 2026
Merged

Add Redis Sentinel session storage tutorial and TLS docs #606

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
e19f89a
Add Redis Sentinel session storage guide and TLS docs
jhrozek Mar 10, 2026
d952a6b
Address PR feedback: fix placeholder and remove redirect
jhrozek Mar 12, 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
8 changes: 5 additions & 3 deletions docs/toolhive/concepts/backend-auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -274,9 +274,11 @@ single ToolHive-issued JWT.
By default, session storage is in-memory only. Upstream tokens are lost when
pods restart, requiring users to re-authenticate. For production deployments,
configure Redis Sentinel as the storage backend for persistent, highly available
session storage. See the
[CRD specification](../reference/crd-spec.md#apiv1alpha1authserverstorageconfig)
for configuration details.
session storage. See
[Configure session storage](../guides-k8s/auth-k8s.mdx#configure-session-storage)
for a quick setup, or the full
[Redis Sentinel session storage](../guides-k8s/redis-session-storage.mdx)
tutorial for an end-to-end walkthrough.

:::

Expand Down
37 changes: 37 additions & 0 deletions docs/toolhive/guides-k8s/auth-k8s.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -527,6 +527,43 @@ authorization endpoints automatically.

:::

### Configure session storage

By default, the embedded authorization server stores sessions in memory.
Upstream tokens are lost when pods restart, requiring users to re-authenticate.
For production deployments, configure Redis Sentinel as the storage backend by
adding a `storage` block to your `MCPExternalAuthConfig`:

```yaml title="storage block for MCPExternalAuthConfig"
storage:
type: redis
redis:
sentinelConfig:
masterName: mymaster
sentinelService:
name: redis-sentinel
namespace: redis
aclUserConfig:
usernameSecretRef:
name: redis-acl-secret
key: username
passwordSecretRef:
name: redis-acl-secret
key: password
```

Create the Secret containing your Redis ACL credentials:

```bash
kubectl create secret generic redis-acl-secret \
--namespace toolhive-system \
--from-literal=username=toolhive-auth \
--from-literal=password="YOUR_REDIS_ACL_PASSWORD"
```

For a complete walkthrough including deploying Redis Sentinel from scratch, see
[Redis Sentinel session storage](./redis-session-storage.mdx).

### Using an OAuth 2.0 upstream provider

If your upstream identity provider does not support OIDC discovery, you can
Expand Down
Loading