Setting the JWT signing key for production

MobilityManager signs authentication tokens with a symmetric JWT key. This key is security-critical: anyone who knows it can forge tokens, including SystemAdmin tokens. This article explains the requirements and how to set the key safely in production.

Requirements enforced at startup

Outside the Development environment, the application refuses to start unless Jwt:Key meets all of these conditions:

• It is present and non-empty.
• It is at least 32 bytes long.
• It is not one of the well-known committed default values.

If any check fails in Production, startup aborts with an InvalidOperationException stating that Jwt:Key must be a strong (≥32 byte) secret and must not be a committed default.

Warning: The placeholder keys shipped in .env.example and used for local development are explicitly blacklisted. They will pass the length check but are still rejected outside Development. Never reuse them.

Generate a strong key

Produce a random secret of at least 32 bytes. For example:

openssl rand -base64 48

Use the full output as the key value. Longer is fine; the minimum is 32 bytes.

Provide the key by environment

Docker Compose

Set JWT_KEY in your .env file. Both the development and production Compose files require it and fail fast if it is missing:

JWT_KEY=Zx8v...your-48-byte-random-value...==

Kubernetes

Store the key in the mobilitymanager-secrets Secret under Jwt__Key:

kubectl -n mobilitymanager-prod create secret generic mobilitymanager-secrets \
  --from-literal=Jwt__Key='Zx8v...your-random-value...==' \
  --dry-run=client -o yaml | kubectl apply -f -

Published deployment

Supply Jwt__Key as an environment variable from your process manager or secret store. Do not place it in a committed appsettings.json.

Optional issuer and audience

You can also set Jwt__Issuer and Jwt__Audience. If omitted, they default to CK.MobilityManager and CK.MobilityManager.Users respectively. Keep these consistent across all instances that validate the same tokens.

Note: Changing the signing key invalidates all previously issued tokens, forcing users to sign in again. Rotate deliberately and roll the new key out to every instance at once.

Related

• Configuring environment variables and the .env file
• Configuring the document encryption-at-rest key
• Production hardening checklist
• Troubleshooting a failed startup