مشاركة عبر

رموز خطأ Azure Key Vault REST API

  • مقالة

يمكن إرجاع رموز الخطأ التالية بواسطة عملية على خدمة ويب Azure Key Vault.

HTTP 401: طلب غير مصدق

401 يعني أن الطلب لم تتم مصادقته لـ Key Vault.

يتم مصادقة طلب إذا كان:

  • المخزن الرئيسي يعرف هوية المتصل،
  • يُسمح للمتصل بمحاولة الوصول إلى موارد Key Vault.

ثمة عدة أسباب لاحتمالية إعادة طلب الرمز 401.

لا يوجد رمز مميز للمصادقة مرفق بالطلب

فيما يلي مثال على طلب PUT، تعيين قيمة سر:

PUT https://putreqexample.vault.azure.net//secrets/DatabaseRotatingPassword?api-version=7.0 HTTP/1.1
x-ms-client-request-id: 03d275a2-52a4-4bed-82c8-6fe15165affb
accept-language: en-US
Authorization: Bearer     eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Im5iQ3dXMTF3M1hrQi14VWFYd0tSU0xqTUhHUSIsImtpZCI6Im5iQ3dXMTF3M1hrQi14VWFYd0tSU0xqTUhHUSJ9.eyJhdWQiOiJodHRwczovL3ZhdWx0LmF6dXJlLm5ldCIsImlzcyI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0Ny8iLCJpYXQiOjE1NDg2OTc1MTMsIm5iZiI6MTU0ODY5NzUxMywiZXhwIjoxNTQ4NzAxNDEzLCJhaW8iOiI0MkpnWUhoODVqaVBnZHF5ZlRGZE5TdHY3bGUvQkFBPSIsImFwcGlkIjoiZmFkN2Q1YjMtNjlkNi00YjQ4LTkyNTktOGQxMjEyNGUxY2YxIiwiYXBwaWRhY3IiOiIxIiwiaWRwIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3LyIsIm9pZCI6IjM5NzVhZWVkLTdkMDgtNDUzYi1iNmY0LTQ0NWYzMjY5ODA5MSIsInN1YiI6IjM5NzVhZWVkLTdkMDgtNDUzYi1iNmY0LTQ0NWYzMjY5ODA5MSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInV0aSI6IjItZ3JoUmtlSWs2QmVZLUxuNDJtQUEiLCJ2ZXIiOiIxLjAifQ.fgubiz1MKqTJTXI8dHIV7t9Fle6FdHrkaGYKcBeVRX1WtLVuk1QVxzIFDlZKLXJ7QPNs0KWpeiWQI9IWIRK-8wO38yCqKTfDlfHOiNWGOpkKddlG729KFqakVf2w0GPyGPFCONRDAR5wjQarN9Bt8I8YbHwZQz_M1hztlnv-Lmsk1jBmech9ujD9-lTMBmSfFFbHcqquev119V7sneI-zxBZLf8C0pIDkaXf1t8y6Xr8CUJDMdlWLslCf3pBCNIOy65_TyGvy4Z4AJryTPBarNBPwOkNAtjCfZ4BDc2KqUZM5QN_VK4foP64sVzUL6mSr0Gh7lQJIL5b1qIpJxjxyQ
User-Agent: FxVersion/4.7.3324.0 OSName/Windows OSVersion/6.2.9200.0 Microsoft.Azure.KeyVault.KeyVaultClient/3.0.3.0
Content-Type: application/json; charset=utf-8
Host: putreqexample.vault.azure.net
Content-Length: 31

{
   "value": "m*gBJ7$Zuoz)"
}

عنوان "التفويض" هو رمز الوصول المطلوب مع كل استدعاء لـ Key Vault لعمليات مستوى البيانات. إذا كان العنوان مفقوداً، فيجب أن تكون الاستجابة 401.

يفتقر الرمز المميز إلى المورد الصحيح المقترن به

عند طلب رمز وصول من نقطة نهاية Azure OAUTH، تكون معلمة تسمى "مورد" إلزامية. تعتبر القيمة مهمة لموفر الرمز المميز لأنها تحدد نطاق الرمز المميز للاستخدام المقصود. مورد جميع الرموز المميزة للوصول إلى Key Vault هو https://vault.keyvault.net (بدون شرطة مائلة).

انتهت صلاحية الرمز المميز

الرموز المميزة بترميز base64 ويمكن فك تشفير القيم في مواقع الويب مثل http://jwt.calebb.net. هنا هو الرمز المميز أعلاه الذي تم فك ترميزه:

    {
 typ: "JWT",
 alg: "RS256",
 x5t: "nbCwW11w3XkB-xUaXwKRSLjMHGQ",
 kid: "nbCwW11w3XkB-xUaXwKRSLjMHGQ"
}.
{
 aud: "https://vault.azure.net",
 iss: "https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/",
 iat: 1548697513,
 nbf: 1548697513,
 exp: 1548701413,
 aio: "42JgYHh85jiPgdqyfTFdNStv7le/BAA=",
 appid: "fad7d5b3-69d6-4b48-9259-8d12124e1cf1",
 appidacr: "1",
 idp: "https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/",
 oid: "3975aeed-7d08-453b-b6f4-445f32698091",
 sub: "3975aeed-7d08-453b-b6f4-445f32698091",
 tid: "72f988bf-86f1-41af-91ab-2d7cd011db47",
 uti: "2-grhRkeIk6BeY-Ln42mAA",
 ver: "1.0"
}.
[signature]

يمكننا أن نرى العديد من الأجزاء المهمة في هذا الرمز المميز:

  • aud (الجمهور): مورد الرمز المميز. لاحظ أن هذا هو https://vault.azure.net. لن يعمل هذا الرمز المميز لأي مورد لا يتطابق بشكل صريح مع هذه القيمة، مثل الرسم البياني.
  • iat (تم إصداره في): عدد العلامات منذ بداية الفترة عندما تم إصدار الرمز المميز.
  • nbf (ليس قبل ذلك): عدد العلامات منذ بداية الفترة عندما يصبح هذا الرمز المميز صالحاً.
  • exp (انتهاء الصلاحية): عدد العلامات منذ بداية الفترة عندما تنتهي صلاحية هذا الرمز المميز.
  • appid (معرف التطبيق): المعرف الفريد العمومي (GUID) لمعرف التطبيق الذي يقوم بهذا الطلب.
  • tid (معرّف المستأجر): المعرّف الفريد العمومي (GUID) لمعرّف المستأجر للمدير الرئيسي الذي يقوم بهذا الطلب

من المهم أن يتم تحديد جميع القيم بشكل صحيح في الرمز المميز حتى يعمل الطلب. إذا كان كل شيء صحيحا، فلن ينتج عن الطلب 401.

استكشاف الأخطاء وإصلاحها 401

يجب التحقيق في 401s من نقطة إنشاء الرمز المميز، قبل تقديم الطلب إلى المخزن الرئيسي. بشكل عام يتم استخدام التعليمة البرمجية لطلب الرمز المميز. بمجرد استلام الرمز المميز، يتم تمريره إلى طلب Key Vault. إذا كانت التعليمة البرمجية تعمل محلياً، فيمكنك استخدام Fiddler لالتقاط الطلب/الاستجابة لـ https://login.microsoftonline.com. يبدو الطلب كالتالي:


POST https://login.microsoftonline.com/<key vault tenant ID>/oauth2/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: login.microsoftonline.com
Content-Length: 192

resource=https%3A%2F%2Fvault.azure.net&client_id=<registered-app-ID>&client_secret=<registered-app-secret>&client_info=1&grant_type=client_credentials

يجب أن تكون المعلومات التالية التي قدمها المستخدم صحيحة:

  • معرف مستأجر المخزن الرئيسي
  • تم تعيين قيمة المورد إلى https%3A%2F%2Fvault.azure.net (عنوان URL المرمز)
  • معرّف العميل
  • سر العميل

تأكد من تطابق باقي الطلب تقريباً.

إذا كان يمكنك فقط الحصول على رمز الوصول إلى الاستجابة، يمكنك فك ترميزه لضمان معرف المستأجر ومعرف العميل (معرف التطبيق) والمورد.

HTTP 403: أذونات غير كافية

HTTP 403 يعني أن الطلب قد تمت مصادقته (يعرف هوية الطلب) ولكن الهوية ليس لديها إذن للوصول إلى المورد المطلوب. هناك سببان:

  • لا يوجد نهج وصول للهوية.
  • لم تتم الموافقة على عنوان IP للمورد الطالب في إعدادات جدار حماية المخزن الرئيسي.

يحدث HTTP 403 غالباً عندما لا يستخدم تطبيق العميل معرف العميل الذي يعتقده العميل. هذا يعني عادةً أن نُهج الوصول لم يُجرَ إعدادها بشكل صحيح لهوية الاتصال الفعلية.

إذا تلقيت خطأ 403 فوراً بعد إضافة هوية إلى نهج الوصول، يمكنك التعامل معه عن طريق إضافة إعادة المحاولة الدورية.

استكشاف الأخطاء وإصلاحها 403

أولاً، قم بتشغيل تسجيل الدخول. للحصول على إرشادات حول كيفية القيام بذلك، راجع تسجيل الدخول إلى Azure Key Vault.

بمجرد تشغيل تسجيل الدخول، يمكنك تحديد ما إذا كان 403 بسبب نهج الوصول أو نهج جدار الحماية.

خطأ بسبب نهج جدار الحماية

"عنوان العميل (00.00.00.00) غير مصرح به والمتصل ليس خدمة موثوقة"

هناك قائمة محدودة من "خدمات Azure الموثوق بها". مواقع Azure على الويب ليست خدمة Azure موثوقة. لمزيد من المعلومات، راجع منشور المدونة الخدمات الموثوق بها.

يجب إضافة عنوان IP الخاص بموقع Azure على الويب إلى Key Vault حتى يعمل.

إذا كان ذلك بسبب نهج الوصول: ابحث عن معرف الكائن للطلب وتأكد من أن معرف الكائن يطابق الكائن الذي يحاول المستخدم تعيين نهج الوصول إليه. غالبا ما تكون هناك كائنات متعددة في معرف Microsoft Entra، والتي لها نفس الاسم، لذا فإن اختيار العنصر الصحيح أمر مهم. من خلال حذف نهج الوصول وقراءته، من الممكن معرفة ما إذا كانت هناك كائنات متعددة بنفس الاسم.

بالإضافة إلى ذلك، لا تتطلب معظم نهج الوصول استخدام "التطبيق المعتمد" كما هو موضح في المدخل. تُستخدَم التطبيقات المعتمدة لسيناريوهات المصادقة "بالنيابة عن"، وهي نادرة.

HTTP 429: طلبات كثيرة جداً

يحدث التقييد عندما يتجاوز عدد الطلبات الحد الأقصى المحدد للإطار الزمني. في حالة حدوث التقييد، ستكون استجابة Key Vault هي HTTP 429. هناك حدود قصوى معلن عنها لأنواع الطلبات المقدمة. على سبيل المثال: إن إنشاء مفتاح HSM 2048-bit هو 10 طلبات لكل 10 ثوانٍ، لكن يكون حد جميع معاملات HSM الأخرى 2000 طلب/10 ثوانٍ. لذلك من المهم فهم أنواع المكالمات التي يتم إجراؤها عند تحديد سبب التقييد. عامةً تقتصر الطلبات المتعلقة بـ Key Vault على 4000 طلب/10 ثوانٍ. الاستثناءات هي العمليات الأساسية، كما هو موثق في حدود خدمة Key Vault

استكشاف الأخطاء وإصلاحها 429

يتم عمل التقييد باستخدام هذه الأساليب:

  • قلل عدد الطلبات التي يتم إجراؤها على Key Vault من خلال تحديد ما إذا كانت هناك أنماط لمورد مطلوب ومحاولة تخزينها مؤقتاً في تطبيق الاستدعاء.

  • عند حدوث تقييد Key Vault، قم بتكييف التعليمات البرمجية المطلوبة لاستخدام التراجع الأسي لإعادة المحاولة. يتم شرح الخوارزمية هنا: كيفية تقييد التطبيق الخاص بك

  • إذا تعذر تقليل عدد الطلبات عن طريق التخزين المؤقت ولم يعمل التراجع المؤقت، ففكر في تقسيم المفاتيح إلى خزائن أساسية متعددة. حد الخدمة للاشتراك الفردي هو 5 أضعاف حد Key Vault الفردي. إذا كنت تستخدم أكثر من خمسة Key Vaults، يجب مراعاة استخدام اشتراكات متعددة.

يمكن العثور على إرشادات مفصلة تتضمن طلب زيادة الحدود هنا: إرشادات التحكم بالنطاق الترددي في Key Vault