المصادقة والطلبات والاستجابات

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

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

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

نوع الكائن	لاحقة URL
المفاتيح المحمية بالبرامج	/المفاتيح
مفاتيح محمية بـ HSM	/المفاتيح
Secrets	/secrets
Certificates	/ الشهادات

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

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

بنية عنوان URL للطلب

تستخدم عمليات إدارة المفاتيح أفعال HTTP بما في ذلك DELETE و GET و PATCH و PUT. تستخدم عمليات التشفير على الكائنات الرئيسية الموجودة HTTP POST.

بالنسبة للعملاء الذين لا يستطيعون دعم أفعال HTTP محددة، يسمح Azure Key Vault باستخدام HTTP POST مع رأس X-HTTP-REQUEST لتحديد الفعل المقصود. عند استخدام POST كبديل (على سبيل المثال، بدلا من DELETE)، قم بتضمين نص فارغ للطلبات التي لا تتطلب عادة واحدا.

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

• لإنشاء مفتاح يسمى 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://<vault-name>.vault.azure.net/
  • بالنسبة ل HSMs المدارة: https://{HSM-name}.managedhsm.azure.net/ يتم تخزين المفاتيح دائما ضمن مسار /keys، بينما يتم تخزين الأسرار دائما ضمن مسار /secrets.

إصدارات واجهة برمجة التطبيقات المعتمدة

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

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

متطلبات نص الطلب

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

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

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

تنسيق نص الاستجابة

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

استخدام HTTP POST كبديل

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

معالجة استجابات الأخطاء

تستخدم معالجة الأخطاء رموز حالة 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 ID.

يجب إرسال رموز الوصول المميزة إلى الخدمة باستخدام عنوان تخويل 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-Authenticate هي:

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

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

إشعار

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