واجهات برمجة التطبيقات الآمنة المستخدمة لموصلات واجهة برمجة التطبيقات في Azure AD B2C

هام

اعتبارا من 1 مايو 2025، لن يكون Azure AD B2C متوفرا للشراء للعملاء الجدد. تعرف على المزيد في الأسئلة المتداولة.

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

المتطلبات الأساسية

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

يمكنك حماية نقطة نهاية واجهة برمجة التطبيقات باستخدام مصادقة HTTP الأساسية أو مصادقة شهادة عميل HTTPS. في كلتا الحالتين، يمكنك توفير بيانات الاعتماد التي يستخدمها Azure AD B2C عندما يستدعي نقطة نهاية واجهة برمجة التطبيقات. ثم تتحقق نقطة نهاية واجهة برمجة التطبيقات من بيانات الاعتماد وتنفذ قرارات التخويل.

مصادقة HTTP الأساسية

يتم تعريف مصادقة HTTP الأساسية في RFC 2617. تعمل المصادقة الأساسية على النحو التالي:

يرسل Azure AD B2C طلب HTTP مع بيانات اعتماد العميل (username و password) في Authorization الرأس.
يتم تنسيق بيانات الاعتماد كسلسلة username:passwordمشفرة base64.
تكون واجهة برمجة التطبيقات الخاصة بك مسؤولة عن التحقق من هذه القيم لتنفيذ قرارات تفويض أخرى.

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

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

إضافة اسم مستخدم واجهة برمجة تطبيقات REST ومفاتيح سياسة كلمة المرور

لتكوين ملف تعريف تقني لواجهة برمجة تطبيقات REST باستخدام مصادقة HTTP الأساسية، قم بإنشاء مفاتيح التشفير التالية لتخزين اسم المستخدم وكلمة المرور:

قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد أيقونة الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة الدلائل + الاشتراكات .
اختر جميع الخدمات في الزاوية العلوية اليمنى من مدخل Microsoft Azure، ثم ابحث عن Azure AD B2C وحدده.
في صفحة Overview، حدد Identity Experience Framework.
حدد Policy Keys، ثم حدد Add.
بالنسبة إلى خيارات، حدد يدوي.
بالنسبة إلى الاسم، اكتب RestApiUsername. قد تتم إضافة البادئة B2C_1A_ تلقائيا.
في المربع سري ، أدخل اسم مستخدم واجهة برمجة تطبيقات REST.
لاستخدام المفتاح، حدد تشفير.
حدد إنشاء.
حدد مفاتيح السياسة مرة أخرى.
حدد إضافة.
بالنسبة إلى خيارات، حدد يدوي.
بالنسبة إلى الاسم، اكتب RestApiPassword. قد تتم إضافة البادئة B2C_1A_ تلقائيا.
في المربع سري ، أدخل كلمة مرور واجهة برمجة تطبيقات REST.
لاستخدام المفتاح، حدد تشفير.
حدد إنشاء.

تكوين ملف التعريف التقني لواجهة برمجة تطبيقات REST لاستخدام مصادقة HTTP الأساسية

بعد إنشاء المفاتيح الضرورية، قم بتكوين بيانات تعريف ملف تعريف واجهة برمجة تطبيقات REST للإشارة إلى بيانات الاعتماد.

في دليل العمل الخاص بك، افتح ملف نهج الملحق (TrustFrameworkExtensions.xml).
ابحث عن ملف تعريف واجهة برمجة تطبيقات REST التقني. على سبيل المثال REST-ValidateProfile، أو REST-GetProfile.
حدد موقع العنصر <Metadata> .
قم بتغيير نوع المصادقة إلى Basic.
قم بتغيير AllowInsecureAuthInProduction إلى false.

بعد العنصر الإغلاقي </Metadata> مباشرة، أضف مقتطف XML التالي:

<CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_RestApiUsername" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_RestApiPassword" />
</CryptographicKeys>

يعد قصاصة XML التالية مثالا على ملف تعريف RESTful التقني الذي تم تكوينه باستخدام مصادقة HTTP الأساسية:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <Item Key="AuthenticationType">Basic</Item>
        <Item Key="AllowInsecureAuthInProduction">false</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_RestApiUsername" />
        <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_RestApiPassword" />
      </CryptographicKeys>
      ...
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

مصادقة شهادة عميل HTTPS

مصادقة شهادة العميل هي مصادقة متبادلة تستند إلى الشهادة، حيث يوفر العميل، Azure AD B2C، شهادة العميل الخاصة به إلى الخادم لإثبات هويته. يحدث هذا كجزء من مصافحة SSL. واجهة برمجة التطبيقات الخاصة بك مسؤولة عن التحقق من صحة الشهادات التي تنتمي إلى عميل صالح، مثل Azure AD B2C، وتنفيذ قرارات التخويل. شهادة العميل هي شهادة رقمية X.509.

هام

في بيئات الإنتاج، يجب توقيع الشهادة من قبل مرجع مصدق.

إنشاء شهادة

الخيار 1: استخدام Azure Key Vault (موصى به)

لإنشاء شهادة، يمكنك استخدام Azure Key Vault، الذي يحتوي على خيارات للشهادات الموقعة ذاتيا والتكاملات مع موفري مصدر الشهادات للشهادات الموقعة. تتضمن الإعدادات الموصى بها ما يلي:

الموضوع:CN=<yourapiname>.<tenantname>.onmicrosoft.com
نوع المحتوى: PKCS #12
نوع أكتون مدى الحياة: Email all contacts at a given percentage lifetime أو Email all contacts a given number of days before expiry
نوع المفتاح: RSA
حجم المفتاح: 2048
المفتاح الخاص القابل للطرد: Yes (حتى تتمكن من تصدير .pfx الملف)

يمكنك بعد ذلك تصدير الشهادة.

الخيار 2: إعداد شهادة موقعة ذاتيا باستخدام الوحدة النمطية PowerShell

إذا لم يكن لديك شهادة بالفعل، يمكنك استخدام شهادة موقعة ذاتيا. الشهادة الموقعة ذاتيا هي شهادة أمان لم يتم توقيعها من قبل مرجع مصدق (CA) ولا توفر ضمانات الأمان لشهادة موقعة من قبل المرجع المصدق.

نوافذ
macOS

في Windows، استخدم الأمر Cmdlet New-SelfSignedCertificate في PowerShell لإنشاء شهادة.

قم بتشغيل أمر PowerShell التالي لإنشاء شهادة موقعة ذاتيا. تعديل الوسيطة -Subject حسب الاقتضاء للتطبيق الخاص بك واسم مستأجر Azure AD B2C مثل contosowebapp.contoso.onmicrosoft.com. يمكنك أيضا ضبط -NotAfter التاريخ لتحديد انتهاء صلاحية مختلف للشهادة.
```
New-SelfSignedCertificate `
    -KeyExportPolicy Exportable `
    -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -KeyUsage DigitalSignature `
    -NotAfter (Get-Date).AddMonths(12) `
    -CertStoreLocation "Cert:\CurrentUser\My"
```
على كمبيوتر Windows، ابحث عن Manage user certificates وحددها
ضمن الشهادات - المستخدم الحالي، حددالشهادات>الشخصية>yourappname.yourtenant.onmicrosoft.com.
حدد الشهادة، ثم حدد إجراء>تصدير كافة المهام>.
حدد التالي>نعم، قم بتصدير المفتاح> الخاصالتالي.
اقبل الإعدادات الافتراضية لتصدير تنسيق الملف، ثم حدد التالي.
تمكين خيار كلمة المرور ، أدخل كلمة مرور للشهادة، ثم حدد التالي.
لتحديد موقع لحفظ الشهادة، حدد استعراض وانتقل إلى دليل من اختيارك.
في النافذة حفظ باسم ، أدخل اسم ملف، ثم حدد حفظ.
حدد التالي>وإنهاء.

لكي يقبل Microsoft Azure Active Directory B2C كلمة مرور ملف .pfx، يجب تشفير كلمة المرور باستخدام خيار TripleDES-SHA1 في الأداة المساعدة لتصدير متجر شهادات Windows، بدلا من AES256-SHA256.

تكوين موصل واجهة برمجة التطبيقات

لتكوين موصل واجهة برمجة التطبيقات باستخدام مصادقة شهادة العميل، اتبع الخطوات التالية:

قم بتسجيل الدخول إلى بوابة Azure.
ضمن خدمات Azure، حدد Azure AD B2C.
حدد موصلات واجهة برمجة التطبيقات، ثم حدد موصل واجهة برمجة التطبيقات الذي تريد تكوينه.
بالنسبة لنوع المصادقة، حدد شهادة.
في المربع تحميل الشهادة ، حدد ملف .pfx لشهادتك باستخدام مفتاح خاص.
في المربع إدخال كلمة المرور ، اكتب كلمة مرور الشهادة.
حدد حفظ.

تنفيذ قرارات التفويض

يجب أن تنفذ واجهة برمجة التطبيقات التفويض استنادا إلى شهادات العميل المرسلة لحماية نقاط نهاية واجهة برمجة التطبيقات. بالنسبة إلى Azure App Service وAzure Functions، راجع تكوين مصادقة TLS المتبادلة لمعرفة كيفية تمكين الشهادة والتحقق من صحتها من التعليمات البرمجية لواجهة برمجة التطبيقات. يمكنك بدلا من ذلك استخدام Azure API Management كطبقة أمام أي خدمة واجهة برمجة تطبيقات للتحقق من خصائص شهادة العميل مقابل القيم المطلوبة.

تجديد الشهادات

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

لتحميل شهادة جديدة إلى موصل واجهة برمجة تطبيقات حالي، حدد موصل واجهة برمجة التطبيقات ضمن موصلات واجهة برمجة التطبيقات وانقر على تحميل شهادة جديدة. سيتم استخدام الشهادة التي تم تحميلها مؤخرا، والتي لم تنته صلاحيتها والتي انقضى تاريخ البدء بها تلقائيا بواسطة Azure AD B2C.

توفير شهادة جديدة لموصل واجهة برمجة التطبيقات عند وجودها بالفعل.

إضافة مفتاح نهج شهادة العميل

قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد أيقونة الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة الدلائل + الاشتراكات .
اختر جميع الخدمات في الزاوية العلوية اليمنى من مدخل Microsoft Azure، ثم ابحث عن Azure AD B2C وحدده.
في صفحة Overview، حدد Identity Experience Framework.
حدد Policy Keys، ثم حدد Add.
في مربع الخيارات ، حدد تحميل.
في مربع الاسم ، اكتب RestApiClientCertificate. تتم إضافة البادئة B2C_1A_ تلقائيا.
في مربع تحميل الملف ، حدد ملف .pfx لشهادتك باستخدام مفتاح خاص.
في المربع كلمة المرور ، اكتب كلمة مرور الشهادة.
حدد إنشاء.

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

بعد إنشاء المفتاح الضروري، قم بتكوين بيانات تعريف ملف تعريف واجهة برمجة تطبيقات REST للإشارة إلى شهادة العميل.

في دليل العمل الخاص بك، افتح ملف نهج الملحق (TrustFrameworkExtensions.xml).
ابحث عن ملف تعريف واجهة برمجة تطبيقات REST التقني. على سبيل المثال REST-ValidateProfile، أو REST-GetProfile.
حدد موقع العنصر <Metadata> .
قم بتغيير نوع المصادقة إلى ClientCertificate.
قم بتغيير AllowInsecureAuthInProduction إلى false.

بعد العنصر الإغلاقي </Metadata> مباشرة، أضف مقتطف XML التالي:

<CryptographicKeys>
   <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_RestApiClientCertificate" />
</CryptographicKeys>

قصاصة XML التالية هي مثال على ملف تعريف تقني RESTful تم تكوينه باستخدام شهادة عميل HTTP:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <Item Key="AuthenticationType">ClientCertificate</Item>
        <Item Key="AllowInsecureAuthInProduction">false</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_RestApiClientCertificate" />
      </CryptographicKeys>
      ...
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

مصادقة حامل OAuth2

يتم تعريف مصادقة الرمز المميز للحامل في إطار عمل تخويل OAuth2.0: استخدام الرمز المميز للحامل (RFC 6750). في مصادقة الرمز المميز للحامل، يرسل Azure AD B2C طلب HTTP مع رمز مميز في رأس التخويل.

Authorization: Bearer <token>

رمز الحامل هو سلسلة غير شفافة. يمكن أن يكون رمزا مميزا للوصول إلى JWT أو أي سلسلة تتوقع واجهة برمجة تطبيقات REST أن يرسلها Azure AD B2C في رأس التخويل. يدعم Azure AD B2C الأنواع التالية:

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

استخدام حامل OAuth2

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

تعريف مطالبة لتخزين الرمز المميز لحاملها

توفر المطالبة تخزينا مؤقتا للبيانات أثناء تنفيذ نهج Azure AD B2C. مخطط المطالبات هو المكان الذي تعلن فيه عن مطالباتك. يجب تخزين الرمز المميز للوصول في مطالبة لاستخدامها لاحقا.

افتح ملف الملحقات للنهج الخاص بك. على سبيل المثال، SocialAndLocalAccounts/TrustFrameworkExtensions.xml
ابحث عن عنصر BuildingBlocks . إذا لم يكن العنصر موجودا، أضفه.
حدد موقع عنصر ClaimsSchema . إذا لم يكن العنصر موجودا، أضفه.
أضف المطالبات التالية إلى عنصر ClaimsSchema .

<ClaimType Id="bearerToken">
  <DisplayName>Bearer token</DisplayName>
  <DataType>string</DataType>
</ClaimType>
<ClaimType Id="grant_type">
  <DisplayName>Grant type</DisplayName>
  <DataType>string</DataType>
</ClaimType>
<ClaimType Id="scope">
  <DisplayName>scope</DisplayName>
  <DataType>string</DataType>
</ClaimType>

الحصول على رمز مميز للوصول

يمكنك الحصول على رمز مميز للوصول بإحدى الطرق العديدة، من موفر هوية موحد، عن طريق استدعاء واجهة برمجة تطبيقات REST التي ترجع رمزا مميزا للوصول، باستخدام تدفق ROPC، أو باستخدام تدفق بيانات اعتماد العميل. يتم استخدام تدفق بيانات اعتماد العميل بشكل شائع للتفاعلات من خادم إلى خادم يجب تشغيلها في الخلفية، دون تفاعل فوري مع المستخدم.

تحذير

توصي Microsoft بعدم استخدام تدفق ROPC. يتطلب هذا التدفق درجة عالية جدا من الثقة في التطبيق ، ويحمل مخاطر غير موجودة في التدفقات الأخرى. ينبغي ألّا تستخدم هذا التدفق إلا عندما لا يمكن استخدام تدفقات أخرى أكثر أمانًا.

الحصول على رمز وصول Microsoft Entra

يستخدم المثال التالي ملف تعريف تقني لواجهة برمجة تطبيقات REST لتقديم طلب إلى نقطة نهاية الرمز المميز ل Microsoft Entra باستخدام بيانات اعتماد العميل التي تم تمريرها كمصادقة HTTP الأساسية. لمزيد من المعلومات، راجع النظام الأساسي للهويات في Microsoft وتدفق بيانات اعتماد عميل OAuth 2.0.

قبل أن يتفاعل ملف التعريف الفني مع معرف Microsoft Entra للحصول على رمز مميز للوصول، تحتاج إلى تسجيل تطبيق. يعتمد Azure AD B2C على النظام الأساسي ل Microsoft Entra. يمكنك إنشاء التطبيق في مستأجر Azure AD B2C، أو في أي مستأجر Microsoft Entra تديره. لتسجيل الطلب:

قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد أيقونة الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة الدلائل + الاشتراكات .
في القائمة اليسرى، حدد Microsoft Entra ID. أو حدد All services وابحث عن Microsoft Entra ID وحدده.
حدد App registrations، ثم حدد New registration.
أدخل اسمًا للتطبيق. على سبيل المثال ، Client_Credentials_Auth_app.
ضمن أنواع الحسابات المدعومة، حدد الحسابات فِي هذا الدليل التنظيمي فقط.
حدد Register.
سجل معرف التطبيق (العميل).

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

في صفحة معرف Microsoft Entra - تسجيلات التطبيقات ، حدد التطبيق الذي قمت بإنشائه، على سبيل المثال Client_Credentials_Auth_app.
من القائمة اليسرى، في خانة Manage ، حدد Certificates & secrets .
حدد سر عميل جديد.
أدخل وصفاً لسر العميل في خانة Description . ليكن clientsecret1 على سبيل المثال.
من Expires ، حدد مدة صلاحية السر، ثم حدد Add .
سجّل القيمة المستخدمة للسر في التعليمة البرمجية لتطبيق عميلك. لا تُعرض هذه القيمة السرية مجدداًبعد مغادرة هذه الصفحة مطلقاً. يمكنك استخدام هذه القيمة كسر للتطبيق في التعليمة البرمجية لتطبيقك.

إنشاء مفاتيح نهج Azure AD B2C

تحتاج إلى تخزين معرف العميل والقيمة السرية للعميل التي قمت بتسجيلها مسبقا في مستأجر Azure AD B2C.

قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد أيقونة الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة الدلائل + الاشتراكات .
اختر جميع الخدمات في الزاوية العلوية اليمنى من مدخل Microsoft Azure، ثم ابحث عن Azure AD B2C وحدده.
في صفحة Overview، حدد Identity Experience Framework.
حدد Policy Keys ثم حدد Add.
بالنسبة إلى خيارات، اختر Manual.
أدخل اسما لمفتاح السياسة، SecureRESTClientId. تتم إضافة البادئة B2C_1A_ تلقائيا إلى اسم المفتاح.
في السر، أدخل معرف العميل الذي قمت بتسجيله مسبقا.
بالنسبة لاستخدام المفتاح، حدد Signature.
حدد إنشاء.
قم بإنشاء مفتاح نهج آخر بالإعدادات التالية:
- الاسم: SecureRESTClientSecret.
- السرية: أدخل سر العميل الذي سجلته مسبقا

بالنسبة إلى ServiceUrl، استبدل اسم المستأجر الخاص بك باسم مستأجر Microsoft Entra. راجع مرجع ملف تعريف RESTful الفني لجميع الخيارات المتاحة.

<TechnicalProfile Id="REST-AcquireAccessToken">
  <DisplayName></DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://login.microsoftonline.com/your-tenant-name.onmicrosoft.com/oauth2/v2.0/token</Item>
    <Item Key="AuthenticationType">Basic</Item>
     <Item Key="SendClaimsIn">Form</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_SecureRESTClientId" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_SecureRESTClientSecret" />
  </CryptographicKeys>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="grant_type" DefaultValue="client_credentials" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="scope" DefaultValue="https://graph.microsoft.com/.default" AlwaysUseDefaultValue="true" />
  </InputClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="bearerToken" PartnerClaimType="access_token" />
  </OutputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

إشعار

إذا كنت تستخدم المطالبات grant_type أو scope في ملفات تعريف فنية أخرى، فإننا نوصي أيضا بتحديدها DefaultValue واستخدامها AlwaysUseDefaultValue="true" لتجنب التعارضات المحتملة في الربط مقابل القيمة غير الصحيحة.

تغيير ملف تعريف REST الفني لاستخدام مصادقة الرمز المميز للحامل

لدعم مصادقة الرمز المميز للحامل في نهجك المخصص، قم بتعديل ملف التعريف الفني لواجهة برمجة تطبيقات REST باستخدام الخطوات التالية:

في دليل العمل، افتح ملف نهج ملحق TrustFrameworkExtensions.xml .
ابحث عن العقدة <TechnicalProfile> التي تتضمن Id="REST-API-SignUp".
حدد موقع العنصر <Metadata> .
قم بتغيير AuthenticationType إلى Bearer، على النحو التالي:
```
<Item Key="AuthenticationType">Bearer</Item>
```
قم بتغيير أو إضافة UseClaimAsBearerToken إلى bearerToken، على النحو التالي. bearerToken هو اسم المطالبة التي يتم استرداد الرمز المميز للحامل منها (مطالبة الإخراج منREST-AcquireAccessToken).
```
<Item Key="UseClaimAsBearerToken">bearerToken</Item>
```
أضف المطالبة من الخطوة السابقة كمطالبة إدخال:
```
<InputClaim ClaimTypeReferenceId="bearerToken"/>
```

بعد تحديث النهج الخاص بك، يجب أن يبدو ملف التعريف الفني مشابها لرمز XML التالي:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <Item Key="AuthenticationType">Bearer</Item>
        <Item Key="UseClaimAsBearerToken">bearerToken</Item>
        <Item Key="AllowInsecureAuthInProduction">false</Item>
      </Metadata>
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="bearerToken"/>
      </InputClaims>
      ...
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

اتصل بالملف الفني ل REST

لاستدعاء ملف REST-GetProfile التعريف التقني، تحتاج أولا إلى الحصول على رمز وصول Microsoft Entra باستخدام ملف التعريف التقني REST-AcquireAccessToken . يوضح المثال التالي كيفية استدعاء ملف التعريف REST-GetProfile الفني من ملف تعريف تقني للتحقق من الصحة:

<ValidationTechnicalProfiles>
  <ValidationTechnicalProfile ReferenceId="REST-AcquireAccessToken" />
  <ValidationTechnicalProfile ReferenceId="REST-GetProfile" />
</ValidationTechnicalProfiles>

يوضح المثال التالي كيفية استدعاء REST-GetProfile ملف التعريف التقني من رحلة مستخدم أو رحلة فرعية:

<OrchestrationSteps>
  <OrchestrationStep Order="2" Type="ClaimsExchange">
    <ClaimsExchanges>
      <ClaimsExchange Id="REST-AcquireAccessTokens" TechnicalProfileReferenceId="REST-AcquireAccessToken" />
    </ClaimsExchanges>
  </OrchestrationStep>

  <OrchestrationStep Order="3" Type="ClaimsExchange">
    <ClaimsExchanges>
      <ClaimsExchange Id="REST-GetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
    </ClaimsExchanges>
  </OrchestrationStep>
</OrchestrationSteps>

استخدام حامل OAuth2 ثابت

إضافة مفتاح سياسة الرمز المميز لحامل OAuth2

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

قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد أيقونة الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة الدلائل + الاشتراكات .
اختر جميع الخدمات في الزاوية العلوية اليمنى من مدخل Microsoft Azure، ثم ابحث عن Azure AD B2C وحدده.
في صفحة Overview، حدد Identity Experience Framework.
حدد Policy Keys، ثم حدد Add.
بالنسبة إلى خيارات، اختر Manual.
أدخل اسما لمفتاح النهج. على سبيل المثال، RestApiBearerToken تتم إضافة البادئة B2C_1A_ تلقائيا إلى اسم المفتاح.
في Secret، أدخل سر العميل الذي سجلته مسبقا.
بالنسبة لاستخدام المفتاح، حدد Encryption.
حدد إنشاء.

تكوين ملف التعريف الفني لواجهة برمجة تطبيقات REST لاستخدام مفتاح نهج الرمز المميز للحامل

بعد إنشاء المفتاح الضروري، قم بتكوين بيانات تعريف ملف تعريف واجهة برمجة تطبيقات REST للإشارة إلى الرمز المميز للحامل.

في دليل العمل الخاص بك، افتح ملف نهج الملحق (TrustFrameworkExtensions.xml).
ابحث عن ملف تعريف واجهة برمجة تطبيقات REST التقني. على سبيل المثال REST-ValidateProfile، أو REST-GetProfile.
حدد موقع العنصر <Metadata> .
قم بتغيير نوع المصادقة إلى Bearer.
قم بتغيير AllowInsecureAuthInProduction إلى false.

بعد العنصر الإغلاقي </Metadata> مباشرة، أضف مقتطف XML التالي:

<CryptographicKeys>
   <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_RestApiBearerToken" />
</CryptographicKeys>

قصاصة XML التالية هي مثال على ملف تعريف تقني RESTful تم تكوينه باستخدام مصادقة الرمز المميز للحامل:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <Item Key="AuthenticationType">Bearer</Item>
        <Item Key="AllowInsecureAuthInProduction">false</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_RestApiBearerToken" />
      </CryptographicKeys>
      ...
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

أضف مرجع ملف تعريف الملف الشخصي الفني للتحقق من الصحة إلى ملف التعريف الفني للتسجيل، والذي يستدعي ملف REST-AcquireAccessTokenتعريف . يعني هذا السلوك أن Azure AD B2C ينتقل لإنشاء الحساب في الدليل فقط بعد التحقق من الصحة بنجاح.

على سبيل المثال:

```XML
<ValidationTechnicalProfiles>
   ....
   <ValidationTechnicalProfile ReferenceId="REST-AcquireAccessToken" />
   ....
</ValidationTechnicalProfiles>

مصادقة مفتاح واجهة برمجة التطبيقات

تستخدم بعض الخدمات آلية "مفتاح واجهة برمجة التطبيقات" لتعتيم الوصول إلى نقاط نهاية HTTP أثناء التطوير من خلال مطالبة المتصل بتضمين مفتاح فريد كعنوان HTTP أو معلمة استعلام HTTP. بالنسبة لوظائف Azure، يمكنك تحقيق ذلك عن طريق تضمين code معلمة كاستعلام في عنوان URL لنقطة النهاية لموصل واجهة برمجة التطبيقات. على سبيل المثال، https://contoso.azurewebsites.net/api/endpoint?code=0123456789).

هذه ليست آلية يجب استخدامها بمفردها في الإنتاج. لذلك، يلزم دائما تكوين المصادقة الأساسية أو المصادقة الشهادات. إذا كنت لا ترغب في تنفيذ أي طريقة مصادقة (غير موصى بها) لأغراض التطوير، فيمكنك تحديد المصادقة "الأساسية" في تكوين موصل واجهة برمجة التطبيقات واستخدام قيم username مؤقتة لها والتي password يمكن لواجهة برمجة التطبيقات الخاصة بك تجاهلها أثناء تنفيذ التفويض المناسب.

مفتاح واجهة برمجة التطبيقات هو معرف فريد يستخدم لمصادقة مستخدم للوصول إلى نقطة نهاية واجهة برمجة تطبيقات REST. يتم إرسال المفتاح في رأس HTTP مخصص. على سبيل المثال، يستخدم مشغل Azure Functions HTTP رأس x-functions-key HTTP لتحديد مقدم الطلب.

إضافة مفاتيح نهج مفتاح واجهة برمجة التطبيقات

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

قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد أيقونة الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة الدلائل + الاشتراكات .
اختر جميع الخدمات في الزاوية العلوية اليمنى من مدخل Microsoft Azure، ثم ابحث عن Azure AD B2C وحدده.
في صفحة Overview، حدد Identity Experience Framework.
حدد Policy Keys، ثم حدد Add.
بالنسبة إلى خيارات، حدد يدوي.
بالنسبة إلى الاسم، اكتب RestApiKey. قد تتم إضافة البادئة B2C_1A_ تلقائيا.
في المربع سري ، أدخل مفتاح واجهة برمجة تطبيقات REST.
لاستخدام المفتاح، حدد تشفير.
حدد إنشاء.

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

بعد إنشاء المفتاح الضروري، قم بتكوين بيانات تعريف ملف تعريف واجهة برمجة تطبيقات REST للإشارة إلى بيانات الاعتماد.

في دليل العمل الخاص بك، افتح ملف نهج الملحق (TrustFrameworkExtensions.xml).
ابحث عن ملف تعريف واجهة برمجة تطبيقات REST التقني. على سبيل المثال REST-ValidateProfile، أو REST-GetProfile.
حدد موقع العنصر <Metadata> .
قم بتغيير نوع المصادقة إلى ApiKeyHeader.
قم بتغيير AllowInsecureAuthInProduction إلى false.

بعد العنصر الإغلاقي </Metadata> مباشرة، أضف مقتطف XML التالي:

<CryptographicKeys>
    <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
</CryptographicKeys>

يحدد معرف مفتاح التشفير رأس HTTP. في هذا المثال، يتم إرسال مفتاح واجهة برمجة التطبيقات ك x-functions-key.

يعد قصاصة XML التالية مثالا على ملف تعريف تقني RESTful تم تكوينه لاستدعاء وظيفة Azure مع مصادقة مفتاح واجهة برمجة التطبيقات:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <Item Key="AuthenticationType">ApiKeyHeader</Item>
        <Item Key="AllowInsecureAuthInProduction">false</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
      </CryptographicKeys>
      ...
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

ابدأ مع عيناتنا.

تعرف على المزيد حول عنصر ملف التعريف الفني RESTful في مرجع السياسة المخصصة.

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-05-08

واجهات برمجة التطبيقات الآمنة المستخدمة لموصلات واجهة برمجة التطبيقات في Azure AD B2C

المتطلبات الأساسية

مصادقة HTTP الأساسية

إضافة اسم مستخدم واجهة برمجة تطبيقات REST ومفاتيح سياسة كلمة المرور

تكوين ملف التعريف التقني لواجهة برمجة تطبيقات REST لاستخدام مصادقة HTTP الأساسية

مصادقة شهادة عميل HTTPS

إنشاء شهادة

الخيار 1: استخدام Azure Key Vault (موصى به)

الخيار 2: إعداد شهادة موقعة ذاتيا باستخدام الوحدة النمطية PowerShell

تكوين موصل واجهة برمجة التطبيقات

تنفيذ قرارات التفويض

تجديد الشهادات

إضافة مفتاح نهج شهادة العميل

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

مصادقة حامل OAuth2

استخدام حامل OAuth2

تعريف مطالبة لتخزين الرمز المميز لحاملها

الحصول على رمز مميز للوصول

الحصول على رمز وصول Microsoft Entra

إنشاء مفاتيح نهج Azure AD B2C

تغيير ملف تعريف REST الفني لاستخدام مصادقة الرمز المميز للحامل

اتصل بالملف الفني ل REST

استخدام حامل OAuth2 ثابت

إضافة مفتاح سياسة الرمز المميز لحامل OAuth2

تكوين ملف التعريف الفني لواجهة برمجة تطبيقات REST لاستخدام مفتاح نهج الرمز المميز للحامل

مصادقة مفتاح واجهة برمجة التطبيقات

إضافة مفاتيح نهج مفتاح واجهة برمجة التطبيقات

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

المحتوى ذو الصلة

الملاحظات

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