Sobre resolvedores de declaração em políticas personalizadas do Azure Active Directory B2C

Os resolvedores de declarações em políticas personalizadas do Azure Active Directory B2C (Azure AD B2C) fornecem informações de contexto sobre uma solicitação de autorização, como o nome da política, a ID da correlação da solicitação, o idioma da interface do usuário e muito mais.

Para usar um resolvedor de declaração em uma declaração de entrada ou saída, você define uma cadeia de caracteres ClaimType, no elemento ClaimsSchema e, em seguida, define DefaultValue como o resolvedor de declaração no elemento de declaração de entrada ou saída. O Azure AD B2C lê o valor do resolvedor de declaração e usa o valor no perfil técnico.

No exemplo a seguir, um tipo de declaração denominado correlationId é definido com um DataType de string.

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

No perfil técnico, mapeie o resolvedor de declaração para o tipo de declaração. O Azure AD B2C preenche o valor do resolvedor de declaração {Context:CorrelationId} para a declaração correlationId e envia a declaração para o perfil técnico.

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

Cultura

A tabela a seguir lista os resolvedores de declaração com informações sobre o idioma usado na solicitação de autorização:

Confira a Demonstração ao vivo dos resolvedores da declaração de cultura.

Política

A tabela a seguir lista os resolvedores de declaração com informações sobre a política usada na solicitação de autorização:

Confira a Demonstração ao vivo dos resolvedores da declaração de cultura.

Contexto

A tabela a seguir lista os resolvedores de declaração contextual da solicitação de autorização:

Confira a Demonstração ao vivo dos resolvedores da declaração de contexto.

Declarações

Esta seção descreve como obter um valor de declaração como um resolvedor de declaração.

OpenID Connect

A tabela a seguir lista os resolvedores de declaração com informações sobre a solicitação de autorização OpenID Connect:

Confira a Demonstração ao vivo dos resolvedores de declaração do OpenID Connect.

Parâmetros OAuth2 key-value

Qualquer nome de parâmetro incluído como parte de uma solicitação OIDC ou OAuth2 pode ser mapeado para uma declaração no percurso do usuário. Por exemplo, a solicitação do aplicativo pode incluir um parâmetro da cadeia de consulta com um nome de app_session, loyalty_number ou qualquer cadeia de consulta personalizada.

Parâmetros de chave-valor SAML

Em uma solicitação de autenticação SAML, qualquer nome de parâmetro incluído na solicitação, mas não específico do protocolo (como SAMLRequest) pode ser mapeado para uma declaração na jornada do usuário. Por exemplo, a solicitação pode incluir um parâmetro personalizado, como username. Isso se aplica a solicitações SAML iniciadas por SP e IDP.

SAML

A tabela a seguir lista os resolvedores de declaração com informações sobre a solicitação de autorização SAML:

Confira a Demonstração ao vivo dos resolvedores da declaração do SAML.

Provedor de identidade OAuth2

A tabela a seguir lista os resolvedores de declaração do provedor de identidade OAuth2:

Para usar os resolvedores de declaração do provedor de identidade OAuth2, defina o atributo PartnerClaimType da declaração de saída para o resolvedor de declaração. O seguinte exemplo demonstra como obter as declarações do provedor de identidade externo:

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

Usar resolvedores de declarações

Você pode usar resolvedores de declarações com os seguintes elementos:

Configurações:

1. Os metadados IncludeClaimResolvingInClaimsHandling devem ser definidos como true.
2. O atributo de declarações de entrada ou saída AlwaysUseDefaultValue deve ser definido como true.

Amostras de resolvedores de declarações

Perfil técnico RESTful

Em um perfil técnico RESTful, você talvez queira enviar o idioma do usuário, o nome da política, o escopo e a ID do cliente. Com base nas declarações, a API REST poderá executar lógica de negócios personalizada e, se necessário, gerar uma mensagem de erro localizada.

O exemplo a seguir mostra um perfil técnico do RESTful com esse cenário:

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

Entrada direta

Usando resolvedores de declaração, você pode preencher previamente o nome de entrada ou as credenciais diretas em um provedor de identidade social específico, como Facebook, LinkedIn ou uma conta Microsoft. Para obter mais informações, confira Configurar entrada direta usando o Azure Active Directory B2C.

Personalização de interface do usuário dinâmica

O Azure AD B2C permite que você passe parâmetros de cadeia de consulta para os pontos de extremidade de definição de conteúdo HTML para renderizar dinamicamente o conteúdo da página. Por exemplo, esse recurso permite alterar a imagem de tela de fundo na página de inscrição ou de entrada do Azure AD B2C, com base em um parâmetro personalizado passado do aplicativo Web ou móvel. Para obter mais informações, confira Configurar dinamicamente a interface do usuário usando políticas personalizadas no Azure Active Directory B2C. Você também pode localizar sua página HTML com base em um parâmetro de idioma, ou pode alterar o conteúdo com base na ID do cliente.

O exemplo a seguir passa na cadeia de consulta um parâmetro denominado campaignId com um valor de Hawaii, um código de idioma de en-US e aplicativo que representa a ID do cliente:

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

Como resultado, o Azure AD B2C envia os parâmetros acima para a página de conteúdo HTML:

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

Definição de conteúdo

Em um ContentDefinition LoadUri, você pode enviar resolvedores de declaração para efetuar pull de conteúdo de locais diferentes, com base nos parâmetros usados.

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

Perfil técnico do Application Insights

Com o Azure Application Insights e resolvedores de declaração, você pode obter insights sobre o comportamento do usuário. No perfil técnico do Application Insights, você envia declarações de entrada que persistem no Azure Application Insights. Para obter mais informações, confira Acompanhar o comportamento do usuário em jornadas do Azure AD B2C usando o Application Insights. O exemplo a seguir envia a ID de política, a ID de correlação, o idioma e a ID do cliente para o Azure Application Insights.

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

Política da terceira parte confiável

Em uma política de terceira parte confiável, talvez você queira enviar a ID de locatário ou a ID de correlação para o aplicativo de terceira parte confiável dentro do 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>

Próximas etapas

• Encontre mais amostras de transformação de declarações no repositório GitHub da comunidade do Azure AD B2C