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

مقالة
11/20/2023

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

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

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

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

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

يتم تعريف مصادقة HTTP الأساسية في RFC 2617. تعمل المصادقة الأساسية كما يلي:

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

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

سجل دخولك إلى مدخل Azure.
ضمن خدمات Azure، حدد Azure AD B2C أو ابحث عن Azure AD B2C وحدده.
حدد API connectors، ثم حدد API Connector الذي تريد تكوينه.
بالنسبة لـAuthentication type، حدد Basic.
قم بتوفير Username وPassword لنقطة نهاية واجهة برمجة التطبيقات REST الخاصة بك.
حدد حفظ.

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

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

سجل دخولك إلى مدخل Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد رمز الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة Directories + subscriptions.
اختر كل الخدمات في الزاوية العلويةِ اليسرى من مدخل Microsoft Azure، ثم ابحث عن Azure AD B2Cوحدده.
في صفحة نظرة عامة، حدد Identity Experience Framework.
حدد مفاتيح النهج ثم حدد إضافة.
بالنسبة لـOptions، حدد Manual.
بالنسبة للاسم، اكتب RestApiUsername. قد تتم إضافة B2C_1A_ البادئة تلقائيا.
في المربع Secret ، أدخل اسم مستخدم REST API.
لمفتاح الاستخدام، حدد توقيع.
حدد إنشاء.
حدد Policy Keys مرة أخرى.
حدد إضافة.
بالنسبة لـOptions، حدد Manual.
بالنسبة للاسم، اكتب RestApiPassword. قد تتم إضافة B2C_1A_ البادئة تلقائيا.
في المربع Secret ، أدخل كلمة مرور REST API.
لمفتاح الاستخدام، حدد توقيع.
حدد إنشاء.

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

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

في الدليل المشغَّل، افتح ملف نهج الملحق (TrustFrameworkExtensions.xml).
ابحث عن الملف التقني لواجهة برمجة التطبيقات REST. على سبيل المثال REST-ValidateProfile، أو REST-GetProfile.
<Metadata> حدد موقع العنصر.
تغيير AuthenticationType إلى 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
نوع Acton مدى الحياة: 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) ولا توفر ضمانات الأمان لشهادة موقعة من قبل هيئة شهادات.

Windows
ماك

في نظام التشغيل Windows، استخدم الأمر 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.
حدد الشهادة، ثم حدد الإجراء>كل المهام>تصدير.
حدد التالي>نعم، تصدير المفتاح الخاص>التالي.
اقبل الإعدادات الافتراضية لـ تصدير تنسيق الملف، ثم حدد التالي.
قم بتمكين خيار كلمة المرور، وأدخل كلمة مرور للشهادة، ثم حدد التالي.
لتحديد موقع لحفظ الشهادة الخاصة بك، حدد استعراض وتنقل إلى الدليل الذي تختاره.
في نافذة Save As، أدخل File name، ثم حدد Save.
حدد التالي>وإنهاء.

لكي يقبل Azure AD B2C كلمة مرور ملف pfx. يجب تشفير كلمة المرور باستخدام الخيار TripleDES-SHA1 في الأداة المساعدة Windows Certificate Store Export، بدلاً من AES256-SHA256.

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

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

سجل دخولك إلى مدخل Azure.
من خدمات Azure، حدد Azure AD B2C.
حدد API connectors، ثم حدد API Connector الذي تريد تكوينه.
بالنسبة لـ Authentication type، حدد Certificate.
في المربع Upload certificate حدد ملف .pfx الخاص بالشهادة الخاصة بك باستخدام مفتاح خاص.
في المربع Enter Password اكتب كلمة مرور الشهادة.
حدد حفظ.

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

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

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

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

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

Providing a new certificate to an API connector when one already exists.

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

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

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

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

في الدليل المشغَّل، افتح ملف نهج الملحق (TrustFrameworkExtensions.xml).
ابحث عن الملف التقني لواجهة برمجة التطبيقات REST. على سبيل المثال REST-ValidateProfile، أو REST-GetProfile.
<Metadata> حدد موقع العنصر.
تغيير AuthenticationType إلى 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 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 من قائمة Directories + subscriptions.
في القائمة اليسرى، حدد Microsoft Entra ID. أو حدد All services وابحث عن Microsoft Entra ID وحدده.
حدد App registrations، ثم حدد New registration.
أدخل Name للتطبيق. على سبيل المثال، Client_Credentials_Auth_app.
لأنواع الحسابات المدعومة، حدد الحسابات في هذا الدليل التنظيمي فقط.
حدد السجل.
سجل معرف التطبيق (العميل).

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

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

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

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

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

بالنسبة إلى ServiceUrl، استبدل your-tenant-name باسم مستأجر 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، كما يلي. الرمز المميز للحامل هو اسم المطالبة التي يتم استرداد الرمز المميز للحامل منها (مطالبة الإخراج من 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 من قائمة Directories + subscriptions.
اختر كل الخدمات في الزاوية العلويةِ اليسرى من مدخل Microsoft Azure، ثم ابحث عن Azure AD B2Cوحدده.
في صفحة نظرة عامة، حدد Identity Experience Framework.
حدد مفاتيح النهج ثم حدد إضافة.
بالنسبة للخيارات، اختر Manual .
أدخِل اسمًا لمفتاح النهج. على سبيل المثال، RestApiBearerToken. تتم إضافة البادئة B2C_1A_ تلقائيًا إلى اسم مفتاحك.
في بيانات، أدخل بيانات العميل التي سجلتها سابقًا.
بالنسبة إلى Key usage، حدد Encryption.
حدد إنشاء.

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

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

في الدليل المشغَّل، افتح ملف نهج الملحق (TrustFrameworkExtensions.xml).
ابحث عن الملف التقني لواجهة برمجة التطبيقات REST. على سبيل المثال REST-ValidateProfile، أو REST-GetProfile.
<Metadata> حدد موقع العنصر.
تغيير AuthenticationType إلى 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>

مصادقة مفتاح API

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

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

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

إضافة مفاتيح نهج مفتاح API

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

سجل دخولك إلى مدخل Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد رمز الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة Directories + subscriptions.
اختر كل الخدمات في الزاوية العلويةِ اليسرى من مدخل Microsoft Azure، ثم ابحث عن Azure AD B2Cوحدده.
في صفحة نظرة عامة، حدد Identity Experience Framework.
حدد مفاتيح النهج ثم حدد إضافة.
بالنسبة لـOptions، حدد Manual.
بالنسبة للاسم، اكتب RestApiKey. قد تتم إضافة B2C_1A_ البادئة تلقائيا.
في المربع Secret ، أدخل مفتاح REST API.
لمفتاح الاستخدام، حدد توقيع.
حدد إنشاء.

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

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

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

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

يعرف معرف مفتاح التشفير رأس HTTP. في هذا المثال، يتم إرسال مفتاح API ك x-functions-key.

تمثل قصاصة XML البرمجية التالية مثالاً عن ملف التعريف الفني لـ RESTFUL المكون لاستدعاء وظيفة Azure مع مصادقة مفتاح API:

<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 في مرجع النهج المخصص.

مشاركة عبر

واجهات برمجة التطبيقات الآمنة المستخدمة لموصلات API في 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 لاستخدام مفتاح نهج الرمز المميز للحامل

مصادقة مفتاح API

إضافة مفاتيح نهج مفتاح API

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

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

الملاحظات

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