المصادقة المخصصة في Azure Static Web Apps

توفر Azure Static Web Apps مصادقة مدارة تستخدم تسجيلات الموفر التي تديرها Azure. لتمكين المزيد من المرونة على التسجيل، يمكنك تجاوز الإعدادات الافتراضية بتسجيل مخصص.

• تسمح لك المصادقة المخصصة أيضا بتكوين موفرين مخصصين يدعمون OpenID الاتصال. يسمح هذا التكوين بتسجيل موفرين خارجيين متعددين.

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

إشعار

تتوفر المصادقة المخصصة فقط في خطة Azure Static Web Apps Standard.

تكوين موفر هوية مخصص

يتم تكوين موفري الهوية المخصصين في auth قسم من ملف التكوين.

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

معرف Microsoft Entra

لإنشاء التسجيل، ابدأ بإنشاء إعدادات التطبيق التالية:

اسم الإعداد	القيمة‬
AZURE_CLIENT_ID	معرف التطبيق (العميل) لتسجيل تطبيق Microsoft Entra.
AZURE_CLIENT_SECRET	سر العميل لتسجيل تطبيق Microsoft Entra.

بعد ذلك، استخدم النموذج التالي لتكوين الموفر في ملف التكوين.

يتوفر موفرو Microsoft Entra في إصدارين مختلفين. يحدد userDetailsClaimالإصدار 1 بشكل صريح ، والذي يسمح للحمولة بإعادة معلومات المستخدم. وعلى النقيض من ذلك، يقوم الإصدار 2 بإرجاع معلومات المستخدم بشكل افتراضي، ويتم تعيينه بواسطة v2.0 في openIdIssuer عنوان URL.

Microsoft Entra الإصدار 1

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET"
        }
      }
    }
  }
}

تأكد من استبدال <TENANT_ID> بمعرف مستأجر Microsoft Entra.

Microsoft Entra الإصدار 2

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET"
        }
      }
    }
  }
}

تأكد من استبدال <TENANT_ID> بمعرف مستأجر Microsoft Entra.

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

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

إشعار

بينما قسم التكوين لمعرف Microsoft Entra هو azureActiveDirectory، فإن النظام الأساسي يسمي هذا aad في عنوان URL لتسجيل الدخول وتسجيل الخروج وإزالة معلومات المستخدم. راجع قسم المصادقة والتخويل للحصول على مزيد من المعلومات.

التفاح

لإنشاء التسجيل، ابدأ بإنشاء إعدادات التطبيق التالية:

اسم الإعداد	القيمة‬
APPLE_CLIENT_ID	معرف عميل Apple.
APPLE_CLIENT_SECRET	سر عميل Apple.

بعد ذلك، استخدم النموذج التالي لتكوين الموفر في ملف التكوين.

{
  "auth": {
    "identityProviders": {
      "apple": {
        "registration": {
          "clientIdSettingName": "APPLE_CLIENT_ID",
          "clientSecretSettingName": "APPLE_CLIENT_SECRET"
        }
      }
    }
  }
}

لمزيد من المعلومات حول كيفية تكوين Apple كموفر مصادقة، راجع وثائق App Service Authentication/Authorization.

Facebook

لإنشاء التسجيل، ابدأ بإنشاء إعدادات التطبيق التالية:

اسم الإعداد	القيمة‬
FACEBOOK_APP_ID	معرف تطبيق Facebook.
FACEBOOK_APP_SECRET	سر تطبيق Facebook.

بعد ذلك، استخدم النموذج التالي لتكوين الموفر في ملف التكوين.

{
  "auth": {
    "identityProviders": {
      "facebook": {
        "registration": {
          "appIdSettingName": "FACEBOOK_APP_ID",
          "appSecretSettingName": "FACEBOOK_APP_SECRET"
        }
      }
    }
  }
}

لمزيد من المعلومات حول كيفية تكوين Facebook كموفر مصادقة، راجع وثائق App Service Authentication/Authorization.

GitHub

لإنشاء التسجيل، ابدأ بإنشاء إعدادات التطبيق التالية:

اسم الإعداد	القيمة‬
GITHUB_CLIENT_ID	معرف عميل GitHub.
GITHUB_CLIENT_SECRET	سر عميل GitHub.

بعد ذلك، استخدم النموذج التالي لتكوين الموفر في ملف التكوين.

{
  "auth": {
    "identityProviders": {
      "github": {
        "registration": {
          "clientIdSettingName": "GITHUB_CLIENT_ID",
          "clientSecretSettingName": "GITHUB_CLIENT_SECRET"
        }
      }
    }
  }
}

Google

لإنشاء التسجيل، ابدأ بإنشاء إعدادات التطبيق التالية:

اسم الإعداد	القيمة‬
GOOGLE_CLIENT_ID	معرف عميل Google.
GOOGLE_CLIENT_SECRET	سر عميل Google.

بعد ذلك، استخدم النموذج التالي لتكوين الموفر في ملف التكوين.

{
  "auth": {
    "identityProviders": {
      "google": {
        "registration": {
          "clientIdSettingName": "GOOGLE_CLIENT_ID",
          "clientSecretSettingName": "GOOGLE_CLIENT_SECRET"
        }
      }
    }
  }
}

لمزيد من المعلومات حول كيفية تكوين Google كموفر مصادقة، راجع وثائق App Service Authentication/Authorization.

موقع Twitter

لإنشاء التسجيل، ابدأ بإنشاء إعدادات التطبيق التالية:

اسم الإعداد	القيمة‬
TWITTER_CONSUMER_KEY	مفتاح مستهلك Twitter.
TWITTER_CONSUMER_SECRET	سر المستهلك تويتر.

بعد ذلك، استخدم النموذج التالي لتكوين الموفر في ملف التكوين.

{
  "auth": {
    "identityProviders": {
      "twitter": {
        "registration": {
          "consumerKeySettingName": "TWITTER_CONSUMER_KEY",
          "consumerSecretSettingName": "TWITTER_CONSUMER_SECRET"
        }
      }
    }
  }
}

لمزيد من المعلومات حول كيفية تكوين Twitter كموفر مصادقة، راجع وثائق App Service Authentication/Authorization.

OpenID Connect

يمكنك تكوين Azure Static Web Apps لاستخدام موفر مصادقة مخصص يلتزم بمواصفات الاتصال OpenID (OIDC). الخطوات التالية مطلوبة لاستخدام موفر OIDC مخصص.

• يسمح بموفر واحد أو أكثر من موفري OIDC.
• يجب أن يكون لكل موفر اسم فريد في التكوين.
• يمكن أن يكون موفر واحد فقط بمثابة هدف إعادة التوجيه الافتراضي.

تسجيل التطبيق الخاص بك مع موفر الهوية

مطلوب منك تسجيل تفاصيل التطبيق الخاص بك مع موفر الهوية. تحقق مع الموفر فيما يتعلق بالخطوات اللازمة لإنشاء معرف عميل وسر العميل لتطبيقك.

بمجرد تسجيل التطبيق مع موفر الهوية، قم بإنشاء أسرار التطبيق التالية في إعدادات التطبيق لتطبيق الويب الثابت:

اسم الإعداد	القيمة‬
MY_PROVIDER_CLIENT_ID	معرف العميل الذي تم إنشاؤه بواسطة موفر المصادقة لتطبيق الويب الثابت.
MY_PROVIDER_CLIENT_SECRET	سر العميل الذي تم إنشاؤه بواسطة التسجيل المخصص لموفر المصادقة لتطبيق الويب الثابت الخاص بك.

إذا قمت بتسجيل موفرين إضافيين، يحتاج كل واحد إلى معرف عميل مقترن ومخزن سري للعميل في إعدادات التطبيق.

هام

أسرار التطبيق هي بيانات اعتماد أمان حساسة. لا تشارك هذا السر مع أي شخص، أو وزعه داخل تطبيق عميل، أو تحقق من التحكم بالمصادر.

بمجرد حصولك على بيانات اعتماد التسجيل، استخدم الخطوات التالية لإنشاء تسجيل مخصص.

1. تحتاج إلى بيانات تعريف OpenID الاتصال للموفر. غالبا ما يتم عرض هذه المعلومات عبر مستند بيانات تعريف التكوين، وهو عنوان URL المصدر للموفر الملحق ب /.well-known/openid-configuration. اجمع عنوان موقع الويب للتكوين هذا.

2. أضف القسم auth من ملف التكوين مع كتلة تكوين لموفري OIDC وتعريف الموفر الخاص بك.

   {
     "auth": {
       "identityProviders": {
         "customOpenIdConnectProviders": {
           "myProvider": {
             "registration": {
               "clientIdSettingName": "MY_PROVIDER_CLIENT_ID",
               "clientCredential": {
                 "clientSecretSettingName": "MY_PROVIDER_CLIENT_SECRET"
               },
               "openIdConnectConfiguration": {
                 "wellKnownOpenIdConfiguration": "https://<PROVIDER_ISSUER_URL>/.well-known/openid-configuration"
               }
             },
             "login": {
               "nameClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
               "scopes": [],
               "loginParameterNames": []
             }
           }
         }
       }
     }
   }
   

• اسم الموفر، myProvider في هذا المثال، هو المعرف الفريد المستخدم من قبل Azure Static Web Apps.
• تأكد من استبدال <PROVIDER_ISSUER_URL> بالمسار إلى عنوان URL المصدر للموفر.
• login يسمح لك الكائن بتوفير قيم ل: النطاقات المخصصة أو معلمات تسجيل الدخول أو المطالبات المخصصة.

عمليات رد اتصال المصادقة

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

النوع	نمط عنوان URL
تسجيل الدخول	https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback
تسجيل الخروج	https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback

إذا كنت تستخدم معرف Microsoft Entra، فاستخدم aad كقيمة <PROVIDER_NAME_IN_CONFIG> العنصر النائب.

إشعار

يتم توفير عناوين URL هذه بواسطة Azure Static Web Apps لتلقي الاستجابة من موفر المصادقة، لا تحتاج إلى إنشاء صفحات في هذه المسارات.

تفاصيل تسجيل الدخول وتسجيل الخروج والمستخدم

لاستخدام موفر هوية مخصص، استخدم أنماط URL التالية.

الإجراء	النمط
تسجيل الدخول	/.auth/login/<PROVIDER_NAME_IN_CONFIG>
تسجيل الخروج	/.auth/logout
تفاصيل المستخدم	/.auth/me
إزالة تفاصيل المستخدم	/.auth/purge/<PROVIDER_NAME_IN_CONFIG>

إذا كنت تستخدم معرف Microsoft Entra، فاستخدم aad كقيمة <PROVIDER_NAME_IN_CONFIG> العنصر النائب.

إدارة الأدوار

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

• مجهول: ينتمي جميع المستخدمين تلقائيا إلى الدور المجهول .
• مصادق عليه: ينتمي جميع المستخدمين الذين سجلوا الدخول إلى الدور المصادق عليه .

بالإضافة إلى الأدوار المضمنة، يمكنك تعيين أدوار مخصصة للمستخدمين، والإشارة إليها في ملف staticwebapp.config.json .

دعوات

إضافة مستخدم إلى دور

لإضافة مستخدم إلى دور، يمكنك إنشاء دعوات تسمح لك بربط المستخدمين بأدوار محددة. يتم تعريف الأدوار وصيانتها في ملف staticwebapp.config.json .

قم بإنشاء دعوة

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

موفر التخويل	يعرض
Microsoft Entra ID	عنوان البريد الإلكتروني
GitHub	اسم المستخدم
موقع Twitter	اسم المستخدم

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

1. انتقل إلى مورد Static Web Apps في مدخل Microsoft Azure.
2. ضمن الإعدادات، حدد إدارة الأدوار.
3. حدِّد دعوة.
4. حدد موفر تخويل من قائمة الخيارات.
5. أضف اسم المستخدم أو عنوان البريد الإلكتروني للمستلم في مربع تفاصيل المدعو.
   • بالنسبة إلى GitHub وTwitter، أدخل اسم المستخدم. بالنسبة لجميع الآخرين، أدخل عنوان البريد الإلكتروني للمستلم.
6. حدد مجال موقعك الثابت من القائمة المنسدلة المجال .
   • المجال الذي تحدده هو المجال الذي يظهر في الدعوة. إذا كان لديك مجال مخصص مقترن بموقعك، فاختر المجال المخصص.
7. أضف قائمة بأسماء الأدوار مفصولة بفواصل في المربع دور .
8. أدخل الحد الأقصى لعدد الساعات التي تريد أن تظل فيها الدعوة صالحة.
   • الحد الأقصى الممكن هو 168 ساعة، وهو سبعة أيام.
9. حدد إنشاء.
10. انسخ الارتباط من مربع الارتباط دعوة.
11. أرسل ارتباط الدعوة بالبريد الإلكتروني إلى المستخدم الذي تمنح حق الوصول إليه.

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

تنبيه

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

تحديث تعيينات الأدوار

1. انتقل إلى مورد Static Web Apps في مدخل Microsoft Azure.
2. ضمن الإعدادات، حدد إدارة الأدوار.
3. حدد المستخدم في القائمة.
4. قم بتحرير قائمة الأدوار في مربع الدور .
5. حدد تحديث.

إزالة المستخدم

1. انتقل إلى مورد Static Web Apps في مدخل Microsoft Azure.
2. ضمن الإعدادات، حدد إدارة الأدوار.
3. حدد موقع المستخدم في القائمة.
4. حدد خانة الاختيار في صف المستخدم.
5. حدد حذف.

أثناء إزالة مستخدم، ضع في اعتبارك العناصر التالية:

• تؤدي إزالة مستخدم إلى إبطال أذوناته.
• قد يستغرق الانتشار في جميع أنحاء العالم بضع دقائق.
• إذا تمت إضافة المستخدم مرة أخرى إلى التطبيق، يتغيرuserId.

دالة (معاينة)

بدلا من استخدام نظام الدعوات المضمن، يمكنك استخدام دالة بلا خادم لتعيين أدوار للمستخدمين برمجيا عند تسجيل الدخول.

لتعيين أدوار مخصصة في دالة، يمكنك تعريف دالة واجهة برمجة التطبيقات التي يتم استدعاؤها تلقائيا بعد كل مرة يصادق فيها المستخدم بنجاح مع موفر هوية. يتم تمرير الدالة معلومات المستخدم من الموفر. يجب أن ترجع قائمة الأدوار المخصصة التي تم تعيينها للمستخدم.

تتضمن أمثلة استخدامات هذه الدالة ما يلي:

• الاستعلام عن قاعدة بيانات لتحديد الأدوار التي يجب تعيينها للمستخدم
• استدعاء واجهة برمجة تطبيقات Microsoft Graph لتحديد أدوار المستخدم استنادا إلى عضوية مجموعة Active Directory الخاصة به
• تحديد أدوار المستخدم استنادا إلى المطالبات التي أرجعها موفر الهوية

إشعار

تتوفر القدرة على تعيين الأدوار عبر وظيفة فقط عند تكوين المصادقة المخصصة.

عند تمكين هذه الميزة، يتم تجاهل أي أدوار تم تعيينها عبر نظام الدعوات المضمن.

تكوين دالة لتعيين الأدوار

لتكوين Static Web Apps لاستخدام دالة API كدالة تعيين الدور، أضف خاصية rolesSource إلى auth قسم ملف تكوين التطبيق الخاص بك. قيمة الخاصية rolesSource هي المسار إلى دالة API.

{
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      // ...
    }
  }
}

إشعار

بمجرد التكوين، لم يعد من الممكن الوصول إلى دالة تعيين الدور بواسطة طلبات HTTP الخارجية.

إنشاء دالة لتعيين الأدوار

بعد تحديد الخاصية rolesSource في تكوين التطبيق، أضف وظيفة API في تطبيق الويب الثابت في المسار المحدد. يمكنك استخدام تطبيق وظائف مدار أو إحضار تطبيق الوظائف الخاص بك.

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

راجع حمولة المثال التالي من معرف Microsoft Entra:

{
  "identityProvider": "aad",
  "userId": "72137ad3-ae00-42b5-8d54-aacb38576d76",
  "userDetails": "ellen@contoso.com",
  "claims": [
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
          "val": "ellen@contoso.com"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
          "val": "Contoso"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
          "val": "Ellen"
      },
      {
          "typ": "name",
          "val": "Ellen Contoso"
      },
      {
          "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier",
          "val": "7da753ff-1c8e-4b5e-affe-d89e5a57fe2f"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
          "val": "72137ad3-ae00-42b5-8d54-aacb38576d76"
      },
      {
          "typ": "http://schemas.microsoft.com/identity/claims/tenantid",
          "val": "3856f5f5-4bae-464a-9044-b72dc2dcde26"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
          "val": "ellen@contoso.com"
      },
      {
          "typ": "ver",
          "val": "1.0"
      }
  ],
  "accessToken": "eyJ0eXAiOiJKV..."
}

يمكن للوظيفة استخدام معلومات المستخدم لتحديد الأدوار التي يجب تعيينها للمستخدم. يجب أن ترجع استجابة HTTP 200 مع نص JSON يحتوي على قائمة بأسماء الأدوار المخصصة لتعيينها للمستخدم.

على سبيل المثال، لتعيين المستخدم للأدوار Reader و Contributor ، قم بإعادة الاستجابة التالية:

{
  "roles": [
    "Reader",
    "Contributor"
  ]
}

إذا كنت لا تريد تعيين أي أدوار أخرى للمستخدم، فسترجع صفيفا فارغا roles .

لمعرفة المزيد، راجع البرنامج التعليمي: تعيين أدوار مخصصة باستخدام وظيفة وMicrosoft Graph.

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

تعيين أدوار المستخدم برمجيا