Wyświetl kontrolki

Artykuł
01/11/2024

Uwaga

W usłudze Azure Active Directory B2C zasady niestandardowe są przeznaczone głównie do rozwiązywania złożonych scenariuszy. W przypadku większości scenariuszy zalecamy używanie wbudowanych przepływów użytkownika. Jeśli nie zostało to zrobione, dowiedz się więcej o niestandardowym pakiecie startowym zasad w temacie Wprowadzenie do zasad niestandardowych w usłudze Active Directory B2C.

Kontrolka wyświetlania to element interfejsu użytkownika, który ma specjalne funkcje i współdziała z usługą zaplecza azure Active Directory B2C (Azure AD B2C). Umożliwia on użytkownikowi wykonywanie akcji na stronie, które wywołują profil techniczny weryfikacji na zapleczu. Kontrolki wyświetlania są wyświetlane na stronie i są przywoływane przez własny profil techniczny.

Wymagania wstępne

W sekcji Metadane samodzielnego profilu technicznego przywoływane elementy ContentDefinition muszą mieć DataUri ustawioną wersję kontraktu strony w wersji 2.1.9 lub nowszej. Na przykład:

<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>
  ...

Definiowanie kontrolek wyświetlania

Element DisplayControl zawiera następujące atrybuty:

Atrybut	Wymagania	opis
`Id`	Tak	Identyfikator używany dla kontrolki wyświetlania. Można się do niego odwoływać.
`UserInterfaceControlType`	Tak	Typ kontrolki wyświetlania. Obecnie obsługiwane są formanty VerificationControl, TOTP i CAPTCHA.

Kontrola weryfikacji

Kontrolka wyświetlania weryfikacji weryfikuje oświadczenia, na przykład adres e-mail lub numer telefonu, z kodem weryfikacyjnym wysłanym do użytkownika. Na poniższej ilustracji przedstawiono stronę samodzielnej rejestracji z dwoma kontrolkami wyświetlania, które weryfikują podstawowy i pomocniczy adres e-mail.

Screenshot showing email verification display control

Kontrolki TOTP

Kontrolki wyświetlania TOTP to zestaw kontrolek wyświetlania, które zapewniają uwierzytelnianie wieloskładnikowe TOTP w aplikacji Microsoft Authenticator. Na poniższej ilustracji przedstawiono stronę rejestracji TOTP z trzema kontrolkami wyświetlania.

Screenshot showing TOTP display controls

QrCodeControl

Element DisplayControl zawiera następujące elementy:

Element	Wystąpień	opis
`InputClaims`	0:1	Dane InputClaims są używane do wstępnego wypełniania wartości oświadczeń, które mają być zbierane od użytkownika. Aby uzyskać więcej informacji, zobacz InputClaims , element.
`DisplayClaims`	0:1	Funkcja DisplayClaims służy do reprezentowania oświadczeń, które mają być zbierane od użytkownika. Aby uzyskać więcej informacji, zobacz DisplayClaim , element.
`OutputClaims`	0:1	Dane OutputClaims są używane do reprezentowania oświadczeń, które mają zostać tymczasowo zapisane dla tego elementu DisplayControl. Aby uzyskać więcej informacji, zobacz OutputClaims , element.
`Actions`	0:1	Akcje służą do wyświetlania listy profilów technicznych weryfikacji w celu wywołania akcji użytkownika w frontonie.

Oświadczenia wejściowe

W kontrolce wyświetlania można użyć elementów InputClaims , aby wstępnie wypełniać wartość oświadczeń do zbierania od użytkownika na stronie. Wszelkie dane InputClaimsTransformations można zdefiniować w profilu technicznym asercji, który odwołuje się do tej kontrolki wyświetlania.

Poniższy przykład wstępnie wypełnia adres e-mail, który ma zostać zweryfikowany przy użyciu już istniejącego adresu.

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

Wyświetlanie oświadczeń

Każdy typ kontrolki wyświetlania wymaga wykonania innego zestawu oświadczeń wyświetlania, oświadczeń wyjściowych i akcji .

Podobnie jak w przypadku oświadczeń wyświetlania zdefiniowanych w własnym profilu technicznym, oświadczenia wyświetlane reprezentują oświadczenia, które mają być zbierane od użytkownika w kontrolce wyświetlania. Przywoływany element ClaimType musi określić element UserInputType dla typu danych wejściowych użytkownika obsługiwanych przez usługę Azure AD B2C, na przykład TextBox lub DropdownSingleSelect. Jeśli wartość oświadczenia wyświetlania jest wymagana przez akcję, ustaw wymagany atrybut, aby true wymusić użytkownikowi podanie wartości dla tego konkretnego oświadczenia wyświetlania.

Niektóre oświadczenia wyświetlania są wymagane w przypadku niektórych typów kontrolek wyświetlania. Na przykład kod weryfikacji jest wymagany dla kontrolki wyświetlania typu VerificationControl. Użyj atrybutu ControlClaimType , aby określić, który element DisplayClaim jest wyznaczony dla tego wymaganego oświadczenia. Na przykład:

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

Oświadczenia wyjściowe

Oświadczenia wyjściowe kontrolki wyświetlania nie są wysyłane do następnego kroku aranżacji. Są one zapisywane tymczasowo tylko dla bieżącej sesji kontrolki wyświetlania. Te tymczasowe oświadczenia można udostępniać między różnymi akcjami tej samej kontrolki wyświetlania.

Aby utworzyć bąbelek oświadczeń wyjściowych do następnego kroku aranżacji, użyj elementu OutputClaims rzeczywistego profilu technicznego asertywnego, który odwołuje się do tej kontrolki wyświetlania.

Wyświetlanie akcji kontrolki

Akcje kontrolki wyświetlania to procedury, które występują w zapleczu usługi Azure AD B2C, gdy użytkownik wykonuje określoną akcję po stronie klienta (przeglądarka). Na przykład walidacje, które mają być wykonywane, gdy użytkownik wybierze przycisk na stronie.

Akcja definiuje listę profilów technicznych weryfikacji. Są one używane do weryfikowania niektórych lub wszystkich oświadczeń wyświetlania kontrolki wyświetlania. Profil techniczny weryfikacji weryfikuje dane wejściowe użytkownika i może zwrócić użytkownikowi błąd. Możesz użyć polecenia ContinueOnError, ContinueOnSuccess i Warunków wstępnych w akcji kontrolki wyświetlania podobnej do sposobu ich używania w profilach technicznych weryfikacji w profilu technicznym z potwierdzeniem własnym.

Akcje

Element Actions zawiera następujący element:

Element	Wystąpień	opis
`Action`	1:n	Lista akcji do wykonania.

Akcja

Element Action zawiera następujący atrybut:

Atrybut	Wymagania	opis
`Id`	Tak	Typ operacji. Możliwe wartości: `SendCode` lub `VerifyCode`. Wartość `SendCode` wysyła kod do użytkownika. Ta akcja może zawierać dwa profile techniczne weryfikacji: jeden do wygenerowania kodu i jeden do wysłania. Wartość `VerifyCode` weryfikuje kod wpisany przez użytkownika w polu tekstowym wejściowym.

Element Action zawiera następujący element:

Element	Wystąpień	opis
`ValidationClaimsExchange`	1:1	Identyfikatory profilów technicznych, które są używane do weryfikowania niektórych lub wszystkich oświadczeń wyświetlania odwoływania się do profilu technicznego. Wszystkie oświadczenia wejściowe, do których odwołuje się profil techniczny, muszą być wyświetlane w oświadczeniach wyświetlania odnoszącego się do profilu technicznego.

ValidationClaimsExchange

Element ValidationClaimsExchange zawiera następujący element:

Element	Wystąpień	opis
`ValidationClaimsExchangeTechnicalProfile`	1:n	Profil techniczny, który ma być używany do weryfikowania niektórych lub wszystkich oświadczeń wyświetlania odwoływania się do profilu technicznego.

Element ValidationClaimsExchangeTechnicalProfile zawiera następujący atrybut:

Atrybut	Wymagania	opis
`TechnicalProfileReferenceId`	Tak	Identyfikator profilu technicznego już zdefiniowany w zasadach lub zasadach nadrzędnych.

Element ValidationClaimsExchangeTechnicalProfile zawiera następujący element:

Element	Wystąpień	opis
`Preconditions`	0:1	Lista warunków wstępnych, które muszą zostać spełnione, aby profil techniczny weryfikacji został wykonany.

Element Warunek wstępny zawiera następujące atrybuty:

Atrybut	Wymagania	opis
`Type`	Tak	Typ sprawdzania lub zapytania do wykonania dla warunku wstępnego. Możliwe wartości: `ClaimsExist` lub `ClaimEquals`. `ClaimsExist` określa, że akcje powinny być wykonywane, jeśli określone oświadczenia istnieją w bieżącym zestawie oświadczeń użytkownika. `ClaimEquals` określa, że akcje powinny być wykonywane, jeśli określone oświadczenie istnieje, a jego wartość jest równa określonej wartości.
`ExecuteActionsIf`	Tak	Wskazuje, czy akcje w warunku wstępnym powinny być wykonywane, jeśli test ma wartość true lub false.

Element Warunek wstępny zawiera następujące elementy:

Element	Wystąpień	opis
`Value`	1:n	Dane używane przez kontrolę. Jeśli typ tego sprawdzania to `ClaimsExist`, to pole określa wartość ClaimTypeReferenceId do utworzenia zapytania. Jeśli typ sprawdzania to `ClaimEquals`, to pole określa wartość ClaimTypeReferenceId do utworzenia zapytania. Określ wartość do zaewidencjonowania w innym elemecie wartości.
`Action`	1:1	Działanie, które należy podjąć, jeśli sprawdzenie warunków wstępnych w ramach kroku aranżacji jest prawdziwe. Wartość akcja jest ustawiona na `SkipThisValidationTechnicalProfile`, która określa, że skojarzony profil techniczny weryfikacji nie powinien być wykonywany.

Poniższy przykład wysyła i weryfikuje adres e-mail przy użyciu profilu technicznego samoobsługowego resetowania hasła identyfikatora firmy Microsoft.

<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>

Poniższy przykład wysyła kod w wiadomości e-mail lub SMS na podstawie wyboru oświadczenia mfaType z warunkiem wstępnym.

<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>

Odwoływanie się do kontrolek wyświetlania

Kontrolki wyświetlania są przywoływane w oświadczeniach wyświetlania własnego profilu technicznego.

Na przykład:

<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" />

Następne kroki

Przykłady użycia kontrolki wyświetlania można znaleźć w temacie:

Udostępnij za pośrednictwem