كيفية استخدام الهويات المُدارة لـ App Service وAzure Functions

مقالة
10/18/2023

توضح لك هذه المقالة كيفية إنشاء هوية مُدارة لتطبيقات App Service وAzure Functions وكيفية استخدامها للوصول إلى الموارد الأخرى.

هام

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

إشعار

الهويات المُدارة غير متاحة للتطبيقات التي تم توزيعها في Azure Arc.

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

يمكن منح طلبك نوعين من الهويات:

ترتبط الهوية التي يعيّنها النظام بالتطبيق الخاص بك ويتم حذفها إذا تم حذف التطبيق الخاص بك. يمكن أن يكون للتطبيق هوية واحدة معينة من قبل النظام.
الهوية التي يعيّنها المستخدم هي مورد Azure مستقل يمكن تعيينه لتطبيقك. يمكن أن يكون للتطبيق هويات متعددة مخصصة للمستخدم.

تكوين الهوية المدارة خاص بالفتحة. لتكوين هوية مدارة لفتحة توزيع في المدخل، انتقل إلى الفتحة أولا. للعثور على الهوية المدارة لتطبيق الويب أو فتحة التوزيع في مستأجر Microsoft Entra من مدخل Microsoft Azure، ابحث عنها مباشرة من صفحة نظرة عامة للمستأجر الخاص بك. عادةً ما يكون اسم الفتحة مشابهًا لـ <app-name>/slots/<slot-name>.

يوضح لك هذا الفيديو كيفية استخدام الهويات المدارة لخدمة التطبيقات.

يتم أيضا وصف الخطوات الواردة في الفيديو في الأقسام التالية.

إضافة يعيِّنها النظام

في جزء التنقل الأيمن من صفحة التطبيق، مرِّر لأسفل وصولاً إلى مجموعة الإعدادات.
حدد "Identity".
في علامة التبويب النظام المعين، بدِّل الحالة إلى تشغيل. انقر فوق حفظ.

شغِّل الأمر az webapp identity assign لإنشاء الهوية التي يعيّنها النظام:

az webapp identity assign --name myApp --resource-group myResourceGroup

لخدمة التطبيق

شغِّل الأمر Set-AzWebApp -AssignIdentity لإنشاء الهوية التي يعيّنها النظام لخدمة التطبيق:

Set-AzWebApp -AssignIdentity $true -Name <app-name> -ResourceGroupName <group-name>

للوظائف

شغِّل الأمر Update-AzFunctionApp -IdentityType لإنشاء الهوية التي يعيّنها النظام لتطبيق الوظائف:

Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType SystemAssigned

يمكن استخدام قالب Azure Resource Manager من أجل أتمتة توزيع موارد Azure. لمعرفة المزيد حول التوزيع إلى App Service وFunctions، راجع أتمتة توزيع الموارد في App Service وأتمتة توزيع الموارد في Azure Functions.

يمكن إنشاء أي مورد من النوع Microsoft.Web/sites بهوية من خلال تضمين الخاصية التالية في تعريف المورد:

"identity": {
    "type": "SystemAssigned"
}

تُعلِم إضافة نوع عيّنه النظام Azure بإنشاء هوية تطبيقك وإدارتها.

وعلى سبيل المثال، قد يبدو قالب تطبيق الويب مثل JSON التالي:

{
    "apiVersion": "2022-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "SystemAssigned"
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]"
    ]
}

عند إنشاء الموقع، يكون لها الخصائص الإضافية التالية:

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<tenant-id>",
    "principalId": "<principal-id>"
}

تحدد الخاصية tenantId ما ينتمي إليه مستأجر Microsoft Entra الذي تنتمي إليه الهوية. إن PrincipId هو معرّف فريد للهوية الجديدة للتطبيق. ضمن معرف Microsoft Entra، يكون لمدير الخدمة نفس الاسم الذي أعطيته ل App Service أو مثيل Azure Functions.

إذا كنت بحاجة إلى الرجوع إلى هذه الخصائص في مرحلة لاحقة في القالب، يمكنك القيام بذلك عبر reference() دالة القالب مع العلامة 'Full'، كما هو الحال في هذا المثال:

{
    "tenantId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.tenantId]",
    "objectId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.principalId]",
}

إضافة هوية يُعينها المستخدم

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

ستحتاج أولاً إلى إنشاء مورد هوية يعيّنها المستخدم.

إنشاء مورد هوية مُدارة يعينها المستخدم وفقًا لهذه الإرشادات.
في جزء التنقل الأيسر من صفحة التطبيق، مرِّر لأسفل وصولاً إلى مجموعة الإعدادات.
حدد "Identity".
حدد إضافة معينة من قبل>المستخدم.
ابحث عن الهوية التي أنشأتها سابقا، وحددها، وحدد إضافة.

بمجرد تحديد إضافة، يتم إعادة تشغيل التطبيق.

قم بإنشاء هوية معينة من قِبل المستخدم .

az identity create --resource-group <group-name> --name <identity-name>

شغِّل الأمر az webapp identity assign لتعيين الهوية إلى التطبيق.

az webapp identity assign --resource-group <group-name> --name <app-name> --identities <identity-id>

لخدمة التطبيق

إضافة هوية معينة من قبل المستخدم في App Service غير مدعومة حاليًا.

للوظائف

قم بإنشاء هوية معينة من قِبل المستخدم .

Install-Module -Name Az.ManagedServiceIdentity -AllowPrerelease
$userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName <group-name>

شغِّل الأمر Update-AzFunctionApp -IdentityType UserAssigned -IdentityId لتعيين الهوية إلى الوظائف:

Update-AzFunctionApp -Name <app-name> -ResourceGroupName <group-name> -IdentityType UserAssigned -IdentityId $userAssignedIdentity.Id

يمكن إنشاء أي مورد من النوع Microsoft.Web/sites بهوية عن طريق تضمين الكتلة التالية في تعريف المورد، واستبدال <resource-id> بمعرف المورد للهوية المطلوبة:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<resource-id>": {}
    }
}

إشعار

يمكن أن يحتوي التطبيق على هويات يعيّنها النظام والمستخدم في الوقت نفسه. وفي هذه الحالة، ستكون الخاصية type هي SystemAssigned,UserAssigned

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

وعلى سبيل المثال، قد يبدو قالب تطبيق الويب مثل JSON التالي:

{
    "apiVersion": "2022-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
            "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
        }
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
    ]
}

عند إنشاء الموقع، يكون لها الخصائص الإضافية التالية:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<resource-id>": {
            "principalId": "<principal-id>",
            "clientId": "<client-id>"
        }
    }
}

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

تكوين المورد الهدف

قد تحتاج إلى تكوين المورد الهدف للسماح بالوصول من التطبيق أو الوظيفة. وعلى سبيل المثال، إذا طلبت رمزًا مميزًا للوصول إلى Key Vault، يجب عليك أيضًا إضافة نهج وصول يتضمن الهوية المدارة للتطبيق أو الوظيفة. بخلاف ذلك، سيتم رفض مكالماتك المحولة إلى Key Vault، حتى إن استخدمت رمزًا مميزًا صالحًا. ينطبق الشيء نفسه على قاعدة بيانات Azure SQL. لمعرفة المزيد حول الموارد التي تدعم رموز Microsoft Entra المميزة، راجع خدمات Azure التي تدعم مصادقة Microsoft Entra.

هام

تحتفظ الخدمات الخلفية للهويات المُدارة بذاكرة تخزين مؤقت لكل URI للمورد لمدة 24 ساعة تقريباً. في حال تحديث نهج الوصول لمورد هدف معين واسترداد رمز مميز لهذا المورد فوراً، فقد تستمر في الحصول على رمز مميز مخزن مؤقتاً بأذونات قديمة حتى تنتهي صلاحية هذا الرمز المميز. لا توجد حالياً طريقة لفرض تحديث الرمز المميز.

الاتصال بخدمات Azure باستخدام التعليمات البرمجية للتطبيق

باستخدام هويته المدارة، يمكن للتطبيق الحصول على رموز مميزة لموارد Azure المحمية بواسطة معرف Microsoft Entra، مثل قاعدة بيانات Azure SQL وAzure Key Vault وAzure Storage. توضح هذه الرموز المميزة التطبيق الذي يصل إلى المورد، وليس أي مستخدم محدد للتطبيق.

توفر خدمة التطبيقات ووظائف Azure نقطة نهاية REST يمكن الوصول إليها داخليًا لاسترداد الرمز المميز. يمكن الوصول إلى نقطة نهاية REST من داخل التطبيق باستخدام HTTP GET قياسي، ويمكن تنفيذه باستخدام عميل HTTP عام بكل لغة. بالنسبة إلى ‎.NET وJavaScript وJava وPython، توفر مكتبة عميل Azure Identity فكرة تجريدية على نقطة نهاية REST هذه وتبسط تجربة التطوير. إن الاتصال بخدمات Azure الأخرى عملية بسيطة مثل إضافة كائن بيانات اعتماد إلى العميل الخاص بالخدمة.

يبدو طلب HTTP GET الأولي مثل المثال التالي:

GET /MSI/token?resource=https://vault.azure.net&api-version=2019-08-01 HTTP/1.1
Host: localhost:4141
X-IDENTITY-HEADER: 853b9a84-5bfa-4b22-a3f3-0b9a43d9ad8a

وقد تبدو عينة الاستجابة كما يلي:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ0eXAi…",
    "expires_on": "1586984735",
    "resource": "https://vault.azure.net",
    "token_type": "Bearer",
    "client_id": "5E29463D-71DA-4FE0-8E69-999B57DB23B0"
}

هذه الاستجابة هي نفس الاستجابة لطلب الرمز المميز للوصول من خدمة إلى خدمة Microsoft Entra. وللوصول إلى Key Vault، ستضيف قيمة access_token إلى اتصال عميل بالمخزن.

إشعار

عند الاتصال بمصادر بيانات Azure SQL باستخدام Entity Framework Core، ضع في اعتبارك استخدام Microsoft.Data.SqlClient، الذي يوفِّر سلاسل اتصال خاصة لاتصال الهوية المُدارة. على سبيل المثال، راجع البرنامج التعليمي: اتصال قاعدة بيانات Azure SQL الآمن من خدمة التطبيقات باستخدام هوية مدارة.

بالنسبة لتطبيقات ووظائف ‎.NET، فإن أبسط طريقة للتعامل مع هوية مُدارة هي من خلال مكتبة عميل Azure Identity لـ ‎.NET. للحصول على إرشادات مفصلة، راجع البرنامج التعليمي: الاتصال بقواعد بيانات Azure من App Service دون أسرار باستخدام هوية مُدارة.

راجع عناوين الوثائق الخاصة بمكتبة العميل للحصول على المعلومات:

تستخدم الأمثلة المرتبطة DefaultAzureCredential. إنه مفيد لمعظم السيناريوهات لأن نفس النمط يعمل في Azure (مع الهويات المُدارة) وعلى جهازك المحلي (دون الهويات المُدارة).

بالنسبة إلى تطبيقات Node.js ووظائف JavaScript، تكون أبسط طريقة للعمل مع هوية مُدارة من خلال مكتبة عميل Azure Identity لـ JavaScript. للحصول على إرشادات مفصلة، راجع البرنامج التعليمي: الاتصال بقواعد بيانات Azure من App Service دون أسرار باستخدام هوية مُدارة.

راجع عناوين الوثائق الخاصة بمكتبة العميل للحصول على المعلومات:

للحصول على مزيدٍ من أمثلة التعليمات البرمجية لمكتبة عميل Azure Identity لـ JavaScript، راجع أمثلة Azure Identity.

بالنسبة لتطبيقات ووظائف Python، فإن أبسط طريقة للعمل بهوية مُدارة هي من خلال مكتبة عميل Azure Identity لـ Python. للحصول على إرشادات مفصلة، راجع البرنامج التعليمي: الاتصال بقواعد بيانات Azure من App Service دون أسرار باستخدام هوية مُدارة.

راجع عناوين الوثائق الخاصة بمكتبة العميل للحصول على المعلومات:

بالنسبة إلى تطبيقات ووظائف Java، تكون أبسط طريقة للعمل مع هوية مُدارة من خلال مكتبة عميل Azure Identity لـ Java. للحصول على إرشادات مفصلة، راجع البرنامج التعليمي: الاتصال بقواعد بيانات Azure من App Service دون أسرار باستخدام هوية مُدارة.

راجع عناوين الوثائق الخاصة بمكتبة العميل للحصول على المعلومات:

للحصول على مزيدٍ من أمثلة التعليمات البرمجية لمكتبة عميل Azure Identity لـ Java، راجع أمثلة Azure Identity.

استخدم البرنامج النصي التالي لاسترداد رمز مميز من نقطة النهاية المحلية عن طريق تحديد URI لمورد لخدمة Azure:

$resourceURI = "https://<AAD-resource-URI-for-resource-to-obtain-token>"
$tokenAuthURI = $env:IDENTITY_ENDPOINT + "?resource=$resourceURI&api-version=2019-08-01"
$tokenResponse = Invoke-RestMethod -Method Get -Headers @{"X-IDENTITY-HEADER"="$env:IDENTITY_HEADER"} -Uri $tokenAuthURI
$accessToken = $tokenResponse.access_token

لمزيدٍ من المعلومات عن نقطة نهاية REST، راجع مرجع نقطة نهاية REST.

إزالة هوية

عند إزالة هوية معينة من قبل النظام، يتم حذفها من معرف Microsoft Entra. تتم أيضا إزالة الهويات المعينة من قبل النظام تلقائيا من معرف Microsoft Entra عند حذف مورد التطبيق نفسه.

في جزء التنقل الأيمن من صفحة التطبيق، مرِّر لأسفل وصولاً إلى مجموعة الإعدادات.
حدد "Identity". ثم اتبع الخطوات بناءً على نوع الهوية:
- الهوية التي يعيّنها النظام: ضمن علامة التبويب "System assigned"، بدِّل الحالة إلى إيقاف التشغيل. انقر فوق حفظ.
- الهوية التي يعيّنها المستخدم: حدد علامة التبويب "User assigned"، وحدد خانة الاختيار للهوية، وحدد "Remove". حدد نعم للتأكيد.

لإزالة الهوية التي يعيّنها النظام:

az webapp identity remove --name <app-name> --resource-group <group-name>

لإزالة هوية واحدة أو أكثر من الهويات التي يعيّنها المستخدم:

az webapp identity remove --name <app-name> --resource-group <group-name> --identities <identity-id1> <identity-id2> ...

يمكنك أيضًا إزالة هوية النظام المعينة بتحديد [system] في --identities.

لخدمة التطبيق

شغِّل الأمر Set-AzWebApp -AssignIdentity لإزالة الهوية التي يعيّنها النظام لخدمة التطبيق:

Set-AzWebApp -AssignIdentity $false -Name <app-name> -ResourceGroupName <group-name>

للوظائف

لإزالة جميع الهويّات في Azure PowerShell (وظائف Azure فقط):

# Update an existing function app to have IdentityType "None".
Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType None

لإزالة جميع الهويّات في قالب ARM:

"identity": {
    "type": "None"
}

إشعار

هناك أيضًا إعداد تطبيق يمكن تعيينه، WEBSITE_DISABLE_MSI، والذي يقوم فقط بتعطيل خدمة الرمز المميز المحلي. ومع ذلك، فإنه يترك الهوية في مكانها، وستظل الأدوات تعرض الهوية المدارة على أنها "تشغيل" أو "مُمكّنة". ونتيجة لذلك، لا ينصح باستخدام هذا الإعداد.

مرجع نقطة نهاية REST

يتيح التطبيق الذي يحتوي على هوية مُدارة نقطة النهاية هذه من خلال تحديد متغيرين للبيئة:

IDENTITY_ENDPOINT - عنوان URL خدمة الرمز المميز المحلي.
IDENTITY_HEADER - عنوان يستخدم للمساعدة في التخفيف من هجمات تزوير الطلب من جانب الخادم (SSRF). يدير النظام الأساسي القيمة.

IDENTITY_ENDPOINT - عنوان URL المحلي الذي يمكن لتطبيق الحاوية طلب الرموز المميزة منه. للحصول على رمز مميز لمورد، أجرِ طلب HTTP GET إلى نقطة النهاية هذه، بما في ذلك المعلمات التالية:

اسم المعلمة في ‏‏الوصف

resource الاستعلام URI لمورد Microsoft Entra للمورد الذي يجب الحصول على رمز مميز له. قد تكون هذه إحدى خدمات Azure التي تدعم مصادقة Microsoft Entra أو أي مورد URI آخر.

نسخة واجهة برمجة التطبيقات الاستعلام إصدار واجهة برمجة تطبيقات الرمز المميز الذي يُستخدَم. استخدم 2019-08-01.

X-IDENTITY-HEADER الرأس قيمة متغير البيئة IDENTITY_HEADER. هذا العنوان يستخدم للمساعدة في التخفيف من هجمات تزوير الطلب من جانب الخادم (SSRF).

client_id الاستعلام (اختياري) مُعرِّف العميل للهوية التي يعيّنها المستخدم المطلوب استخدامه. لا يمكن الاستخدام لطلب يشتمل على principal_id أو mi_res_id أو object_id. في حال حذف جميع معلمات المُعرِّف (client_id وprincipal_id وobject_id وmi_res_id)، تُستخدَم الهوية التي يعيّنها النظام.

principal_id الاستعلام (اختياري) المُعرِّف الأساسي للهوية التي يعيّنها المستخدم المطلوب استخدامه. object_id هو اسم مستعار يمكن استخدامه بدلاً من ذلك. لا يمكن الاستخدام في طلب يتضمن client_id أو mi_res_id أو object_id. في حال حذف جميع معلمات المُعرِّف (client_id وprincipal_id وobject_id وmi_res_id)، تُستخدَم الهوية التي يعيّنها النظام.

mi_res_id الاستعلام (اختياري) مُعرِّف مورد Azure للهوية التي يعيّنها المستخدم المطلوب استخدامه. لا يمكن الاستخدام لطلب يشتمل على principal_id أو client_id أو object_id. في حال حذف جميع معلمات المُعرِّف (client_id وprincipal_id وobject_id وmi_res_id)، تُستخدَم الهوية التي يعيّنها النظام.

اسم المعلمة	في	‏‏الوصف
resource	الاستعلام	URI لمورد Microsoft Entra للمورد الذي يجب الحصول على رمز مميز له. قد تكون هذه إحدى خدمات Azure التي تدعم مصادقة Microsoft Entra أو أي مورد URI آخر.
نسخة واجهة برمجة التطبيقات	الاستعلام	إصدار واجهة برمجة تطبيقات الرمز المميز الذي يُستخدَم. استخدم `2019-08-01`.
X-IDENTITY-HEADER	الرأس	قيمة متغير البيئة IDENTITY_HEADER. هذا العنوان يستخدم للمساعدة في التخفيف من هجمات تزوير الطلب من جانب الخادم (SSRF).
client_id	الاستعلام	(اختياري) مُعرِّف العميل للهوية التي يعيّنها المستخدم المطلوب استخدامه. لا يمكن الاستخدام لطلب يشتمل على `principal_id` أو `mi_res_id` أو `object_id`. في حال حذف جميع معلمات المُعرِّف (`client_id` و`principal_id` و`object_id` و`mi_res_id`)، تُستخدَم الهوية التي يعيّنها النظام.
principal_id	الاستعلام	(اختياري) المُعرِّف الأساسي للهوية التي يعيّنها المستخدم المطلوب استخدامه. `object_id` هو اسم مستعار يمكن استخدامه بدلاً من ذلك. لا يمكن الاستخدام في طلب يتضمن client_id أو mi_res_id أو object_id. في حال حذف جميع معلمات المُعرِّف (`client_id` و`principal_id` و`object_id` و`mi_res_id`)، تُستخدَم الهوية التي يعيّنها النظام.
mi_res_id	الاستعلام	(اختياري) مُعرِّف مورد Azure للهوية التي يعيّنها المستخدم المطلوب استخدامه. لا يمكن الاستخدام لطلب يشتمل على `principal_id` أو `client_id` أو `object_id`. في حال حذف جميع معلمات المُعرِّف (`client_id` و`principal_id` و`object_id` و`mi_res_id`)، تُستخدَم الهوية التي يعيّنها النظام.

هام

في حال محاولة الحصول على رموز مميزة للهويات التي يعيّنها المستخدم، يجب تضمين إحدى الخصائص الاختيارية. وإلا فستحاول خدمة الرمز المميز الحصول على رمز مميز لهوية يعيّنها النظام، وقد يكون موجوداً أو غير موجود.

كيفية استخدام الهويات المُدارة لـ App Service وAzure Functions

إضافة يعيِّنها النظام

لخدمة التطبيق

للوظائف

إضافة هوية يُعينها المستخدم

لخدمة التطبيق

للوظائف

تكوين المورد الهدف

الاتصال بخدمات Azure باستخدام التعليمات البرمجية للتطبيق

إزالة هوية

لخدمة التطبيق

للوظائف

مرجع نقطة نهاية REST

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

الموارد الإضافية