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

[lucas-dclrcq]

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 to static values (rsa, prime256v1, secp256k1, secp384r1):

  - 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 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.:

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.

[benbz]

A discussion about this occurred on #1083. While we could add functionality to make the kid configurable, despite the docs it appears it is safe if the kid changes, however it is more seamless if existing keys are imported with their existing kid and the chart keys have their standard kid.

This could be done with (or by referencing the config in a secret with configSecret/configSecretKey rather than inline with config):

matrixAuthenticationService:
  additional:
    existing-keys.yaml:
      config: |
        secrets:
          keys:
          - kid: "my-existing-kid"
            key: <key>

This should get appended to the chart-managed secrets.keys array.

Given the workaround exists, this is low priority and not a migration blocker