مشاركة عبر

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

  • مقالة

قبل أن تبدأ استخدم اختر نوع نهج المحدد لاختيار نوع النهج الذي تعده. يوفر Azure Active Directory B2C طريقتين لتحديد كيفية تفاعل المستخدمين مع تطبيقاتك: من خلال تدفقات محددة مسبقا للمستخدمين أو من خلال سياسات مخصصة قابلة للتكوين بشكل كامل. تختلف الخطوات المطلوبة في هذه المقالة لكل أسلوب.

نظرة عامة

كمطور أو مسؤول تكنولوجيا المعلومات، يمكنك استخدام موصلات API لدمج تدفق المستخدم الاشتراك مع واجهات برمجة التطبيقات REST لتخصيص تجربة الاشتراك والتكامل مع الأنظمة الخارجية. على سبيل المثال، مع موصلات API، يمكنك:

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

يوفر موصل API Azure AD B2C المعلومات المطلوبة لاستدعاء نقطة نهاية API عن طريق تعريف عنوان URL لنقطة نهاية HTTP والمصادقة لاستدعاء API. بمجرد تكوين موصل API، يمكنك تمكينه لخطوة معينة في تدفق المستخدم. عندما يصل مستخدم إلى هذه الخطوة في تدفق الاشتراك، يتم استدعاء موصل API ويتم تجسيده كذلك كطلب HTTP POST إلى واجهة برمجة التطبيقات الخاصة بك، وإرسال معلومات المستخدم ("المطالبات") كأزواج قيمة المفتاح في نص JSON. يمكن أن تؤثر استجابة API تنفيذ تدفق المستخدم. على سبيل المثال، يمكن للاستجابة API منع مستخدم من الاشتراك، أو مطالبة المستخدم بإعادة إدخال المعلومات، أو الكتابة فوق سمات المستخدم.

حيث يمكنك تمكين موصل API في تدفق المستخدم

هناك ثلاثة أماكن في تدفق المستخدم حيث يمكنك تمكين موصل API:

  • بعد الاتحاد مع موفر الهوية أثناء التسجيل - ينطبق على تجارب الاشتراك فقط
  • قبل إنشاء المستخدم - ينطبق على تجارب الاشتراك فقط
  • قبل إرسال الرمز المميز (معاينة) - ينطبق على عمليات الاشتراك وعمليات تسجيل الدخول

بعد الاتحاد مع موفر الهوية أثناء التسجيل

يتم استدعاء موصل API في هذه الخطوة في عملية التسجيل مباشرة بعد مصادقة المستخدم مع موفر هوية (مثل Google وFacebook ومعرف Microsoft Entra). هذه الخطوة تسبق صفحة مجموعة السمات، وهي النموذج المقدم للمستخدم لتجميع سمات المستخدم. لا يتم استدعاء هذه الخطوة إذا كان المستخدم يقوم بالتسجيل باستخدام حساب محلي. فيما يلي أمثلة لسيناريوهات موصل API التي قد تقوم بتمكينها في هذه الخطوة:

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

قبل إنشاء المستخدم

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

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

قبل إرسال الرمز المميز (معاينة)

ملاحظة

هذه الميزة قيد المعاينة العامة.

يتم استدعاء موصل API في هذه الخطوة في عملية التسجيل أو تسجيل الدخول قبل إصدار رمز مميز. فيما يلي أمثلة للسيناريوهات التي قد تقوم بتمكينها في هذه الخطوة:

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

إطار عمل تجربة الهوية، الذي يقوم عليه Azure Active Directory B2C (Azure AD B2C)، يمكن أن يتكامل مع واجهات برمجة التطبيقات RESTful ضمن رحلة المستخدم. توضح هذه المقالة كيفية إنشاء رحلة مستخدم تتفاعل مع خدمة RESTful باستخدام ملف تعريف فني RESTful.

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

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

رسم تخطيطي لتبادل مطالبات خدمة RESTful

ملاحظة

إذا كان هناك استجابة بطيئة أو لا استجابة من خدمة RESTful إلى Azure AD B2C المهلة 30 ثانية و عدد إعادة المحاولة مرتين (بمعنى أن هناك 3 محاولات في المجموع). حاليا، لا يمكنك تكوين إعدادات المهلة وإعادة المحاولة.

استدعاء خدمة RESTful

يتضمن التفاعل تبادل المطالبات للمعلومات بين مطالبات REST API وAzure AD B2C. يمكنك تصميم التكامل مع خدمات RESTful بالطرق التالية:

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

    • إرسال المطالبات إلى REST API الخاص بك.
    • التحقق من صحة المطالبات، ورمي رسائل الخطأ المخصصة التي يتم عرضها للمستخدم.
    • إرسال المطالبات من API REST إلى خطوات التزامن التالية.

  • قم بتبديل المطالبات. يمكن تكوين تبادل المطالبات المباشرة عن طريق استدعاء ملف تعريف تقني ل REST API مباشرة من خطوة تزامن لرحلة مستخدم. يقتصر هذا التعريف على:

    • إرسال المطالبات إلى REST API الخاص بك.
    • التحقق من صحة المطالبات، ورمي رسائل الخطأ المخصصة التي يتم إرجاعها إلى التطبيق.
    • إرسال المطالبات من API REST إلى خطوات التزامن التالية.

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

  • أثناء تسجيل الدخول، قبل أن يتحقق Azure AD B2C من صحة بيانات الاعتماد
  • مباشرة بعد تسجيل الدخول
  • قبل أن يقوم Azure AD B2C بإنشاء حساب جديد في الدليل
  • بعد قيام Azure AD B2C بإنشاء حساب جديد في الدليل
  • قبل أن يصدر Azure AD B2C رمز وصول مميز

التحقق من صحة مجموعة التشكيل الجانبي التقني

إرسال البيانات

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

يمكنك تكوين كيفية إرسال مطالبات الإدخال إلى موفر مطالبات RESTful باستخدام سمة SendClaimsIn. القيم المُحتملة هي:

  • النص الأساسي، الذي تم إرساله في نص طلب HTTP POST بتنسيق JSON.
  • نموذج، تم إرساله في نص طلب HTTP POST '&' بتنسيق قيمة مفتاح منفصل.
  • عنوان، تم إرساله في عنوان طلب HTTP GET.
  • QueryString، المرسلة في سلسلة استعلام طلب HTTP GET.

عندما يتم تكوين خيار Body، يسمح لك ملف تعريف REST API الفني بإرسال حمولة JSON معقدة إلى نقطة نهاية. لمزيد من المعلومات، راجع إرسال حمولة JSON.

تلقي البيانات

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

مطالبات الإخراج تحليلها من قبل موفر مطالبات RESTful نتوقع دائما لتحليل استجابة الجسم JSON شقة، مثل:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

يجب أن تبدو مطالبات الإخراج مثل مقتطف xml التالي:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

معالجة القيم الخالية

يتم استخدام قيمة فارغة في قاعدة بيانات عندما تكون القيمة في عمود غير معروف أو مفقودة. لا تقم بتضمين مفاتيح JSON بقيمة null . في المثال التالي، إرجاع قيمة البريد null الإلكتروني:

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

عندما يكون العنصر فارغا، إما:

  • حذف زوج قيمة المفتاح من JSON.
  • إرجاع قيمة تتوافق مع نوع بيانات المطالبة بـ B2C AD Azure. على سبيل المثال، string لنوع بيانات، إرجاع سلسلة فارغة "" . بالنسبة integer لنوع بيانات، قم بإرجاع قيمة 0 صفرية . بالنسبة dateTime لنوع بيانات، بادر بإرجاع قيمة دنيا 1970-00-00T00:00:00.0000000Z.

يوضح المثال التالي كيفية معالجة قيمة خالية. تم حذف البريد الإلكتروني من JSON:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

تحليل جسم JSON متداخل

لتحليل استجابة نص JSON المتداخلة تعيين بيانات تعريف ResolveJsonPathsInJsonTokens إلى true. في المطالبة الإخراج تعيين PartnerClaimType إلى عنصر مسار JSON الذي تريد إخراج.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

يجب أن تبدو مطالبات الإخراج مثل مقتطف xml التالي:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

ترجمة واجهة برمجة تطبيقات REST

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

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</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-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

معالجة رسائل الخطأ

قد تحتاج واجهة برمجة تطبيقات REST إلى إرجاع رسالة خطأ، مثل "لم يتم العثور على المستخدم في نظام CRM". إذا حدث خطأ، يجب أن ترجع واجهة برمجة تطبيقات REST رسالة خطأ HTTP 409 (رمز حالة استجابة التعارض). لمزيد من المعلومات، راجع ملف تعريف تقني للتحقق من الصحة

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

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

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

يمكن تطوير REST API على أي منصة وكتابتها بأي لغة برمجة، طالما أنها آمنة ويمكن إرسال المطالبات وتلقيها بتنسيق JSON.

يأتي الطلب إلى خدمة REST API من خوادم Azure AD B2C. يجب نشر خدمة REST API إلى نقطة نهاية HTTPS يمكن الوصول إليها بشكل عام. سوف تصل استدعاءات REST API من عنوان IP لمركز بيانات Azure.

يمكنك استخدام وظائف السحابة بدون خادم، مثل مشغلات HTTP في وظائف Azure لتسهيل التطوير.

يجب تصميم خدمة REST API ومكوناته الأساسية (مثل قاعدة البيانات ونظام الملفات) لتكون متوفرة بشكل كبير.

هام

يجب أن تتوافق نقاط النهاية الخاصة بك مع متطلبات أمان Microsoft Azure AD B2C. أُوقِف العمل بإصدارات وأصفار TLS الأقدم. لمزيد من المعلومات، راجع متطلبات مجموعة TLS والتشفير.

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

راجع المقالات التالية للحصول على أمثلة من استخدام ملف تعريف تقني RESTful: