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

Artigo
01/19/2024

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:

Declaração	Descrição	Exemplo
{Culture:LanguageName}	As duas letras do código ISO para o idioma.	en
{Culture:LCID}	O LCID do código de idioma.	1046
{Culture:RegionName}	As duas letras do código ISO para a região.	EUA
{Culture:RFC5646}	O código de idioma RFC5646.	en-US

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:

Declaração	Descrição	Exemplo
{Policy:PolicyId}	O nome da política de terceira parte confiável.	B2C_1A_signup_signin
{Policy:RelyingPartyTenantId}	A ID do locatário da política de terceira parte confiável.	your-tenant.onmicrosoft.com
{Policy:TenantObjectId}	A ID do objeto do locatário da política de terceira parte confiável.	00000000-0000-0000-0000-000000000000
{Policy:TrustFrameworkTenantId}	A ID do locatário e da estrutura de confiança.	your-tenant.onmicrosoft.com

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:

Declaração	Descrição	Exemplo
{Context:BuildNumber}	A versão do Identity Experience Framework (número de build).	1.0.507.0
{Context:CorrelationId}	ID de correlação.	00000000-0000-0000-0000-000000000000
{Context:DateTimeInUtc}	A data e hora em UTC.	10/10/2021 12:00:00
{Context:DeploymentMode}	O modo de implantação de política.	Produção
{Context:HostName}	O nome do host da solicitação atual.	contoso.b2clogin.com
{Context:IPAddress}	O endereço IP do usuário.	11.111.111.11
{Context:KMSI}	Indica se a caixa de seleção Manter-me conectado está marcada.	true

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.

Declaração	Descrição	Exemplo
{Claim:claim type}	Um identificador de um tipo de declaração já definido na seção ClaimsSchema no arquivo de política ou no arquivo de política pai. Por exemplo: `{Claim:displayName}` ou `{Claim:objectId}`.	Um tipo de declaração de valor.

OpenID Connect

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

Declaração	Descrição	Exemplo
{OIDC:AuthenticationContextReferences}	O parâmetro de cadeia de caracteres da consulta `acr_values`.	N/D
{OIDC:ClientId}	O parâmetro de cadeia de caracteres da consulta `client_id`.	00000000-0000-0000-0000-000000000000
{OIDC:DomainHint}	O parâmetro de cadeia de caracteres da consulta `domain_hint`.	facebook.com
{OIDC:LoginHint}	O parâmetro de cadeia de caracteres da consulta `login_hint`.	someone@contoso.com
{OIDC:MaxAge}	O `max_age`.	N/D
{OIDC:Nonce}	O parâmetro de cadeia de caracteres da consulta `Nonce`.	defaultNonce
{OIDC:Password}	A senha do usuário do fluxo de credenciais de senha do proprietário do recurso.	password1
{OIDC:Prompt}	O parâmetro de cadeia de caracteres da consulta `prompt`.	login
{OIDC:RedirectUri}	O parâmetro de cadeia de caracteres da consulta `redirect_uri`.	https://jwt.ms
{OIDC:Resource}	O parâmetro de cadeia de caracteres da consulta `resource`.	N/D
{OIDC:Scope}	O parâmetro de cadeia de caracteres da consulta `scope`.	openid
{OIDC:Username}	O nome do usuário do fluxo de credenciais de senha do proprietário do recurso.	emily@contoso.com
{OIDC:IdToken}	O parâmetro de cadeia de caracteres da consulta `id token`.	N/D

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.

Declaração	Descrição	Exemplo
{OAUTH-KV:campaignId}	Um parâmetro de cadeia de consulta.	Hawaii
{OAUTH-KV:app_session}	Um parâmetro de cadeia de consulta.	A3C5R
{OAUTH-KV:loyalty_number}	Um parâmetro de cadeia de consulta.	1234
{OAUTH-KV:any custom query string}	Um parâmetro de cadeia de consulta.	N/D

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.

Declaração	Descrição	Exemplo
{SAML-KV:nome de usuário}	Uma cadeia de caracteres de consulta ou um parâmetro de corpo POST.	username@domain.com
{SAML-KV:loyalty_number}	Uma cadeia de caracteres de consulta ou um parâmetro de corpo POST.	1234
{SAML-KV:qualquer cadeia de caracteres de consulta personalizada}	Uma cadeia de caracteres de consulta ou um parâmetro de corpo POST.	N/D

SAML

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

Declaração	Descrição	Exemplo
{SAML:AuthnContextClassReferences}	O valor do elemento `AuthnContextClassRef`, da solicitação SAML.	urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
{SAML:NameIdPolicyFormat}	O atributo `Format`, do elemento `NameIDPolicy` da solicitação SAML.	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
{SAML:Issuer}	O valor do elemento `Issuer` de SAML da solicitação SAML.	`https://contoso.com`
{SAML:AllowCreate}	O valor do atributo `AllowCreate`, do elemento `NameIDPolicy` da solicitação SAML.	True
{SAML:ForceAuthn}	O valor do atributo `ForceAuthN`, do elemento `AuthnRequest` da solicitação SAML.	True
{SAML:ProviderName}	O valor do atributo `ProviderName`, do elemento `AuthnRequest` da solicitação SAML.	Contoso.com
{SAML:RelayState}	O parâmetro de cadeia de caracteres da consulta `RelayState`.
{SAML:Subject}	O `Subject` do elemento NameID da solicitação do SAML AuthN.
{SAML:Binding}	O valor do atributo `ProtocolBinding`, do elemento `AuthnRequest` da solicitação SAML.	urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

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:

Declaração	Descrição	Exemplo
{oauth2:access_token}	O token de acesso do provedor de identidade OAuth2. O atributo `access_token`.	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...`
{oauth2:token_type}	O tipo do token de acesso. O atributo `token_type`.	Portador
{oauth2:expires_in}	O período de tempo durante o qual o token de acesso é válido, em segundos. O atributo `expires_in`. A declaração de saída DataType precisa ser `int` ou `long`.	960000
{oauth2:refresh_token}	O token de atualização do provedor de identidade OAuth2. O atributo `refresh_token`.	`eyJraWQiOiJacW9pQlp2TW5pYVc2MUY...`

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:

Item	Elemento	Configurações
Perfil técnico do Application Insights	`InputClaim`
Perfil técnico Microsoft Entra	`InputClaim`, `OutputClaim`	1, 2
Perfil técnico do OAuth2	`InputClaim`, `OutputClaim`	1, 2
Perfil técnico do OpenID Connect	`InputClaim`, `OutputClaim`	1, 2
Perfil técnico de transformação de declarações	`InputClaim`, `OutputClaim`	1, 2
Perfil técnico do provedor RESTful	`InputClaim`	1, 2
Perfil técnico do provedor de identidade SAML	`OutputClaim`	1, 2
Perfil técnico autodeclarado	`InputClaim`, `OutputClaim`	1, 2
ContentDefinition	`LoadUri`
ContentDefinitionParameters	`Parameter`
Perfil técnico de RelyingParty	`OutputClaim`	2

Configurações:

Os metadados IncludeClaimResolvingInClaimsHandling devem ser definidos como true.
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>

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