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:
- [ ] 1. CSRF secret: Session Manager and ExtAuthZ
- [ ] 2. Client data signing keys: ExtAuthZ and CMK
Tenants, regions and queues:
- [ ] 3. Tenant job queues: Registry and CMK
- [ ] 4. CMK region name: Registry, tenants and CMK
- [ ] 5. Task queues of a system region: CMK and the provider's systems
- [ ] 6. Task queues of the Bridge: CMK and the CMK-2-Krypton Bridge
- [ ] 7. Bridge registration: CMK-2-Krypton Bridge and Registry
Sign-in and the CMK UI:
- [ ] 8. Issuer: the identity provider, the Registry and CMK
- [ ] 9. Callback and UI addresses: the identity provider, Session Manager, the CMK UI and the gateway
- [ ] 10. Group names: the identity provider and CMK
- [ ] 11. Cookie names and session paths: Session Manager, ExtAuthZ and the CMK UI
Krypton:
- [ ] 12. Client identities: the Krypton root node and its clients
- [ ] 13. Agent name: the Krypton root node and each agent
- [ ] 14. Release: the Krypton root node and its agents
- [ ] 15. Workload certificates: Krypton and the workloads
Secrets and keys
1. CSRF secret
Session Manager and ExtAuthZ: the same secret, byte for byte
- Settings: Session Manager
sessionManager.csrfSecret; ExtAuthZcsrfSecret. - 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
401andCSRF 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.
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 -sha256Details: 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. CMKclientData.signingKeysPath, the directory with the public keys. - Rule: the key ID file names the active key, for example
key1. ExtAuthZ has the private keykey1.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 thatkidand verifies the signature. - If they differ: CMK rejects every API request with
500 NO_BUSINESS_DATA. Its log showspublic key not found or invalidwhen it has no public key with that name, andcrypto/rsa: verification errorwhen the two keys are not a pair. When ExtAuthZ cannot read its private key, every allowed request fails at the gateway with500 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.
# 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_idCheck 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:
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 -sha256Details: 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.targetandsource; the CMK of that regiontenantManager.amqp.sourceandtarget. - Rule: the Registry's
targetis CMK'ssource(the jobs), and CMK'stargetis the Registry'ssource(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.
# 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.repliesDetails: 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'sregioninRegisterTenant, or the CMK-2-Krypton Bridge'sconfig.registry.regionfor the tenants it onboards; CMKlandscape.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_ERRORwithno matching orbital target manager found for region. A differentlandscape.regiongives the systems a wrongcmk_regionin 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.targetandamqp.source; the system'sregionin 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
regionequals the systems'regionin the Registry. Itstargetis where the service reads tasks, itssourcewhere 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'sconfig.orbital.amqp.sourceandtarget; the bindings on the broker that connect them. - Rule: what CMK publishes to
targetreaches the queue that the Bridge reads assource, and what the Bridge publishes to itstargetreaches the queue that CMK reads assource. The target'sregionequals the Bridge'sconfig.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.
# 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.repliesDetails: CMK-2-Krypton Bridge configuration.
7. Bridge registration
CMK-2-Krypton Bridge and Registry: region and system type
- Settings: the Bridge's
config.registry.regionandconfig.registry.systemType; the Registry'sorbital.targets[].regionand itsSystem.Typevalidation rule. - Rule:
regionis 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.systemTypemust pass the Registry'sSystem.Typerule. - 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
issuerproperty of the tenant'sApplyAuthin the Registry; theissuerof the identity provider's discovery document and of its tokens; CMKclientData.authContextFields, which must containissuer. - Rule: the issuer is the same string everywhere, character for character, including a trailing
/. - If they differ: sign-in fails with
500andissuer does not matchin Session Manager's log. WithoutissuerinauthContextFields, 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
callbackURLandallowedRedirectBaseURLs; the redirect URIs registered at each identity provider; CMK UIconfig.apiBaseUrl; the allowed origin in the CORS settings of the gateway's CMKSecurityPolicy. - Rule:
callbackURL, for examplehttps://api.example.com/sm/callback, is registered at every tenant's identity provider.allowedRedirectBaseURLsand the CORS origin name the CMK UI, for examplehttps://ui.example.com.apiBaseUrlis the one host that serves both/cmk/v1and/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
groupsclaim that the tenant's identity provider sends; the group identifiers in CMK, for exampleKMS_TenantAdministrator_<tenant>. - Rule: the identity provider sends the groups under exactly the names that CMK knows, in the
groupsclaim. - 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.
11. Cookie names and session paths
Session Manager, ExtAuthZ and the CMK UI: keep the fixed names
- Settings: Session Manager
sessionCookieTemplate.nameandcsrfCookieTemplate.name; ExtAuthZsessionPathPrefixes. - Rule: keep the session cookie name
__Host-Http-SESSIONand the CSRF cookie nameCSRF: ExtAuthZ reads__Host-Http-SESSION-<tenant>, and the CMK UI readsCSRF-<tenant>.sessionPathPrefixesis/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 examplekryptonid://example.org/node/agent-eu10. The certificates are signed by the CA in the root node'sserver.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
namein its bootstrap configuration; on the root node, the segmentnameintopology.segments, the entry inconnectionsand, with mutual TLS, the entry inauth.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 exampleKRYPTON_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
mainbranch. - 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
GetwithPermissionDenied.
Details: Use keys in a workload and KMIP.