المصادقة والطلبات والردود

  • مقالة

يوفر Azure Key Vault نوعين من الحاويات لتخزين وإدارة الأسرار لتطبيقات السحابة الخاصة بك:

نوع الحاوية أنواع الكائنات المدعومة نقطة نهاية مستوى البيانات
خزائن
  • المفاتيح المحمية بالبرامج
  • مفاتيح محمية بـ HSM (مع Premium SKU)
  • الشهادات
  • مفاتيح حساب التخزين
 https://{vault-name}.vault.azure.net
HSM المدار
  • مفاتيح محمية بـ HSM
 https://{hsm-name}.managedhsm.azure.net

فيما يلي لاحقات URL المستخدمة للوصول إلى كل نوع من الكائنات

نوع الكائن لاحقة URL
المفاتيح المحمية بالبرامج /المفاتيح
مفاتيح محمية بـ HSM /المفاتيح
الأسرار /secrets
الشهادات / الشهادات
مفاتيح حساب التخزين / storageaccounts

يدعم Azure Key Vault الطلبات والاستجابات بتنسيق JSON. يتم توجيه الطلبات إلى Azure Key Vault إلى عنوان URL صالح لـ Azure Key Vault باستخدام HTTPS مع بعض معلمات URL ونصوص الطلبات والاستجابة المشفرة JSON.

يغطي هذا الموضوع تفاصيل خدمة Azure Key Vault. للحصول على معلومات عامة حول استخدام واجهات Azure REST، بما في ذلك المصادقة/التخويل وكيفية الحصول على رمز مميز للوصول، راجع مرجع Azure REST API.

عنوان URL الخاص بالطلب

تستخدم عمليات إدارة المفاتيح HTTP DELETE وGET وPATCH وPUT وHTTP POST وعمليات التشفير ضد الكائنات الرئيسية الحالية تستخدم HTTP POST. قد يستخدم العملاء الذين لا يمكنهم دعم أفعال HTTP معينة أيضًا HTTP POST باستخدام رأس X-HTTP-REQUEST لتحديد الفعل المقصود؛ الطلبات التي لا تتطلب عادةً جسمًا يجب أن تتضمن جسمًا فارغًا عند استخدام HTTP POST، على سبيل المثال عند استخدام POST بدلاً من DELETE.

للعمل مع الكائنات في Azure Key Vault، في ما يلي أمثلة على عناوين URLs:

  • لإنشاء مفتاح يسمى TESTKEY في Key Vault استخدم - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

  • لاستيراد مفتاح يسمى IMPORTEDKEY إلى استخدام Key Vault - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

  • للحصول على سر يسمى MYSECRET في استخدام Key Vault - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

  • لتوقيع ملخص باستخدام مفتاح يسمى TESTKEY في استخدام Key Vault - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

  • دائمًا ما تكون سلطة طلب Key Vault على النحو التالي،

    • بالنسبة للخزائن: https://{keyvault-name}.vault.azure.net/
    • بالنسبة ل HSMs المدارة: https://{HSM-name}.managedhsm.azure.net/

    يتم تخزين المفاتيح دائمًا تحت مسار / keys، بينما يتم تخزين الأسرار دائمًا تحت مسار / secrets.

إصدار API

تدعم خدمة Azure Key Vault إصدار البروتوكول لتوفير التوافق مع العملاء ذوي المستوى الأدنى، على الرغم من عدم توفر جميع الإمكانات لهؤلاء العملاء. يجب على العملاء استخدام معلمة api-version سلسلة الاستعلام لتحديد إصدار البروتوكول الذي يدعمونه حيث لا يوجد افتراضي.

تتبع إصدارات بروتوكول Azure Key Vault نظام ترقيم التاريخ باستخدام تنسيق {YYYY}. {MM}. {DD}.

نص الطلب

وفقًا لمواصفات HTTP، يجب ألا تحتوي عمليات GET على نص طلب، ويجب أن يكون لعمليات POST وPUT نص طلب. النص الأساسي في عمليات الحذف اختياري في HTTP.

ما لم يُذكر خلاف ذلك في وصف العملية، يجب أن يكون نوع محتوى نص الطلب application / json ويجب أن يحتوي على كائن JSON متسلسل متوافق مع نوع المحتوى.

ما لم يُذكر خلاف ذلك في وصف العملية، يجب أن يحتوي عنوان قبول الطلب على نوع وسائط التطبيق / json.

هيئة الاستجابة

ما لم يُذكر خلاف ذلك في وصف العملية، سيكون نوع محتوى نص الاستجابة لكل من العمليات الناجحة والفاشلة هو application / json ويحتوي على معلومات تفصيلية عن الخطأ.

باستخدام HTTP POST

قد لا يتمكن بعض العملاء من استخدام أفعال HTTP معينة، مثل التصحيح أو الحذف. يدعم Azure Key Vault HTTP POST كبديل لهؤلاء العملاء بشرط أن يتضمن العميل أيضًا رأس "X-HTTP-METHOD" لتحديد فعل HTTP الأصلي. تمت الإشارة إلى دعم HTTP POST لكل من واجهة برمجة التطبيقات API المحددة في هذا المستند.

الردود على الخطأ

ستستخدم معالجة الأخطاء رموز حالة HTTP. النتائج النموذجية هي:

  • 2xx - النجاح: يستخدم للتشغيل العادي. سيحتوي جسم الاستجابة على النتيجة المتوقعة

  • 3xx - إعادة التوجيه: قد يتم إرجاع 304 "غير معدل" لتحقيق GET شرطي. يمكن استخدام رموز 3xx الأخرى في المستقبل للإشارة إلى تغييرات DNS والمسار.

  • 4xx - خطأ في العميل: يُستخدم للطلبات السيئة، والمفاتيح المفقودة، وأخطاء بناء الجملة، والمعلمات غير الصالحة، وأخطاء المصادقة، وما إلى ذلك. وسيحتوي نص الاستجابة على شرح مفصل للخطأ.

  • 5xx - خطأ في الخادم: يُستخدم لأخطاء الخادم الداخلية. سيحتوي نص الاستجابة على معلومات موجزة عن الخطأ.

    تم تصميم النظام للعمل خلف وكيل أو جدار حماية. لذلك، قد يتلقى العميل رموز خطأ أخرى.

    يعرض Azure Key Vault أيضًا معلومات الخطأ في نص الاستجابة عند حدوث مشكلة. نص الاستجابة بتنسيق JSON ويتخذ الشكل:


{  
  "error":  
  {  
    "code": "BadArgument",  
    "message":  

      "’Foo’ is not a valid argument for ‘type’."  
    }  
  }  
}

المصادقة

يجب مصادقة جميع الطلبات إلى Azure Key Vault. يدعم Azure Key Vault الرموز المميزة للوصول إلى Microsoft Entra التي يمكن الحصول عليها باستخدام OAuth2 [RFC6749].

لمزيد من المعلومات حول تسجيل التطبيق الخاص بك والمصادقة لاستخدام Azure Key Vault، راجع تسجيل تطبيق العميل الخاص بك باستخدام معرف Microsoft Entra.

يجب إرسال الرموز المميزة للوصول إلى الخدمة باستخدام عنوان "تخويل HTTP":

PUT /keys/MYKEY?api-version=<api_version>  HTTP/1.1  
Authorization: Bearer <access_token>

عندما لا يتم توفير رمز وصول، أو عندما لا تقبل الخدمة رمزًا مميزًا، سيتم إرجاع خطأ HTTP 401 إلى العميل وسيتضمن رأس WWW-Authenticate، على سبيل المثال:

401 Not Authorized  
WWW-Authenticate: Bearer authorization="…", resource="…"

المعلمات الموجودة في رأس مصادقة WWW هي:

  • التخويل: عنوان خدمة التخويل OAuth2 التي يمكن استخدامها للحصول على رمز مميز للوصول للطلب.

  • المورد: اسم المورد ( https://vault.azure.net ) لاستخدامه في طلب التخويل.

إشعار

لا يوفر عملاء Key Vault SDK للأسرار والشهادات والمفاتيح في المكالمة الأولى لـ Key Vault رمز وصول لاسترداد معلومات المستأجر. من المتوقع تلقي HTTP 401 باستخدام عميل Key Vault SDK حيث يعرض Key Vault للتطبيق عنوان WWW-Authenticate الذي يحتوي على المورد والمستأجر حيث يحتاج إلى الانتقال وطلب الرمز المميز. إذا تم تكوين كل شيء بشكل صحيح، فستحتوي المكالمة الثانية من التطبيق إلى Key Vault على رمز مميز وستنجح.