عناصر تحكم العرض

مقالة
01/11/2024

إشعار

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

التحكم في العرض هو عنصر واجهة مستخدم له وظائف خاصة ويتفاعل مع خدمة Microsoft Azure Active Directory B2C. يسمح للمستخدم بتنفيذ الإجراءات على الصفحة التي تستدعي ملف التعريف التقني الخاص بالتحقق من الصحة في النهاية الخلفية. يتم عرض عناصر التحكم في العرض على الصفحة ويتم الرجوع إليها بواسطة ملف التعريف التقني الذي تم تأكيده ذاتياً.

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

في قسم بيانات التعريف في ملف التعريف الفني المؤكد ذاتياً يحتاج ContentDefinition المشار إليه مرجعيًا إلى تعيين DataUriإصدار عقد الصفحة رقم 2.1.9 أو أعلى. على سبيل المثال:

<ContentDefinition Id="api.selfasserted">
  <LoadUri>~/tenant/default/selfAsserted.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:selfasserted:2.1.9</DataUri>
  ...

تحديد ضوابط العرض

يحتوي عنصر DisplayControl على السمات التالية:

السمة	المطلوب	الوصف
`Id`	‏‏نعم‬	معرّف يُستخدم للتحكم في العرض. يمكن الإشارة إليه مرجعياً.
`UserInterfaceControlType`	‏‏نعم‬	نوع التحكم في العرض. يتم دعم VerificationControl وعناصر تحكم TOTP وعناصر تحكم CAPTCHA حاليا.

التحكم في التحقق

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

Screenshot showing email verification display control

عناصر تحكم TOTP

عناصر التحكم في عرض TOTP هي مجموعة من عناصر تحكم العرض التي توفر مصادقة متعددة العوامل لـ TOTP مع تطبيق Microsoft Authenticator. توضح الصورة التالية صفحة تسجيل TOTP مع عناصر تحكم العرض الثلاثة.

Screenshot showing TOTP display controls

QrCodeControl

يحتوي عنصر DisplayControl على العناصر التالية:

العنصر	الأحداث	‏‏الوصف
`InputClaims`	0:1	يتم استخدامInputClaims لملء قيمة المطالبات التي سيتم جمعها من المستخدم مسبقاً. لمزيد من المعلومات، راجع عنصر InputClaims.
`DisplayClaims`	0:1	تُستخدم DisplayClaims لتمثيل المطالبات التي سيتم جمعها من المستخدم. لمزيد من المعلومات، راجع عنصر DisplayClaim.
`OutputClaims`	0:1	تُستخدمOutputClaims لتمثيل المطالبات المحفوظة مؤقتاً لـ DisplayControl هذه. لمزيد من المعلومات، راجع عنصر OutputClaims.
`Actions`	0:1	تُستخدمالإجراءات لسرد ملفات التعريف الفنية للتحقق من الصحة لاستدعاء إجراءات المستخدم التي تحدث في الواجهة الأمامية.

مطالبات الإدخال

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

يملأ المثال التالي عنوان البريد الإلكتروني مسبقاً ليتم التحقق من العنوان الموجود بالفعل.

<DisplayControl Id="emailControl" UserInterfaceControlType="VerificationControl">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="emailAddress" />
  </InputClaims>
  ...

عرض المطالبات

يتطلب كل نوع من أنواع التحكم في العرض مجموعة مختلفة من مطالبات العرض وoutput claims, and actions التي يتعين تنفيذها.

على غرار display claims defined in a self-asserted technical profile، تمثل مطالبات العرض المطالبات التي سيتم جمعها من المستخدم ضمن التحكم في العرض. يحتاج عنصر ClaimType المشار إليه إلى تحديد عنصر UserInputType لنوع إدخال المستخدم الذي يدعمه Azure AD B2C، مثل TextBox أو DropdownSingleSelect. إذا كانت قيمة مطالبة العرض مطلوبة من خلال Action فقم بتعيين Required على true لإجبار المستخدم على تقديم قيمة لمطالبة العرض المحددة هذه.

مطلوب مطالبات عرض معينة لأنواع معينة من التحكم في العرض. على سبيل المثال، VerificationCode مطلوبة للتحكم في نوع VerificationControl. استخدم السمة ControlClaimType لتحديد DisplayClaim المخصص لتلك المطالبة المطلوبة. على سبيل المثال:

<DisplayClaim ClaimTypeReferenceId="otpCode" ControlClaimType="VerificationCode" Required="true" />

مطالبات الإخراج

لا يتم إرسال مطالبات الإخراج لعنصر تحكم العرض إلى خطوة التنسيق التالية. يتم حفظها مؤقتاً فقط لجلسة التحكم في العرض الحالية. يمكن مشاركة هذه المطالبات المؤقتة بين الإجراءات المختلفة لنفس التحكم في العرض.

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

عرض إجراءات التحكم

إجراءات عنصر التحكم في العرض هي الإجراءات التي تحدث في الواجهة الخلفية Microsoft Azure Active Directory B2C عندما يقوم المستخدم بتنفيذ إجراء معين من جانب العميل (المستعرض). على سبيل المثال، عمليات التحقق التي يجب إجراؤها عندما يحدد المستخدم زراً على الصفحة.

يحدد الإجراء قائمة ملفات التعريف التقنية للتحقق من صحة. يتم استخدامها للتحقق من صحة بعض أو كل مطالبات العرض الخاصة بالتحكم في العرض. يقوم ملف التعريف الفني للتحقق من الصحة بالتحقق من صحة إدخال المستخدم وقد يعرض خطأً للمستخدم. يمكنك استخدام ContinueOnErrorو ContinueOnSuccessو Preconditions في إجراء التحكم في العرض على غرار الطريقة المستخدمة في ملفات التعريف الفنية للتحقق في ملف تعريف فني مؤكد ذاتيًا.

الإجراءات

يحتوي عنصر Actions على العنصر التالي:

العنصر	الأحداث	‏‏الوصف
`Action`	1:n	قائمة الإجراءات المطلوب تنفيذها.

الإجراء

يحتوي عنصر Action على السمة التالية:

السمة	المطلوب	الوصف
`Id`	‏‏نعم‬	نوع العملية. القيم الممكنة: `SendCode` أو `VerifyCode`. ترسل القيمة `SendCode` رمزاً إلى المستخدم. قد يحتوي هذا الإجراء على ملفي تعريف تقنيين للتحقق: أحدهما لإنشاء رمز والآخر لإرساله. تتحقق قيمة `VerifyCode` من الرمز الذي كتبه المستخدم في مربع نص الإدخال.

يحتوي عنصر Action على العنصر التالي:

العنصر	الأحداث	‏‏الوصف
`ValidationClaimsExchange`	1:1	معرفات ملفات التعريف التقنية المستخدمة للتحقق من صحة بعض أو كل مطالبات العرض الخاصة بالملف الفني المرجعي. يجب أن تظهر جميع مطالبات الإدخال الخاصة بالملف الفني المشار إليه في مطالبات العرض الخاصة بالملف الفني المرجعي.

ValidationClaimsExchange

يحتوي عنصر ValidationClaimsExchange على العنصر التالي:

العنصر	الأحداث	‏‏الوصف
`ValidationClaimsExchangeTechnicalProfile`	1:n	ملف تعريف تقني يتم استخدامه للتحقق من صحة بعض أو كل مطالبات العرض الخاصة بالملف الفني المرجعي.

يحتوي عنصر ValidationClaimsExchangeTechnicalProfile على السمة التالية:

السمة	المطلوب	الوصف
`TechnicalProfileReferenceId`	‏‏نعم‬	معرّف ملف تعريف فني تم تحديده بالفعل في النهج أو النهج الأصلي.

يحتوي عنصر ValidationClaimsExchangeTechnicalProfile على العنصر التالي:

العنصر	الأحداث	‏‏الوصف
`Preconditions`	0:1	قائمة بالشروط المسبقة التي يجب استيفاؤها حتى يتم تنفيذ ملف التعريف الفني للتحقق.

يحتوي العنصر Precondition على السمات التالية:

السمة	المطلوب	الوصف
`Type`	‏‏نعم‬	نوع الفحص أو الاستعلام المطلوب إجراؤه للشرط المسبق. القيم الممكنة: `ClaimsExist` أو `ClaimEquals`. يحدد`ClaimsExist` أنه يجب تنفيذ الإجراءات في حالة وجود المطالبات المحددة في مجموعة المطالبات الحالية للمستخدم. يحدد`ClaimEquals` أنه يجب تنفيذ الإجراءات في حالة وجود المطالبة المحددة وقيمتها تساوي القيمة المحددة.
`ExecuteActionsIf`	‏‏نعم‬	يشير إلى ما إذا كان يجب تنفيذ الإجراءات في الشرط المسبق إذا كان الاختبار صحيحاً أو خطأ.

يحتوي العنصر Precondition على العناصر التالية:

العنصر	الأحداث	‏‏الوصف
`Value`	1:n	البيانات التي يستخدمها الفحص. إذا كان نوع هذا الفحص هو `ClaimsExist`، فإن هذا الحقل يحدد ClaimTypeReferenceId للاستعلام عنه. إذا كان نوع الشيك هو `ClaimEquals`، فإن هذا الحقل يحدد ClaimTypeReferenceId للاستعلام عنه. حدد القيمة التي سيتم التحقق منها في عنصر قيمة آخر.
`Action`	1:1	الإجراء الذي يجب اتخاذه إذا كان التحقق من الشرط المسبق ضمن خطوة التزامن صحيحاً. يتم تعيين قيمة Action is set to `SkipThisValidationTechnicalProfile`، والتي تحدد أنه لا ينبغي تنفيذ ملف التعريف الفني المصاحب للتحقق.

يرسل المثال التالي عنوان البريد الإلكتروني ويتحقق منه باستخدام ملف التعريف الفني Microsoft Entra ID SSPR.

<DisplayControl Id="emailVerificationControl" UserInterfaceControlType="VerificationControl">
  <InputClaims></InputClaims>
  <DisplayClaims>
    <DisplayClaim ClaimTypeReferenceId="email" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="verificationCode" ControlClaimType="VerificationCode" Required="true" />
  </DisplayClaims>
  <OutputClaims></OutputClaims>
  <Actions>
    <Action Id="SendCode">
      <ValidationClaimsExchange>
        <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AadSspr-SendCode" />
      </ValidationClaimsExchange>
    </Action>
    <Action Id="VerifyCode">
      <ValidationClaimsExchange>
        <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AadSspr-VerifyCode" />
      </ValidationClaimsExchange>
    </Action>
  </Actions>
</DisplayControl>

يرسل المثال التالي رمزاً إما عبر البريد الإلكتروني أو الرسائل القصيرة بناءً على اختيار المستخدم لمطالبة mfaType بشروط مسبقة.

<Action Id="SendCode">
  <ValidationClaimsExchange>
    <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AzureMfa-SendSms">
      <Preconditions>
        <Precondition Type="ClaimEquals" ExecuteActionsIf="true">
          <Value>mfaType</Value>
          <Value>email</Value>
          <Action>SkipThisValidationTechnicalProfile</Action>
        </Precondition>
      </Preconditions>
    </ValidationClaimsExchangeTechnicalProfile>
    <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AadSspr-SendEmail">
      <Preconditions>
        <Precondition Type="ClaimEquals" ExecuteActionsIf="true">
          <Value>mfaType</Value>
          <Value>phone</Value>
          <Action>SkipThisValidationTechnicalProfile</Action>
        </Precondition>
      </Preconditions>
    </ValidationClaimsExchangeTechnicalProfile>
  </ValidationClaimsExchange>
</Action>

الرجوع إلى ضوابط العرض

تتم الإشارة إلى عناصر التحكم في العرض في display claims self-asserted technical profile.

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

<TechnicalProfile Id="SelfAsserted-ProfileUpdate">
  ...
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim DisplayControlReferenceId="PhoneVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />

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

للحصول على عينات من استخدام التحكم في العرض، راجع:

مشاركة عبر