Aller au contenu principal

API DKE

L'API de gestion authentifiée pour déployer et exploiter les services DKE 365, et les endpoints publics du protocole DKE que Microsoft 365 / Office appellent directement.

S'applique à :
DuoKey Cockpit v2Double Key EncryptionMicrosoft Purview / MIP

L'API DKE 365 comporte deux familles d'endpoints. L'API de gestion (/api/dke/…) est authentifiée par une session utilisateur Cockpit et soumise aux permissions Operations.Dke.* ; elle déploie, configure et exploite les services DKE. Le protocole DKE public (/dke/…, sans préfixe /api) est la surface que Microsoft Office appelle pour chiffrer et déchiffrer le contenu.

FamilleChemin de baseAuthentificationObjet
API de gestion/api/dke/…Session utilisateur Cockpit (JWT), permissions Operations.Dke.*Déployer, configurer et gérer les services DKE
Protocole DKE public/dke/… (sans /api)GetKey est public ; Decrypt valide un jeton porteur Azure ADLes endpoints que Microsoft 365 / Office appellent directement

API de gestion​

Authentifiée par une session utilisateur Cockpit (JWT). Chaque route requiert la permission Operations.Dke.* indiquée.

Méthode + CheminObjetPermission
GET /api/dke/servicesLister les services DKEOperations.Dke.Read
POST /api/dke/servicesDéployer un nouveau serviceOperations.Dke.Create
POST /api/dke/services/validate-keyValider qu'une clé est compatible DKE (RSA-2048/4096)Operations.Dke.Create
GET /api/dke/services/{id}Obtenir un serviceOperations.Dke.Read
PUT /api/dke/services/{id}Mettre à jour un serviceOperations.Dke.Update
DELETE /api/dke/services/{id}Supprimer un serviceOperations.Dke.Delete
POST /api/dke/services/{id}/enableActiver (et auto-provisionner l'app Azure AD)Operations.Dke.Enable
POST /api/dke/services/{id}/disableDésactiverOperations.Dke.Disable
POST /api/dke/services/{id}/stopArrêterOperations.Dke.Disable
POST /api/dke/services/{id}/rotate-keyFaire tourner la clé RSA (avec fenêtre de chevauchement)Operations.Dke.Update
GET /api/dke/services/{id}/healthSanté d'un serviceOperations.Dke.Read
GET /api/dke/services/{id}/deploy-configTélécharger la configuration de déploiement clientOperations.Dke.Read
GET /api/dke/services/{id}/onboardingGuide d'intégration DNS / CNAMEOperations.Dke.Read
POST /api/dke/provision-azure-appProvisionner l'app Azure AD de façon autonomeOperations.Dke.Create
GET /api/dke/defaultsValeurs par défaut de l'assistant (domaine de base, domaine d'audience, IdP par défaut)(authentification uniquement)
POST /api/dke/resolve-domain(s)Résoudre les domaines partenaires B2B en émetteurs validesOperations.Dke.Read
Remarque

Il n'existe pas d'endpoint d'« enregistrement » distinct — enregistrement = déployer → activer. Sur /api/dke/services/{id}/enable, si le service a un identity_provider_id et pas encore d'app Azure, Cockpit v2 appelle Microsoft Graph pour créer l'enregistrement de l'app Azure AD et stocke les azure_client_id, azure_audience et azure_app_object_id résultants.

Exemple de requête de déploiement​

POST /api/dke/servicesJSON

{
"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>"
}

Protocole public​

Les endpoints que Microsoft Office appelle directement, servis sans le préfixe /api. Un service est adressé par son slug (un GUID). GetKey est public — n'importe qui peut récupérer la clé publique publiée. Decrypt valide un jeton porteur Azure AD (et applique la politique d'accès liée du service) avant de dégager la clé.

Méthode + CheminNomAuthentificationObjet
GET /dke/{slug}/versionVersionPublicSonde de version du protocole / service
GET /dke/{slug}/{key_id}GetKeyPublicRenvoyer la JWK publique RSA publiée utilisée pour chiffrer le contenu
POST /dke/{slug}/{key_id}/decryptDecryptJeton porteur Azure ADDégager une clé enveloppée à l'aide de la clé privée détenue par le vault
Remarque

Des variantes héritées de GetKey et Decrypt adressées par kid sont également servies, où la clé est adressée par key_name plutôt que par key_id, afin de correspondre au kid URL qu'Office peut avoir mis en cache. Le kid publié est l'URL complète du service, https://{slug}.{base-domain}/dke/{slug}/{key_name}/{key_id}.

Attention

Seul un service au statut Running sert les requêtes de déchiffrement. Decrypt résout le service par slug, sélectionne la clé effective (courante, ou la clé précédente pendant la fenêtre de chevauchement de rotation), effectue une validation mTLS optionnelle, valide le JWT Azure AD, applique la politique d'accès liée, puis déchiffre en RSA-OAEP via l'adaptateur de vault. La clé privée ne quitte jamais le vault.

Détails du protocole​

Particularités de la JWK publiée​

La clé publique renvoyée par GetKey est une JWK RSA standard, mais suit les particularités DKE de Microsoft — les clients (et toute réimplémentation) doivent s'attendre exactement à ceci :

ChampValeur / encodage
nLe module RSA, encodé en Base64 standard (pas en base64url)
eL'exposant public sous forme d'entier (par ex. 65537), et non une chaîne base64url
algRS256
kidL'URL complète de la clé de service

Corps de requête / réponse Decrypt​

L'endpoint Decrypt prend la clé enveloppée et renvoie la clé dégagée. Les valeurs sont en Base64.

POST /dke/{slug}/{key_id}/decrypt — requêteJSON

{
"alg": "RSA-OAEP-256",
"value": "<base64 ciphertext>"
}
RéponseJSON

{
"value": "<base64 plaintext>"
}

Chaque déchiffrement est limité en débit par tenant (100 requêtes/seconde par défaut, configurable).

Voir aussi : proxy PKCS#11 Oracle TDE​

Pour Oracle Transparent Data Encryption, DuoKey expose un endpoint proxy PKCS#11 distinct, POST /api/apps/{app_id}/tde/pkcs11/{access_guid}, authentifié uniquement par le jeton porteur access_guid intégré dans son URL. Voir le guide d'intégration Oracle TDE pour plus de détails.

Voir aussi