element-hq / element-hq/ess-helm

Unable to configure custom KID for MAS signing keys, blocking migration from manual deployments

Open
#1,028 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
951
Forks
144
Avg merge
21h 32m
Merged PRs (30d)
65

Description

**Describe the bug**

When migrating from a manual MAS deployment to the ESS Helm chart, there is no way to configure custom `kid` (Key ID) values for the signing keys. The KIDs are hardcoded in [`config-overrides.yaml.tpl`](https://github.com/element-hq/ess-helm/blob/main/charts/matrix-stack/configs/matrix-authentication-service/config-overrides.yaml.tpl) to static values (`rsa`, `prime256v1`, `secp256k1`, `secp384r1`):

```yaml
- kid: rsa
key_file: /secrets/...
- kid: prime256v1
key_file: /secrets/...
```

While the key material itself can be provided via `matrixAuthenticationService.privateKeys.rsa.secretKey` (or `.value`), the KID cannot be overridden. This breaks migration from existing MAS deployments where keys were registered with different KIDs, as existing tokens/sessions become invalid when the KID changes.

The [MAS documentation](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html) states:
> A JWK Key ID is automatically derived from each key. To override this default, set `kid` to a custom value. The `kid` can be any case-sensitive string value as long as it is unique to this list; a key's `kid` value must be stable across restarts.

**To Reproduce**

1. Have an existing manual MAS deployment with signing keys using auto-derived or custom KIDs
2. Migrate to the ESS Helm chart, providing the same key material via `matrixAuthenticationService.privateKeys.rsa`
3. MAS starts with hardcoded `kid: rsa` instead of the original KID
4. Previously issued tokens/sessions fail validation because the KID in the JWT header no longer matches any known key

**Expected behavior**

The Helm chart should allow configuring custom `kid` values for each signing key, e.g.:

```yaml
matrixAuthenticationService:
privateKeys:
rsa:
kid: "my-existing-kid" # optional, defaults to "rsa" for backwards compatibility
secret: existing-secret
secretKey: key-in-secret
```

This would enable seamless migration from manual deployments by preserving the original KID values.

**Additional context**

- This is a migration blocker for anyone moving from a manual MAS deployment to the ESS Helm chart with pre-existing signing keys.
- The `values.yaml` `privateKeys` section currently only supports `value`, `secret`, and `secretKey` — there is no `kid` field.
- A simple fix would be to allow an optional `kid` override per key in `values.yaml` and use it in the template with a fallback to the current hardcoded values.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.