DKE API
Die authentifizierte Management-API zum Bereitstellen und Betreiben von DKE-365-Diensten sowie die öffentlichen DKE-Protokollendpunkte, die Microsoft 365 / Office direkt aufruft.
Die DKE-365-API hat zwei Endpunktfamilien. Die Management-API (/api/dke/…) ist mit einer Cockpit-Benutzersitzung authentifiziert und durch Operations.Dke.*-Berechtigungen gesteuert; sie stellt DKE-Dienste bereit, konfiguriert und betreibt sie. Das öffentliche DKE-Protokoll (/dke/…, ohne /api-Präfix) ist die Oberfläche, die Microsoft Office zum Ver- und Entschlüsseln von Inhalten aufruft.
| Familie | Basispfad | Auth | Zweck |
|---|---|---|---|
| Management-API | /api/dke/… | Cockpit-Benutzersitzung (JWT), Operations.Dke.*-Berechtigungen | DKE-Dienste bereitstellen, konfigurieren und verwalten |
| Öffentliches DKE-Protokoll | /dke/… (ohne /api) | GetKey ist öffentlich; Decrypt validiert ein Azure-AD-Bearer-Token | Die Endpunkte, die Microsoft 365 / Office direkt aufruft |
Management-API
Authentifiziert mit einer Cockpit-Benutzersitzung (JWT). Jede Route erfordert die angegebene Operations.Dke.*-Berechtigung.
| Methode + Pfad | Zweck | Berechtigung |
|---|---|---|
GET /api/dke/services | DKE-Dienste auflisten | Operations.Dke.Read |
POST /api/dke/services | Einen neuen Dienst bereitstellen | Operations.Dke.Create |
POST /api/dke/services/validate-key | Validieren, dass ein Schlüssel DKE-fähig ist (RSA-2048/4096) | Operations.Dke.Create |
GET /api/dke/services/{id} | Einen Dienst abrufen | Operations.Dke.Read |
PUT /api/dke/services/{id} | Einen Dienst aktualisieren | Operations.Dke.Update |
DELETE /api/dke/services/{id} | Einen Dienst löschen | Operations.Dke.Delete |
POST /api/dke/services/{id}/enable | Aktivieren (und die Azure-AD-App automatisch bereitstellen) | Operations.Dke.Enable |
POST /api/dke/services/{id}/disable | Deaktivieren | Operations.Dke.Disable |
POST /api/dke/services/{id}/stop | Stoppen | Operations.Dke.Disable |
POST /api/dke/services/{id}/rotate-key | Den RSA-Schlüssel rotieren (mit Überlappungsfenster) | Operations.Dke.Update |
GET /api/dke/services/{id}/health | Gesundheitsstatus eines Dienstes | Operations.Dke.Read |
GET /api/dke/services/{id}/deploy-config | Die Client-Deploy-Konfiguration herunterladen | Operations.Dke.Read |
GET /api/dke/services/{id}/onboarding | DNS-/CNAME-Onboarding-Anleitung | Operations.Dke.Read |
POST /api/dke/provision-azure-app | Die Azure-AD-App eigenständig bereitstellen | Operations.Dke.Create |
GET /api/dke/defaults | Assistenten-Standardwerte (Basisdomäne, Audience-Domäne, Standard-IdP) | (nur Auth) |
POST /api/dke/resolve-domain(s) | B2B-Partnerdomänen zu gültigen Ausstellern auflösen | Operations.Dke.Read |
Es gibt keinen separaten „Registrierungs"-Endpunkt — Registrierung = Bereitstellen → Aktivieren. Bei /api/dke/services/{id}/enable ruft Cockpit v2, falls der Dienst eine identity_provider_id hat und noch keine Azure-App besitzt, Microsoft Graph auf, um die Azure-AD-App-Registrierung zu erstellen, und speichert die resultierenden Werte azure_client_id, azure_audience und azure_app_object_id.
Beispiel-Deploy-Anfrage
{
"name": "Contoso DKE",
"slug": "89c3b193-af16-4887-8031-43f88d475d9d",
"key_id": "<rsa-key-uuid>",
"key_name": "dke_key",
"azure_tenant_id": "<azure-tenant-guid>",
"azure_client_id": "<app-guid>",
"azure_audience": "https://89c3b193-af16-4887-8031-43f88d475d9d.duokey365.com",
"allowed_domains": ["partner.com"],
"algorithm": "RSA-OAEP-256",
"cache_duration_hours": 24,
"mtls_enabled": false,
"allow_anonymous": false,
"access_policy_id": "<policy-uuid>",
"identity_provider_id": "<idp-uuid>"
}
Öffentliches Protokoll
Die Endpunkte, die Microsoft Office direkt aufruft, bereitgestellt ohne das /api-Präfix. Ein Dienst wird über seinen slug (eine GUID) adressiert. GetKey ist öffentlich — jeder kann den veröffentlichten öffentlichen Schlüssel abrufen. Decrypt validiert ein Azure-AD-Bearer-Token (und setzt die gebundene Zugriffsrichtlinie des Dienstes durch), bevor entpackt wird.
| Methode + Pfad | Name | Auth | Zweck |
|---|---|---|---|
GET /dke/{slug}/version | Version | Öffentlich | Protokoll-/Dienstversionsprüfung |
GET /dke/{slug}/{key_id} | GetKey | Öffentlich | Den veröffentlichten öffentlichen RSA-JWK zurückgeben, der zum Verschlüsseln von Inhalten verwendet wird |
POST /dke/{slug}/{key_id}/decrypt | Decrypt | Azure-AD-Bearer-Token | Einen umschlossenen Schlüssel mit dem im Vault gehaltenen privaten Schlüssel entpacken |
Legacy-kid-Name-Varianten von GetKey und Decrypt werden ebenfalls bedient, bei denen der Schlüssel über key_name statt key_id adressiert wird, um zur kid-URL zu passen, die Office möglicherweise zwischengespeichert hat. Der veröffentlichte kid ist die vollständige Dienst-URL, https://{slug}.{base-domain}/dke/{slug}/{key_name}/{key_id}.
Nur ein Dienst im Status Running bedient Decrypt-Anfragen. Decrypt löst den Dienst über slug auf, wählt den effektiven Schlüssel (aktuell oder, während des Rotations-Überlappungsfensters, den vorherigen Schlüssel), führt optional eine mTLS-Validierung durch, validiert das Azure-AD-JWT, setzt die gebundene Zugriffsrichtlinie durch und entschlüsselt dann per RSA-OAEP über den Vault-Adapter. Der private Schlüssel verlässt den Vault niemals.
Protokolldetails
Eigenheiten des veröffentlichten JWK
Der von GetKey zurückgegebene öffentliche Schlüssel ist ein Standard-RSA-JWK, folgt jedoch den DKE-Eigenheiten von Microsoft — Clients (und jede Neuimplementierung) müssen genau diese erwarten:
| Feld | Wert / Kodierung |
|---|---|
n | Der RSA-Modulus, kodiert als Standard-Base64 (nicht base64url) |
e | Der öffentliche Exponent als Ganzzahl (z. B. 65537), keine base64url-Zeichenkette |
alg | RS256 |
kid | Die vollständige Dienst-Schlüssel-URL |
Decrypt-Anfrage-/Antwortkörper
Der Decrypt-Endpunkt nimmt den umschlossenen Schlüssel entgegen und gibt den entpackten Schlüssel zurück. Werte sind Base64-kodiert.
{
"alg": "RSA-OAEP-256",
"value": "<base64 ciphertext>"
}
{
"value": "<base64 plaintext>"
}
Jede Entschlüsselung wird pro Client-IP im Krypto-Tarif ratenbegrenzt (1000 Anfragen/Minute).
Verwandt: Oracle-TDE-PKCS#11-Proxy
Für Oracle Transparent Data Encryption stellt DuoKey einen separaten PKCS#11-Proxy-Endpunkt bereit, POST /api/apps/{app_id}/tde/pkcs11/{access_guid}, authentifiziert ausschließlich über das in seiner URL eingebettete access_guid-Bearer-Token. Details finden Sie in der Oracle-TDE-Integrationsanleitung.