Informacje o funkcjach rozpoznawania oświadczeń w zasadach niestandardowych usługi Azure Active Directory B2C

  • Artykuł

Zasady niestandardowe rozpoznawania oświadczeń w usłudze Azure Active Directory B2C (Azure AD B2C) udostępniają informacje kontekstowe dotyczące żądania autoryzacji, takie jak nazwa zasad, identyfikator korelacji żądania, język interfejsu użytkownika i inne.

Aby użyć rozpoznawania oświadczeń w oświadczeniu wejściowym lub wyjściowym, należy zdefiniować ciąg ClaimType w elemecie ClaimsSchema , a następnie ustawić wartość DefaultValue na rozpoznawanie oświadczeń w elemecie oświadczeń wejściowych lub wyjściowych. Usługa Azure AD B2C odczytuje wartość narzędzia rozpoznawania oświadczeń i używa wartości w profilu technicznym.

W poniższym przykładzie typ oświadczenia o nazwie correlationId jest definiowany z typem DataType klasy string.

<ClaimType Id="correlationId">
  <DisplayName>correlationId</DisplayName>
  <DataType>string</DataType>
  <UserHelpText>Request correlation Id</UserHelpText>
</ClaimType>

W profilu technicznym zamapuj program rozpoznawania oświadczeń na typ oświadczenia. Usługa Azure AD B2C wypełnia wartość rozpoznawania {Context:CorrelationId} oświadczeń w oświadczeniu correlationId i wysyła oświadczenie do profilu technicznego.

<InputClaim ClaimTypeReferenceId="correlationId" DefaultValue="{Context:CorrelationId}" />

Kultura

W poniższej tabeli wymieniono narzędzia rozpoznawania oświadczeń zawierające informacje o języku używanym w żądaniu autoryzacji:

Oświadczenie opis Przykład
{Culture:LanguageName} Dwuliterowy kod ISO języka. en
{Culture:LCID} Identyfikator LCID kodu języka. 1033
{Culture:RegionName} Dwuliterowy kod ISO dla regionu. — USA
{Culture:RFC5646} Kod języka RFC5646. en-US

Zapoznaj się z pokazem live rozpoznawania oświadczeń kultury.

Zasady

W poniższej tabeli wymieniono narzędzia rozpoznawania oświadczeń z informacjami o zasadach używanych w żądaniu autoryzacji:

Oświadczenie opis Przykład
{Policy:PolicyId} Nazwa zasad jednostki uzależnionej. B2C_1A_signup_signin
{Policy:RelyingPartyTenantId} Identyfikator dzierżawy zasad jednostki uzależnionej. your-tenant.onmicrosoft.com
{Policy:TenantObjectId} Identyfikator obiektu dzierżawy zasad jednostki uzależnionej. 00000000-0000-0000-0000-000000000000
{Policy:TrustFrameworkTenantId} Identyfikator dzierżawy platformy zaufania. your-tenant.onmicrosoft.com

Zapoznaj się z pokazem na żywo funkcji rozpoznawania oświadczeń zasad.

Kontekst

W poniższej tabeli wymieniono kontekstowe funkcje rozpoznawania oświadczeń żądania autoryzacji:

Oświadczenie opis Przykład
{Context:BuildNumber} Wersja programu Identity Experience Framework (numer kompilacji). 1.0.507.0
{Context:CorrelationId} Identyfikator korelacji. 00000000-0000-0000-0000-000000000000
{Context:DateTimeInUtc} Data i godzina w formacie UTC. 10/10/2021 12:00:00
{Context:DeploymentMode} Tryb wdrażania zasad. Produkcyjne
{Context:HostName} Nazwa hosta bieżącego żądania. contoso.b2clogin.com
{Context:IPAddress} Adres IP użytkownika. 11.111.111.11
{Context:KMSI} Wskazuje, czy zaznaczono pole wyboru Nie wylogowuj mnie. prawda

Zapoznaj się z pokazem live programu rozpoznawania oświadczeń kontekstu.

Roszczenia

W tej sekcji opisano sposób uzyskiwania wartości oświadczenia jako rozpoznawania oświadczeń.

Oświadczenie opis Przykład
{Claim:claim type} Identyfikator typu oświadczenia już zdefiniowany w sekcji ClaimsSchema w pliku zasad lub pliku zasad nadrzędnych. Na przykład: {Claim:displayName}, lub {Claim:objectId}. Wartość typu oświadczenia.

OpenID Connect

W poniższej tabeli wymieniono narzędzia rozpoznawania oświadczeń zawierające informacje o żądaniu autoryzacji openID Połączenie:

Oświadczenie opis Przykład
{OIDC:AuthenticationContextReferences} acr_values Parametr ciągu zapytania. Nie dotyczy
{OIDC:ClientId} client_id Parametr ciągu zapytania. 00000000-0000-0000-0000-000000000000
{OIDC:DomainHint} domain_hint Parametr ciągu zapytania. facebook.com
{OIDC:LoginHint} login_hint Parametr ciągu zapytania. someone@contoso.com
{OIDC:MaxAge} max_age. Nie dotyczy
{OIDC:Nonce} Nonce Parametr ciągu zapytania. defaultNonce
{OIDC:Password} Poświadczenia hasła właściciela zasobu przepływają hasło użytkownika. hasło1
{OIDC:Prompt} prompt Parametr ciągu zapytania. Nazwa logowania
{OIDC:RedirectUri} redirect_uri Parametr ciągu zapytania. https://jwt.ms
{OIDC:Zasób} resource Parametr ciągu zapytania. Nie dotyczy
{OIDC:Scope} scope Parametr ciągu zapytania. Openid
{OIDC:Username} Poświadczenia hasła właściciela zasobu przepływają nazwę użytkownika. emily@contoso.com
{OIDC:IdToken} id token Parametr ciągu zapytania. Nie dotyczy

Zapoznaj się z pokazem na żywo funkcji rozpoznawania oświadczeń openID Połączenie.

Parametry klucz-wartość protokołu OAuth2

Dowolna nazwa parametru dołączona w ramach żądania OIDC lub OAuth2 może zostać zamapowana na oświadczenie w podróży użytkownika. Na przykład żądanie z aplikacji może zawierać parametr ciągu zapytania o nazwie app_session, loyalty_numberlub dowolnym niestandardowym ciągu zapytania.

Oświadczenie opis Przykład
{OAUTH-KV:campaignId} Parametr ciągu zapytania. Hawaje
{OAUTH-KV:app_session} Parametr ciągu zapytania. A3C5R
{OAUTH-KV:loyalty_number} Parametr ciągu zapytania. 1234
{OAUTH-KV:dowolny ciąg zapytania niestandardowego} Parametr ciągu zapytania. Nie dotyczy

Parametry klucz-wartość protokołu SAML

W żądaniu uwierzytelniania SAML wszystkie nazwy parametrów zawarte w żądaniu, ale nie są specyficzne dla protokołu (takiego jak SAMLRequest) mogą być mapowane na oświadczenie w podróży użytkownika. Na przykład żądanie może zawierać niestandardowy parametr, taki jak username. Dotyczy to zarówno żądań SAML inicjowanych przez dostawcę usług, jak i inicjowanych przez dostawcę tożsamości.

Oświadczenie opis Przykład
{SAML-KV:username} Ciąg zapytania lub parametr treści POST. username@domain.com
{SAML-KV:loyalty_number} Ciąg zapytania lub parametr treści POST. 1234
{SAML-KV:dowolny niestandardowy ciąg zapytania} Ciąg zapytania lub parametr treści POST. Nie dotyczy

SAML

W poniższej tabeli wymieniono narzędzia rozpoznawania oświadczeń z informacjami o żądaniu autoryzacji SAML:

Oświadczenie opis Przykład
{SAML:AuthnContextClassReferences} Wartość AuthnContextClassRef elementu z żądania SAML. urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
{SAML:NameIdPolicyFormat} Atrybut Format z NameIDPolicy elementu żądania SAML. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
{SAML:Issuer} Wartość elementu SAML Issuer żądania SAML. https://contoso.com
{SAML:AllowCreate} Wartość AllowCreate atrybutu NameIDPolicy z elementu żądania SAML. Prawda
{SAML:ForceAuthn} Wartość ForceAuthN atrybutu AuthnRequest z elementu żądania SAML. Prawda
{SAML:ProviderName} Wartość ProviderName atrybutu AuthnRequest z elementu żądania SAML. Contoso.com
{SAML:RelayState} RelayState Parametr ciągu zapytania.
{SAML:Subject} Element Subject z nameid żądania SAML AuthN.
{SAML:Binding} Wartość ProtocolBinding atrybutu AuthnRequest z elementu żądania SAML. urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

Zapoznaj się z pokazem live programu rozpoznawania oświadczeń SAML.

Dostawca tożsamości OAuth2

W poniższej tabeli wymieniono usługi rozpoznawania oświadczeń dostawcy tożsamości OAuth2:

Oświadczenie opis Przykład
{oauth2:access_token} Token dostępu dostawcy tożsamości OAuth2. Atrybut access_token . eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...
{oauth2:token_type} Typ tokenu dostępu. Atrybut token_type . Okaziciela
{oauth2:expires_in} Czas ważności tokenu dostępu w sekundach. Atrybut expires_in . Typ danych wyjściowych oświadczenia musi mieć wartość int lub long. 960000
{oauth2:refresh_token} Token odświeżania dostawcy tożsamości OAuth2. Atrybut refresh_token . eyJraWQiOiJacW9pQlp2TW5pYVc2MUY...

Aby użyć rozpoznawania oświadczeń dostawcy tożsamości OAuth2, ustaw atrybut oświadczenia wyjściowego na rozpoznawanie oświadczeń PartnerClaimType . W poniższym przykładzie pokazano, jak uzyskać oświadczenia zewnętrznego dostawcy tożsamości:

<ClaimsProvider>
  <DisplayName>Contoso</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="Contoso-OAUTH">
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessToken" PartnerClaimType="{oauth2:access_token}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessTokenType" PartnerClaimType="{oauth2:token_type}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessTokenExpiresIn" PartnerClaimType="{oauth2:expires_in}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderRefreshToken" PartnerClaimType="{oauth2:refresh_token}" />
      </OutputClaims>
      ...
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Korzystanie z funkcji rozpoznawania oświadczeń

Narzędzia rozpoznawania oświadczeń można używać z następującymi elementami:

Produkt Element Ustawienia
Profil techniczny aplikacji Szczegółowe informacje InputClaim
Profil techniczny firmy Microsoft Entra InputClaim, OutputClaim 1, 2
Profil techniczny OAuth2 InputClaim, OutputClaim 1, 2
Profil techniczny openID Połączenie InputClaim, OutputClaim 1, 2
Profil techniczny przekształcania oświadczeń InputClaim, OutputClaim 1, 2
Profil techniczny dostawcy RESTful InputClaim 1, 2
Profil techniczny dostawcy tożsamości SAML OutputClaim 1, 2
Własny profil techniczny InputClaim, OutputClaim 1, 2
ContentDefinition LoadUri
ContentDefinitionParameters Parameter
Profil techniczny jednostki uzależnionej OutputClaim 2

Ustawienia:

  1. Metadane IncludeClaimResolvingInClaimsHandling muszą być ustawione na true.
  2. Atrybut AlwaysUseDefaultValue oświadczeń wejściowych lub wyjściowych musi być ustawiony na true.

Przykłady rozpoznawania oświadczeń

Profil techniczny RESTful

W profilu technicznym RESTful możesz wysłać język użytkownika, nazwę zasad, zakres i identyfikator klienta. Na podstawie oświadczeń interfejs API REST może uruchamiać niestandardową logikę biznesową i w razie potrzeby zgłosić zlokalizowany komunikat o błędzie.

W poniższym przykładzie przedstawiono profil techniczny RESTful z tym scenariuszem:

<TechnicalProfile Id="REST">
  <DisplayName>Validate user input data and return loyaltyNumber claim</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="policyName" DefaultValue="{Policy:PolicyId}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="scope" DefaultValue="{OIDC:Scope}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="clientId" DefaultValue="{OIDC:ClientId}" AlwaysUseDefaultValue="true" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Bezpośrednie logowanie

Korzystając z funkcji rozpoznawania oświadczeń, możesz wstępnie wypełniać nazwę logowania lub bezpośrednio zalogować się do określonego dostawcy tożsamości społecznościowych, takiego jak Facebook, LinkedIn lub konto Microsoft. Aby uzyskać więcej informacji, zobacz Konfigurowanie logowania bezpośredniego przy użyciu usługi Azure Active Directory B2C.

Dostosowywanie dynamicznego interfejsu użytkownika

Usługa Azure AD B2C umożliwia przekazywanie parametrów ciągu zapytania do punktów końcowych definicji zawartości HTML w celu dynamicznego renderowania zawartości strony. Na przykład ta funkcja umożliwia modyfikowanie obrazu tła na stronie rejestracji lub logowania usługi Azure AD B2C na podstawie niestandardowego parametru przekazywanego z aplikacji internetowej lub mobilnej. Aby uzyskać więcej informacji, zobacz Dynamiczne konfigurowanie interfejsu użytkownika przy użyciu zasad niestandardowych w usłudze Azure Active Directory B2C. Możesz również zlokalizować stronę HTML na podstawie parametru języka lub zmienić zawartość na podstawie identyfikatora klienta.

Poniższy przykład przekazuje parametr ciągu zapytania o nazwie campaignId z wartością Hawaii, kod en-USjęzyka i aplikacji reprezentującej identyfikator klienta:

<UserJourneyBehaviors>
  <ContentDefinitionParameters>
    <Parameter Name="campaignId">{OAUTH-KV:campaignId}</Parameter>
    <Parameter Name="language">{Culture:RFC5646}</Parameter>
    <Parameter Name="app">{OIDC:ClientId}</Parameter>
  </ContentDefinitionParameters>
</UserJourneyBehaviors>

W związku z tym usługa Azure AD B2C wysyła powyższe parametry do strony zawartości HTML:

/selfAsserted.aspx?campaignId=hawaii&language=en-US&app=0239a9cc-309c-4d41-87f1-31288feb2e82

Definicja zawartości

W obiekcie ContentDefinitionLoadUri można wysyłać narzędzia rozpoznawania oświadczeń w celu ściągnięcia zawartości z różnych miejsc na podstawie użytych parametrów.

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://contoso.blob.core.windows.net/{Culture:LanguageName}/myHTML/unified.html</LoadUri>
  ...
</ContentDefinition>

Profil techniczny aplikacji Szczegółowe informacje

Za pomocą aplikacja systemu Azure Szczegółowe informacje i funkcji rozpoznawania oświadczeń możesz uzyskać szczegółowe informacje na temat zachowania użytkownika. W profilu technicznym Szczegółowe informacje aplikacji wysyłasz oświadczenia wejściowe, które są utrwalane do aplikacja systemu Azure Szczegółowe informacje. Aby uzyskać więcej informacji, zobacz Track user behavior in Azure AD B2C journeys by using Application Szczegółowe informacje (Śledzenie zachowania użytkowników w usłudze Azure AD B2C przy użyciu Szczegółowe informacje aplikacji). Poniższy przykład wysyła identyfikator zasad, identyfikator korelacji, język i identyfikator klienta do aplikacja systemu Azure Szczegółowe informacje.

<TechnicalProfile Id="AzureInsights-Common">
  <DisplayName>Alternate Email</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.Insights.AzureApplicationInsightsProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="PolicyId" PartnerClaimType="{property:Policy}" DefaultValue="{Policy:PolicyId}" />
    <InputClaim ClaimTypeReferenceId="CorrelationId" PartnerClaimType="{property:CorrelationId}" DefaultValue="{Context:CorrelationId}" />
    <InputClaim ClaimTypeReferenceId="language" PartnerClaimType="{property:language}" DefaultValue="{Culture:RFC5646}" />
    <InputClaim ClaimTypeReferenceId="AppId" PartnerClaimType="{property:App}" DefaultValue="{OIDC:ClientId}" />
  </InputClaims>
</TechnicalProfile>

Zasady jednostki uzależnionej

W profilu technicznym zasad jednostki uzależnionej możesz wysłać identyfikator dzierżawy lub identyfikator korelacji do aplikacji jednostki uzależnionej w ramach zestawu JWT.

<RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <TechnicalProfile Id="PolicyProfile">
      <DisplayName>PolicyProfile</DisplayName>
      <Protocol Name="OpenIdConnect" />
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="displayName" />
        <OutputClaim ClaimTypeReferenceId="givenName" />
        <OutputClaim ClaimTypeReferenceId="surname" />
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
        <OutputClaim ClaimTypeReferenceId="identityProvider" />
        <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
        <OutputClaim ClaimTypeReferenceId="correlationId" AlwaysUseDefaultValue="true" DefaultValue="{Context:CorrelationId}" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>

Następne kroki

  • Znajdź więcej przykładów funkcji rozpoznawania oświadczeń w repozytorium GitHub społeczności usługi Azure AD B2C