DKE Troubleshooting
This chapter focuses on Double Key Encryption (DKE) for Microsoft 365: the path from an Office client, through Microsoft Purview sensitivity labels, to your on-premise DuoKey DKE key endpoint (served by the Cockpit API container).
The diagnostic approach here is aligned with Microsoft's official DKE troubleshooting guidance, adapted for a containerized, on-premise DuoKey deployment where the DKE service is served by the Cockpit API pod behind the OpenShift Ingress Router.
How DKE fits together
Purview supplies the DKE endpoint URL, the Office client acquires an Entra token, then fetches the public key from the DuoKey endpoint. Content is double-encrypted with the Microsoft key and your DKE key.
Two keys protect the content: the Microsoft-managed key and your DKE key, which never leaves your on-premise endpoint. If either side of this flow breaks, users cannot apply or open DKE-protected content.
Step 1 — Is the DKE key endpoint reachable?
The fastest first test. From a client network, open the key URL in a browser:
https://<dke-endpoint>/<keyname>
- Expected: a JSON response containing the public key (
kid,key, key metadata). - Nothing / timeout / connection refused: network, DNS, ingress, or pod problem.
Cluster-side checks:
oc get route -n duokey # is the DKE route present?
oc get pods -n duokey -l app=duokey-cockpit-api # is the Cockpit API pod Running/Ready?
oc logs -n duokey -l app=duokey-cockpit-api --tail=200
curl -I https://<dke-endpoint>/<keyname> # status + TLS
| Symptom | Likely cause | Resolution |
|---|---|---|
| Connection refused / timeout | Firewall / DNS / no route | Allow 443 to the endpoint; verify public DNS resolves to the LB; check the OpenShift route |
| 502 / 503 | No healthy Cockpit API pod | Fix the Cockpit API pods first (oc describe, oc logs) |
404 on /<keyname> | Wrong key name | Confirm the key name matches the deployed key configuration |
Step 2 — TLS / certificate trust
DKE clients require a valid, trusted TLS certificate on the endpoint.
| Symptom | Cause | Resolution |
|---|---|---|
certificate not trusted in browser/Office | Endpoint uses an untrusted/private CA | Use a certificate trusted by clients, or distribute your internal CA to clients |
| Handshake failure / reset | TLS version / cipher mismatch | Align the Ingress tlsSecurityProfile with client requirements (Network Security) |
| Name mismatch | Cert CN/SAN ≠ endpoint hostname | Reissue the cert with the correct SAN |
Step 3 — Authentication (Entra ID)
DKE authorizes key requests using an Entra ID (Azure AD) token. Most "can't get the key" errors are issuer/audience mismatches.
Check the DKE service's Azure AD identity settings, configured per service in
the Cockpit console (Cockpit v2 stores this on the DKE service record in
the database — there is no appsettings.json or ConfigMap involved):
| Setting | Must match |
|---|---|
| Azure AD tenant ID | Your Entra ID tenant |
| Client / application ID | The DKE application registered in Entra ID |
| Audience | The App ID URI / client ID the JWT is issued for |
| Allowed domains | The B2B domain(s) whose users are allowed to request keys |
# Inspect the deployed DKE service's identity settings in the Cockpit console
# (Service details → Azure AD identity), or via the Cockpit API.
| Symptom | Cause | Resolution |
|---|---|---|
| 401 Unauthorized | Tenant/audience mismatch, or no/expired token | Correct the tenant ID / audience on the DKE service; confirm the Entra app registration |
| 403 Forbidden | User's domain not in the allowed list | Add the user's domain to the DKE service's allowed domains |
| Works for admin, not users | Authorization scoping | Review the allowed domains / access policy on the DKE service |
Ensure the DKE app registration in Entra ID exists, exposes the expected audience/App ID URI, and that admin consent has been granted. An issuer/audience mismatch is the single most common DKE failure.
Step 4 — Sensitivity label configuration (Purview)
The DKE sensitivity label must point at your endpoint and be published.
- In Microsoft Purview, the DKE label's encryption settings must contain the
exact DKE endpoint URL (
https://<dke-endpoint>). - The label policy must be published to the target users.
- Allow time for label/policy propagation to clients.
| Symptom | Cause | Resolution |
|---|---|---|
| Label missing in Office | Policy not published / not propagated | Publish the policy; wait for sync; sign out/in |
| Label applies but content unreadable elsewhere | Endpoint not reachable for that user | Re-check Steps 1–3 from the affected network |
| Wrong endpoint | URL typo in the label | Correct the DKE endpoint URL on the label |
Step 5 — Office client
| Symptom | Cause | Resolution |
|---|---|---|
| "Something went wrong" on applying/opening | Endpoint unreachable or auth failure | Run Steps 1 and 3 from the client's network |
| Older client can't use DKE | Build doesn't support DKE | Update to a DKE-capable Microsoft 365 Apps build |
| Intermittent failures after config change | Stale token / cache | Sign out and back in; clear the Office credential cache |
| Works online, fails offline | DKE requires endpoint access at open time | Endpoint must be reachable whenever protected content is opened |
End-to-end checklist
- Key endpoint returns JSON public key in a browser:
https://<dke-endpoint>/<keyname> - Cockpit API pods
Running/Ready; route present - TLS certificate valid and trusted by clients
- Entra ID tenant + audience match the DKE service's identity settings
- User is in the authorized users/group
- DKE label points at the correct endpoint and is published
- Office client is a DKE-capable build and can reach the endpoint
Escalating to DuoKey
Collect and send to [email protected]:
oc logs -n duokey -l app=duokey-cockpit-api --tail=500
oc get route,pods -n duokey
Include: the exact error, whether the browser key-endpoint test succeeds, the affected user(s), and any recent label or Entra ID changes.