واجهة DKE (DKE API)
واجهة الإدارة المصادَق عليها لنشر خدمات DKE 365 وتشغيلها، ونقاط نهاية بروتوكول DKE العام التي يستدعيها Microsoft 365 / Office مباشرة.
تضم واجهة DKE 365 API عائلتَي نقاط نهاية. واجهة الإدارة (/api/dke/…) تتم المصادقة عليها بجلسة مستخدم Cockpit وتخضع لبوابة أذونات Operations.Dke.*؛ وهي تنشر خدمات DKE وتهيّئها وتشغّلها. أما بروتوكول DKE العام (/dke/…، دون بادئة /api) فهو السطح الذي يستدعيه Microsoft Office لتشفير المحتوى وفك تشفيره.
| العائلة | المسار الأساسي | المصادقة | الغرض |
|---|---|---|---|
| واجهة الإدارة (Management API) | /api/dke/… | جلسة مستخدم Cockpit (JWT)، أذونات Operations.Dke.* | نشر خدمات DKE وتهيئتها وإدارتها |
| بروتوكول DKE العام | /dke/… (بدون /api) | GetKey عامة؛ Decrypt يتحقق من رمز حامل خاص بـ Azure AD | نقاط النهاية التي يستدعيها Microsoft 365 / Office مباشرة |
واجهة الإدارة (Management API)
تتم المصادقة عليها بجلسة مستخدم Cockpit (JWT). يتطلب كل مسار إذن Operations.Dke.* المذكور.
| الطريقة + المسار | الغرض | الإذن |
|---|---|---|
GET /api/dke/services | سرد خدمات DKE | Operations.Dke.Read |
POST /api/dke/services | نشر خدمة جديدة | Operations.Dke.Create |
POST /api/dke/services/validate-key | التحقق من أن المفتاح مؤهَّل لـ DKE (RSA-2048/4096) | Operations.Dke.Create |
GET /api/dke/services/{id} | الحصول على خدمة | Operations.Dke.Read |
PUT /api/dke/services/{id} | تحديث خدمة | Operations.Dke.Update |
DELETE /api/dke/services/{id} | حذف خدمة | Operations.Dke.Delete |
POST /api/dke/services/{id}/enable | تفعيل (مع التزويد التلقائي لتطبيق Azure AD) | Operations.Dke.Enable |
POST /api/dke/services/{id}/disable | تعطيل | Operations.Dke.Disable |
POST /api/dke/services/{id}/stop | إيقاف | Operations.Dke.Disable |
POST /api/dke/services/{id}/rotate-key | تدوير مفتاح RSA (مع نافذة تداخل) | Operations.Dke.Update |
GET /api/dke/services/{id}/health | سلامة خدمة | Operations.Dke.Read |
GET /api/dke/services/{id}/deploy-config | تنزيل تهيئة النشر الخاصة بالعميل | Operations.Dke.Read |
GET /api/dke/services/{id}/onboarding | إرشادات الإعداد عبر DNS / CNAME | Operations.Dke.Read |
POST /api/dke/provision-azure-app | تزويد تطبيق Azure AD بشكل مستقل | Operations.Dke.Create |
GET /api/dke/defaults | القيم الافتراضية للمعالج (النطاق الأساسي، نطاق الجمهور، موفّر الهوية الافتراضي) | (مصادقة فقط) |
POST /api/dke/resolve-domain(s) | تحليل نطاقات شركاء B2B إلى مُصدرين صالحين | Operations.Dke.Read |
لا توجد نقطة نهاية منفصلة لـ«التسجيل» — التسجيل = نشر ← تفعيل. عند استدعاء /api/dke/services/{id}/enable، إذا كانت الخدمة تحمل identity_provider_id ولا يوجد بعد تطبيق Azure، يستدعي Cockpit v2 واجهة Microsoft Graph لإنشاء تسجيل تطبيق Azure AD ويخزّن قيم azure_client_id وazure_audience وazure_app_object_id الناتجة.
مثال على طلب النشر
{
"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>"
}
البروتوكول العام
نقاط النهاية التي يستدعيها Microsoft Office مباشرة، وتُقدَّم دون بادئة /api. يُعنوَن كل خدمة بواسطة slug الخاص بها (وهو GUID). GetKey عامة — يمكن لأي جهة جلب المفتاح العام المنشور. أما Decrypt فيتحقق من رمز حامل خاص بـ Azure AD (ويفرض سياسة الوصول المرتبطة بالخدمة) قبل فك التغليف.
| الطريقة + المسار | الاسم | المصادقة | الغرض |
|---|---|---|---|
GET /dke/{slug}/version | Version | عام | فحص إصدار البروتوكول / الخدمة |
GET /dke/{slug}/{key_id} | GetKey | عام | إرجاع مفتاح JWK العام لـ RSA المنشور المستخدم لتشفير المحتوى |
POST /dke/{slug}/{key_id}/decrypt | Decrypt | رمز حامل خاص بـ Azure AD | فك تغليف مفتاح مُغلَّف باستخدام المفتاح الخاص المحفوظ في الخزنة |
تُقدَّم أيضاً أصناف قديمة (legacy) من GetKey وDecrypt تُعنوَن بواسطة kid-بالاسم، حيث يُعنوَن المفتاح بواسطة key_name بدلاً من key_id، لمطابقة عنوان URL الخاص بـ kid الذي قد يكون Office قد خزّنه مؤقتاً. عنوان kid المنشور هو عنوان URL الكامل للخدمة، https://{slug}.{base-domain}/dke/{slug}/{key_name}/{key_id}.
لا تخدم طلبات فك التشفير إلا خدمة في حالة Running. يحدد Decrypt الخدمة بواسطة slug، ويختار المفتاح الفعّال (الحالي، أو المفتاح السابق أثناء نافذة تداخل التدوير)، وينفّذ تحققاً اختيارياً من mTLS، ويتحقق من JWT الخاص بـ Azure AD، ويفرض سياسة الوصول المرتبطة، ثم يفك التشفير بخوارزمية RSA-OAEP باستخدام محول الخزنة. لا يغادر المفتاح الخاص الخزنة أبداً.
تفاصيل البروتوكول
خصوصيات JWK المنشور
المفتاح العام الذي يُعيده GetKey هو JWK قياسي لـ RSA، لكنه يتبع خصوصيات DKE الخاصة بـ Microsoft — يجب على العملاء (وأي إعادة تنفيذ) توقع هذه الخصوصيات بالتحديد:
| الحقل | القيمة / الترميز |
|---|---|
n | مقياس RSA (modulus)، مُرمَّز بصيغة Base64 القياسية (وليس base64url) |
e | الأس العام (exponent) كـعدد صحيح (مثال: 65537)، وليس كسلسلة base64url |
alg | RS256 |
kid | عنوان URL الكامل لمفتاح الخدمة |
نص طلب / استجابة Decrypt
تأخذ نقطة نهاية Decrypt المفتاح المُغلَّف وتُعيد المفتاح بعد فك تغليفه. القيم بصيغة Base64.
{
"alg": "RSA-OAEP-256",
"value": "<base64 ciphertext>"
}
{
"value": "<base64 plaintext>"
}
يخضع كل طلب فك تشفير لتحديد المعدّل (rate limit) لكل مستأجر (القيمة الافتراضية 100 طلب/ثانية، قابلة للتهيئة).
ذو صلة: وكيل Oracle TDE PKCS#11
من أجل Oracle Transparent Data Encryption، يوفّر DuoKey نقطة نهاية منفصلة لوكيل PKCS#11، POST /api/apps/{app_id}/tde/pkcs11/{access_guid}، تتم المصادقة عليها فقط برمز access_guid الحامل المضمَّن في عنوان URL الخاص بها. راجع دليل تكامل Oracle TDE للتفاصيل.