Skip to content

Settings that must match ​

OpenKCM runs as several services that work together. Some settings therefore exist in two places: in two services, or in a service and a system outside OpenKCM, such as the message broker or the customer's identity provider. Both places must hold the same value. This page lists every such setting, what breaks when the two values differ, and how to check them.

Read this before you install, upgrade or rotate a secret

A service cannot see the other service's copy of a shared setting. A mismatch therefore rarely stops a service from starting. It shows up later, often only in production traffic: users who cannot sign in, API calls rejected with 401 or 500, tenants that stay in provisioning, or key changes that never reach a system. Check every item on this page when you install a deployment, add a region, upgrade a service or rotate a secret.

In the configuration references, each of these settings is marked with the label must match, and its section starts with a red box that links to this page.

Which services share what ​

Checklist ​

Secrets and keys:

Tenants, regions and queues:

Sign-in and the CMK UI:

Krypton:

Secrets and keys ​

1. CSRF secret ​

Session Manager and ExtAuthZ: the same secret, byte for byte

  • Settings: Session Manager sessionManager.csrfSecret; ExtAuthZ csrfSecret.
  • Rule: exactly the same bytes in both services, at least 32 bytes, from a cryptographic random generator. A trailing newline in one of the files is already a difference.
  • Why: Session Manager creates the CSRF token with its secret when a user signs in. ExtAuthZ checks the token with its own copy on every API call.
  • If they differ: users can sign in, but every API call from the CMK UI fails with 401 and CSRF token is not valid.
  • When you rotate it: put the same new value into the Secrets of both services, then restart both right after each other.

ExtAuthZ and Session Manager run in different namespaces, so the secret is kept in two Kubernetes Secrets. Create both from the same file, then compare them: the two hashes must be identical.

bash
kubectl -n envoy-gateway-system get secret csrf-secret -o jsonpath='{.data.csrf_secret}' | openssl dgst -sha256
kubectl -n services get secret csrf-secret -o jsonpath='{.data.csrf_secret}' | openssl dgst -sha256

Details: Shared CSRF secret.

2. Client data signing keys ​

ExtAuthZ and CMK: one key pair, one key ID

  • Settings: ExtAuthZ clientData.signingKeyIDFilePath, the key ID file, in a directory with the private keys. CMK clientData.signingKeysPath, the directory with the public keys.
  • Rule: the key ID file names the active key, for example key1. ExtAuthZ has the private key key1.pem; CMK has the matching public key under the same name, key1.pem. CMK never gets a private key.
  • Why: ExtAuthZ signs the client data of every allowed request with the private key and writes the key ID into it as kid. CMK selects the public key by that kid and verifies the signature.
  • If they differ: CMK rejects every API request with 500 NO_BUSINESS_DATA. Its log shows public key not found or invalid when it has no public key with that name, and crypto/rsa: verification error when the two keys are not a pair. When ExtAuthZ cannot read its private key, every allowed request fails at the gateway with 500 INTERNAL_SERVER_ERROR.
  • When you rotate it: give CMK the new public key first, then switch ExtAuthZ's key ID file, and remove the old public key last.
yaml
# ExtAuthZ configuration: signs
clientData:
  signingKeyIDFilePath: /etc/extauthz-signing/keyId   # content: key1, next to key1.pem (private)

# CMK configuration: verifies
clientData:
  signingKeysPath: /etc/signing-keys                  # key1.pem (public), the same file name
  authContextFields:
    - issuer
    - client_id

Check that the two halves are a pair: the public key derived from ExtAuthZ's private key and CMK's public key must give the same hash. For public keys in the BEGIN PUBLIC KEY format:

bash
kubectl -n envoy-gateway-system get secret extauthz-signing-keys-secret -o jsonpath='{.data.keyId}' | base64 -d; echo
kubectl -n envoy-gateway-system get secret extauthz-signing-keys-secret -o jsonpath='{.data.key1\.pem}' \
  | base64 -d | openssl pkey -pubout | openssl dgst -sha256
kubectl -n services get secret cmk-client-data-public-keys -o jsonpath='{.data.key1\.pem}' \
  | base64 -d | openssl pkey -pubin | openssl dgst -sha256

Details: Signing keys and Key rotation.

Tenants, regions and queues ​

3. Tenant job queues ​

Registry and CMK: one queue pair per CMK region, crossed over

  • Settings: Registry orbital.targets[].connection.amqp.target and source; the CMK of that region tenantManager.amqp.source and target.
  • Rule: the Registry's target is CMK's source (the jobs), and CMK's target is the Registry's source (the answers). Every CMK region has its own pair. Create the queues on the broker before the services start.
  • If they differ: registered tenants stay in STATUS_PROVISIONING, and no CMK serves them. A request queue shared by two regions sends tenants to the wrong region, because CMK does not check a tenant's region itself.
yaml
# Registry configuration
orbital:
  targets:
    - region: emea
      connection:
        amqp:
          target: /queues/cmk.emea.tenants           # = CMK tenantManager.amqp.source
          source: /queues/cmk.emea.tenants.replies   # = CMK tenantManager.amqp.target

# CMK configuration, region emea
tenantManager:
  amqp:
    source: /queues/cmk.emea.tenants
    target: /queues/cmk.emea.tenants.replies

Details: Registry targets and CMK tenantManager.

4. CMK region name ​

Registry, tenants and CMK: one name per CMK region

  • Settings: Registry orbital.targets[].region; the tenant's region in RegisterTenant, or the CMK-2-Krypton Bridge's config.registry.region for the tenants it onboards; CMK landscape.region.
  • Rule: the same name everywhere, for example emea. The tenant's region cannot be changed once the tenant is active.
  • If they differ: a tenant whose region has no Registry target goes to STATUS_PROVISIONING_ERROR with no matching orbital target manager found for region. A different landscape.region gives the systems a wrong cmk_region in their tasks.

Restrict the regions that the Registry accepts with a Tenant.Region rule in its validations, so a misspelled region is rejected at registration.

Details: Region configuration.

5. Task queues of a system region ​

CMK and the provider's systems: one target per system region

  • Settings: CMK eventProcessor.targets[]: region, amqp.target and amqp.source; the system's region in the Registry; the queues that the service reads and answers on in that region.
  • Rule: one target per system region in which the tenants of this CMK have systems. Its region equals the systems' region in the Registry. Its target is where the service reads tasks, its source where the service answers.
  • If they differ: tasks for a region without a target fail with target not configured for region. Tasks sent to a queue that no service reads are retried for about a day, then the system shows Failed to the customer.

Details: CMK eventProcessor and Connect a regional system.

6. Task queues of the Bridge ​

CMK and the CMK-2-Krypton Bridge: the Bridge's queues, through the broker

  • Settings: CMK eventProcessor.targets[] for the Bridge's region; the Bridge's config.orbital.amqp.source and target; the bindings on the broker that connect them.
  • Rule: what CMK publishes to target reaches the queue that the Bridge reads as source, and what the Bridge publishes to its target reaches the queue that CMK reads as source. The target's region equals the Bridge's config.registry.region.
  • If they differ: CMK's key and system tasks do not reach the Bridge. They are retried for about a day, then fail.
yaml
# CMK configuration
eventProcessor:
  targets:
    - region: eu10                                          # = Bridge config.registry.region
      amqp:
        target: /exchanges/cmk/eu10.krypton-bridge.requests # routed to the Bridge's source queue
        source: /queues/cmk.krypton-bridge.eu10.replies     # filled from the Bridge's target

# CMK-2-Krypton Bridge chart values
config:
  orbital:
    amqp:
      source: /queues/krypton-bridge.eu10.requests
      target: /exchanges/cmk/eu10.krypton-bridge.replies

Details: CMK-2-Krypton Bridge configuration.

7. Bridge registration ​

CMK-2-Krypton Bridge and Registry: region and system type

  • Settings: the Bridge's config.registry.region and config.registry.systemType; the Registry's orbital.targets[].region and its System.Type validation rule.
  • Rule: region is the CMK region of the tenants that the Bridge onboards and the region of the systems it registers, so the Registry needs a target with that name. systemType must pass the Registry's System.Type rule.
  • If they differ: the Bridge creates the keys in Krypton, but the registration in the Registry fails. The job still reports JOB_STATUS_DONE; only the Bridge's log shows the error, and the tenant is missing in the Registry.

Details: Onboard the tenant with Krypton.

Sign-in and the CMK UI ​

8. Issuer ​

The identity provider, the Registry and CMK: the exact issuer

  • Settings: the issuer property of the tenant's ApplyAuth in the Registry; the issuer of the identity provider's discovery document and of its tokens; CMK clientData.authContextFields, which must contain issuer.
  • Rule: the issuer is the same string everywhere, character for character, including a trailing /.
  • If they differ: sign-in fails with 500 and issuer does not match in Session Manager's log. Without issuer in authContextFields, CMK cannot list a user's tenants.

Details: Connect the identity provider and CMK clientData.

9. Callback and UI addresses ​

The identity provider, Session Manager, the CMK UI and the gateway

  • Settings: Session Manager callbackURL and allowedRedirectBaseURLs; the redirect URIs registered at each identity provider; CMK UI config.apiBaseUrl; the allowed origin in the CORS settings of the gateway's CMK SecurityPolicy.
  • Rule: callbackURL, for example https://api.example.com/sm/callback, is registered at every tenant's identity provider. allowedRedirectBaseURLs and the CORS origin name the CMK UI, for example https://ui.example.com. apiBaseUrl is the one host that serves both /cmk/v1 and /sm/*.
  • If they differ: the identity provider refuses the sign-in, Session Manager rejects the login and logout with 400, or the browser blocks the API calls of the CMK UI.

Details: Session Manager configuration and Install a regional deployment.

10. Group names ​

The identity provider and CMK: the exact group names

  • Settings: the groups claim that the tenant's identity provider sends; the group identifiers in CMK, for example KMS_TenantAdministrator_<tenant>.
  • Rule: the identity provider sends the groups under exactly the names that CMK knows, in the groups claim.
  • If they differ: users sign in, but CMK finds no role for them and rejects their requests with 403 ZERO_ROLES_NOT_ALLOWED.

Details: Give the first administrator access and Sign-in, groups and roles.

Session Manager, ExtAuthZ and the CMK UI: keep the fixed names

  • Settings: Session Manager sessionCookieTemplate.name and csrfCookieTemplate.name; ExtAuthZ sessionPathPrefixes.
  • Rule: keep the session cookie name __Host-Http-SESSION and the CSRF cookie name CSRF: ExtAuthZ reads __Host-Http-SESSION-<tenant>, and the CMK UI reads CSRF-<tenant>. sessionPathPrefixes is /cmk/v1/, the CMK API's base path.
  • If they differ: ExtAuthZ finds no session or the CMK UI finds no CSRF token, and the API calls of the CMK UI fail.

Details: Session Manager configuration.

Krypton ​

12. Client identities ​

Krypton root node and its clients: the identity in the certificate

  • Settings: the root node's auth.identity; the URI in the client certificate of each agent and of the CMK-2-Krypton Bridge (config.kryptonClient).
  • Rule: each client certificate has exactly one URI in its subject alternative names, and that URI is listed in auth.identity, for example kryptonid://example.org/node/agent-eu10. The certificates are signed by the CA in the root node's server.ca_path.
  • If they differ: the root node refuses the connection: agents cannot register, and the Bridge cannot create tenants and keys.

Details: Krypton security.

13. Agent name ​

Krypton root node and each agent: one name in four places

  • Settings: the agent's name in its bootstrap configuration; on the root node, the segment name in topology.segments, the entry in connections and, with mutual TLS, the entry in auth.identity.
  • Rule: the same name in all four places, for example agent-eu10. The sealer secrets that the key bindings of the agent's segment name, for example KRYPTON_TEK_KEY, are set on the agent.
  • If they differ: the root node refuses the registration and the agent exits.

Details: Agents.

14. Release ​

Krypton root node and its agents: the same release

  • Rule: run the root node and all agents from the same Krypton release. Release v0.1.0 uses another configuration format and agent protocol than the main branch.
  • If they differ: agents and the root node do not understand each other.

Details: Krypton.

15. Workload certificates ​

Krypton and the workloads: tenant ID and CA

  • Settings: the root node's kmip.tls.ca_path; the common name (CN) of each workload's client certificate; the CA that the workload trusts for the KMIP server.
  • Rule: the CN of a workload's certificate is the ID of the tenant whose keys it reads, and the certificate is signed by the CA in kmip.tls.ca_path. The workload trusts the CA of the KMIP server's certificate.
  • If they differ: the TLS handshake fails, or Krypton answers Get with PermissionDenied.

Details: Use keys in a workload and KMIP.

See also ​

EU and German government funding logos

Funded by the European Union – NextGenerationEU.

The views and opinions expressed are solely those of the author(s) and do not necessarily reflect the views of the European Union or the European Commission. Neither the European Union nor the European Commission can be held responsible for them.