إدارة API وإصدارات وقت التشغيل من مصادقة App Service

توضح لك هذه المقالة كيفية تخصيص إصدارات API ووقت التشغيل للمصادقة والتخويل المضمنين في App Service.

ثمة إصداران من واجهة برمجة تطبيقات الإدارة لمصادقة App Service. الإصدار V2 مطلوب لتجربة "المصادقة" في مدخل Microsoft Azure. يمكن للتطبيق الذي يستخدم بالفعل الإصدار V1 من API الترقية إلى إصدار V2 بمجرد إجراء بعض التغييرات. على وجه التحديد، يجب نقل التكوين السري إلى إعدادات التطبيق الملصقة بالفتحة. يمكن إجراء ذلك تلقائياً من قسم "المصادقة" في المدخل لتطبيقك.

تحديث إصدار التكوين

تحذير

سيؤدي الترحيل إلى V2 إلى تعطيل إدارة ميزة App Service Authentication/Authorization للتطبيق الخاص بك من خلال بعض العملاء، مثل تجربته الحالية في مدخل Microsoft Azure وAzure CLI وAzure PowerShell. ولا يمكن عكس ذلك.

لا تدعم واجهة برمجة تطبيقات V2 إنشاء حساب Microsoft أو تحريره كموفر مميز كما تم في الإصدار 1. بدلا من ذلك، يستخدم النظام الأساسي للهويات في Microsoft المتقاربة لتسجيل دخول المستخدمين باستخدام كل من Microsoft Entra وحسابات Microsoft الشخصية. عند التبديل إلى V2 API، يتم استخدام تكوين V1 Microsoft Entra لتكوين موفر النظام الأساسي للهويات في Microsoft. سيتم ترحيل موفر حساب Microsoft V1 إلى الأمام في عملية الترحيل ويستمر في العمل كالمعتاد، ولكن يجب الانتقال إلى نموذج النظام الأساسي للهويات في Microsoft الأحدث. راجع دعم تسجيلات موفر حساب Microsoft للتعرُّف على المزيد.

ستقوم عملية الترحيل التلقائي بنقل أسرار الموفر إلى إعدادات التطبيق ثم تحويل بقية التكوين إلى التنسيق الجديد. لاستخدام الترحيل التلقائي:

1. انتقل إلى تطبيقك في المدخل وحدد خيار قائمة Authentication.
2. إذا تم تكوين التطبيق باستخدام نموذج V1، فسترى زر ترقية.
3. راجع الوصف في موجه التأكيد. إذا كنت جاهزا لتنفيذ الترحيل، فحدد ترقية في المطالبة.

إدارة الترحيل يدوياً

ستسمح لك الخطوات التالية بترحيل التطبيق يدويا إلى V2 API إذا كنت لا ترغب في استخدام الإصدار التلقائي المذكور أعلاه.

نقل الأسرار إلى إعدادات التطبيق

1. احصل على التكوين الحالي باستخدام واجهة برمجة تطبيقات V1:

   az webapp auth show -g <group_name> -n <site_name>
   

   في حمولة JSON الناتجة، دون القيمة السرية المستخدمة لكل موفر قمت بتكوينه:

   • Microsoft Entra: clientSecret
   • Google: googleClientSecret
   • Facebook: facebookAppSecret
   • Twitter: twitterConsumerSecret
   • حساب Microsoft: microsoftAccountClientSecret

   هام

   القيم السرية هي أوراق اعتماد أمنية مهمة ويجب التعامل معها بعناية. لا تشارك هذه القيم أو الاحتفاظ بها على جهاز محلي.

2. إنشاء إعدادات تطبيق ثبات الفتحة لكل قيمة سرية. يمكنك اختيار اسم كل إعداد تطبيق. يجب أن تتطابق قيمتها مع ما حصلت عليه في الخطوة السابقة أو الرجوع إلى سر Key Vault الذي قمت بإنشائه بهذه القيمة.

   لإنشاء الإعداد، يمكنك استخدام مدخل Microsoft Azure أو تشغيل تباين مما يلي لكل موفر:

   # For Web Apps, Google example    
   az webapp config appsettings set -g <group_name> -n <site_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>
   
   # For Azure Functions, Twitter example
   az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>
   

   إشعار

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

3. إنشاء ملف JSON جديد باسم authsettings.json. خذ الإخراج الذي تلقيته سابقا وقم بإزالة كل قيمة سرية منه. اكتب الإخراج المتبقي إلى الملف، مع التأكد من عدم تضمين أي معلومات سرية. في بعض الحالات، قد يحتوي التكوين على صفائف تضم سلاسل فارغة. تأكد من عدم حدوث microsoftAccountOAuthScopes ذلك، وإذا كان كذلك، قم بتبديل هذه القيمة إلى null.

4. أضف خاصية إلى تشير إلى authsettings.json اسم إعداد التطبيق الذي قمت بإنشائه مسبقا لكل موفر:

   • Microsoft Entra: clientSecretSettingName
   • Google: googleClientSecretSettingName
   • Facebook: facebookAppSecretSettingName
   • Twitter: twitterConsumerSecretSettingName
   • حساب Microsoft: microsoftAccountClientSecretSettingName

   قد يبدو ملف مثال بعد هذه العملية مشابها لما يلي، في هذه الحالة تم تكوينه فقط لمعرف Microsoft Entra:

   {
       "id": "/subscriptions/00d563f8-5b89-4c6a-bcec-c1b9f6d607e0/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings",
       "name": "authsettings",
       "type": "Microsoft.Web/sites/config",
       "location": "Central US",
       "properties": {
           "enabled": true,
           "runtimeVersion": "~1",
           "unauthenticatedClientAction": "AllowAnonymous",
           "tokenStoreEnabled": true,
           "allowedExternalRedirectUrls": null,
           "defaultProvider": "AzureActiveDirectory",
           "clientId": "3197c8ed-2470-480a-8fae-58c25558ac9b",
           "clientSecret": "",
           "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
           "clientSecretCertificateThumbprint": null,
           "issuer": "https://sts.windows.net/0b2ef922-672a-4707-9643-9a5726eec524/",
           "allowedAudiences": [
               "https://mywebapp.azurewebsites.net"
           ],
           "additionalLoginParams": null,
           "isAadAutoProvisioned": true,
           "aadClaimsAuthorization": null,
           "googleClientId": null,
           "googleClientSecret": null,
           "googleClientSecretSettingName": null,
           "googleOAuthScopes": null,
           "facebookAppId": null,
           "facebookAppSecret": null,
           "facebookAppSecretSettingName": null,
           "facebookOAuthScopes": null,
           "gitHubClientId": null,
           "gitHubClientSecret": null,
           "gitHubClientSecretSettingName": null,
           "gitHubOAuthScopes": null,
           "twitterConsumerKey": null,
           "twitterConsumerSecret": null,
           "twitterConsumerSecretSettingName": null,
           "microsoftAccountClientId": null,
           "microsoftAccountClientSecret": null,
           "microsoftAccountClientSecretSettingName": null,
           "microsoftAccountOAuthScopes": null,
           "isAuthFromFile": "false"
       }   
   }
   

5. أرسل هذا الملف كتكوين المصادقة/التخويل الجديد لتطبيقك:

   az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json
   

6. تحقق من أن تطبيقك لا يزال يعمل كما هو متوقع بعد هذه الإيماءة.

7. احذف الملف المستخدم في الخطوات السابقة.

لقد قمت الآن بترحيل التطبيق لتخزين أسرار موفر الهوية كإعدادات للتطبيق.

دعم تسجيلات موفر حساب Microsoft

إذا كان التكوين الحالي يحتوي على موفر حساب Microsoft ولا يحتوي على موفر Microsoft Entra، يمكنك تبديل التكوين إلى موفر Microsoft Entra ثم تنفيذ الترحيل. للقيام بذلك:

1. انتقل إلى App registrations في مدخل Microsoft Azure وابحث عن التسجيل المقترن بموفر حساب Microsoft الخاص بك. قد يكون تحت عنوان "التطبيقات من الحساب الشخصي".
2. انتقل إلى صفحة "Authentication" للتسجيل. ضمن "Redirect URIs"، يجب أن تشاهد إدخالا ينتهي ب /.auth/login/microsoftaccount/callback. انسخ عنوان URI هذا.
3. أضف عنوان URI جديداً يطابق العنوان الذي نسخته للتو، باستثناء أنه ينتهي بـ /.auth/login/aad/callback. سيسمح هذا باستخدام التسجيل بواسطة تكوين مصادقة / تخويل خدمة التطبيقات.
4. انتقل إلى تكوين مصادقة / تخويل خدمة التطبيقات لتطبيقك.
5. اجمع التكوين لموفر حساب Microsoft.
6. قم بتكوين موفر Microsoft Entra باستخدام وضع الإدارة "المتقدم"، وتوفير معرف العميل والقيم السرية للعميل التي جمعتها في الخطوة السابقة. بالنسبة إلى عنوان URL المصدر، استخدم <authentication-endpoint>/<tenant-id>/v2.0، واستبدل <نقطة> نهاية المصادقة بنقطة نهاية المصادقة لبيئة السحابة الخاصة بك (على سبيل المثال، "https://login.microsoftonline.com"؛ لمعرف Microsoft Entra العمومي)، استبدال معرف> المستأجر أيضا <بمعرف الدليل (المستأجر).
7. بمجرد حفظ التكوين، اختبر تدفق تسجيل الدخول عن طريق التنقل في المتصفح إلى /.auth/login/aad نقطة النهاية على موقعك وإكمال تدفق تسجيل الدخول.
8. عند هذه النقطة، قمت بنسخ التكوين بنجاح، ولكن يظل تكوين موفر حساب Microsoft الحالي. قبل إزالته، تأكد من أن جميع أجزاء التطبيق تشير إلى موفر Microsoft Entra من خلال ارتباطات تسجيل الدخول، وما إلى ذلك. تحقق من أن جميع أجزاء التطبيق تعمل كما هو متوقع.
9. بمجرد التحقق من أن الأمور تعمل مقابل موفر Microsoft Entra، يمكنك إزالة تكوين موفر حساب Microsoft.

تحذير

من الممكن تقريب التسجيلين عن طريق تعديل أنواع الحسابات المدعومة لتسجيل تطبيق Microsoft Entra. ومع ذلك، قد يفرض هذا مطالبة موافقة جديدة لمستخدمي حساب Microsoft، وقد تختلف مطالبات هوية هؤلاء المستخدمين من حيث البنية، sub ولا سيما تغيير القيم نظراً لاستخدام معرف تطبيق جديد. ولا يوصى بهذا النهج ما لم يتم فهمه فهماً دقيقاً. يجب عليك بدلاً من ذلك انتظار دعم التسجيلين في سطح V2 API.

التبديل إلى الإصدار 2

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

بدلاً من ذلك، يمكنك إجراء طلب PUT مقابل المورد config/authsettingsv2 ضمن مورد الموقع. مخطط الحمولة هو نفسه الذي تم التقاطه في التكوين المستند إلى الملف.

تثبيت التطبيق بإصدار وقت تشغيل مصادقة معين

عند تمكين المصادقة/التخويل، يتم إدخال البرنامج الوسيط للنظام الأساسي في مسار طلب HTTP كما هو موضح في نظرة عامة على الميزة. يتم تحديث البرنامج الوسيط للنظام الأساسي هذا بشكلٍ دوري بميزات وتحسينات جديدة كجزء من تحديثات النظام الأساسي الروتينية. بشكلٍ افتراضي، سيتم تشغيل تطبيق الويب أو الدالة على أحدث إصدار من هذا البرنامج الوسيط للنظام الأساسي. هذه التحديثات التلقائية متوافقة دائماً مع الإصدارات السابقة. ومع ذلك، في الحدث النادر الذي يقدم فيه هذا التحديث التلقائي مشكلة وقت التشغيل لتطبيق الويب أو التطبيق الوظيفي، يمكنك العودة مؤقتاً إلى إصدار البرنامج الوسيط السابق. توضح هذه المقالة كيفية تثبيت تطبيق مؤقتاً بإصدار معين من برنامج وسيط المصادقة.

تحديثات الإصدار التلقائية واليدوية

يمكنك تثبيت تطبيقك بإصدار معين من البرنامج الوسيط للنظام الأساسي عن طريق تعيين إعداد runtimeVersion للتطبيق. يتم تشغيل تطبيقك دائماً على أحدث إصدار ما لم تختص بتثبيته بشكلٍ صريح في إصدار معين. سيكون هناك عدد قليل من الإصدارات المدعومة في كل مرة. إذا قمت بتثبيت إصدار غير صالح لم يعد معتمداً، فسيستخدم تطبيقك أحدث إصدار بدلاً من ذلك. لتشغيل أحدث إصدار دائماً، قم بتعيين runtimeVersion إلى ~1.

عرض وتحديث إصدار وقت التشغيل الحالي

يمكنك تغيير إصدار وقت التشغيل الذي يستخدمه التطبيق الخاص بك. يجب أن يسري إصدار وقت التشغيل الجديد بعد إعادة تشغيل التطبيق.

عرض إصدار وقت التشغيل الحالي

يمكنك عرض الإصدار الحالي من البرنامج الوسيط لمصادقة النظام الأساسي إما باستخدام Azure CLI أو عبر إحدى نقاط نهاية HTTP للإصدار المضمن في تطبيقك.

من Azure CLI

باستخدام Azure CLI، اعرض الإصدار الوسيط الحالي باستخدام الأمر az webapp auth show.

az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>

في هذا الرمز، استبدل <my_app_name> باسم التطبيق الخاص بك. استبدل أيضاً <my_resource_group> باسم مجموعة الموارد لتطبيقك.

سترى الحقل في runtimeVersion إخراج CLI. سيكون مشابهاً لإخراج المثال التالي، والذي تم اقتطاعه من أجل التوضيح:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}

من نقطة نهاية الإصدار

يمكنك أيضاً الوصول إلى نقطة نهاية /.auth/version على تطبيق أيضاً لعرض إصدار البرنامج الوسيط الحالي الذي يعمل عليه التطبيق. سيكون مشابهاً للإخراج المثال التالي:

{
"version": "1.3.2"
}

تحديث إصدار وقت التشغيل الحالي

باستخدام Azure CLI، يمكنك تحديث runtimeVersion الإعداد في التطبيق باستخدام الأمر az webapp auth update.

az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>

استبدل <my_app_name> باسم التطبيق الخاص بك. استبدل أيضاً <my_resource_group> باسم مجموعة الموارد لتطبيقك. أيضاً، استبدل <version> بإصدار صالح من وقت التشغيل 1.x أو ~1 لأحدث إصدار. راجع ملاحظات الإصدار على إصدارات وقت التشغيل المختلفة للمساعدة في تحديد الإصدار المراد تثبيته.

يمكنك تشغيل هذا الأمر من Azure Cloud Shell عن طريق اختيار Try it في نموذج التعليمات البرمجية السابق. يمكنك أيضا استخدام Azure CLI محليا لتنفيذ هذا الأمر بعد تنفيذ تسجيل الدخول az لتسجيل الدخول.

الخطوات التالية

البرنامج التعليمي: مصادقة المستخدمين وتفويضهم من طرف إلى طرف