ContentDefinitions

Artigo
01/11/2024

Observação

No Azure Active Directory B2C, as políticas personalizadas são projetadas principalmente para tratar de cenários complexos. Para a maioria dos cenários, recomendamos que você use fluxos de usuários predefinidos. Se você ainda não fez isso, saiba mais sobre o pacote de início de política personalizado em Introdução às políticas personalizadas no Active Directory B2C.

Você pode personalizar a aparência de qualquer perfil técnico autodeclarado. O Azure AD B2C (Azure Active Directory B2C) executa o código no navegador do cliente e usa uma abordagem moderna chamada CORS (Compartilhamento de Recursos entre Origens).

Para personalizar a interface do usuário, você pode especificar uma URL no elemento ContentDefinition com conteúdo personalizado em HTML. No perfil técnico autodeclarado ou OrchestrationStep, aponte para esse identificador de definição de conteúdo. A definição de conteúdo pode conter um elemento LocalizedResourcesReferences que especifica uma lista de recursos localizados a serem carregados. O Azure AD B2C mescla os elementos da interface do usuário com o conteúdo HTML carregado da URL e exibe a página ao usuário.

O elemento ContentDefinitions contém as URLs para modelos de HTML5 que podem ser usados em um percurso do usuário. O URI da página HTML5 é usado para uma etapa especificada da interface do usuário. Por exemplo, a redefinição de senha de entrada ou de inscrição ou páginas de erro. Você pode modificar a aparência substituindo o LoadUri pelo arquivo HTML5. Você pode criar definições de novo conteúdo de acordo com suas necessidades. Esse elemento pode conter uma referência de recursos localizados, como o identificador de localização especificado no elemento localização.

O exemplo a seguir mostra o identificador de definição de conteúdo e a definição de recursos localizados:

<ContentDefinition Id="api.localaccountsignup">
  <LoadUri>~/tenant/default/selfAsserted.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:selfasserted:1.1.0</DataUri>
  <Metadata>
    <Item Key="DisplayName">Local account sign up page</Item>
  </Metadata>
  <LocalizedResourcesReferences MergeBehavior="Prepend">
    <LocalizedResourcesReference Language="en" LocalizedResourcesReferenceId="api.localaccountsignup.en" />
    <LocalizedResourcesReference Language="es" LocalizedResourcesReferenceId="api.localaccountsignup.es" />
    ...

Os metadados do perfil técnico autodeclarado LocalAccountSignUpWithLogonEmail contêm o identificador de definição de conteúdo ContentDefinitionReferenceId definido como api.localaccountsignup

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ContentDefinitionReferenceId">api.localaccountsignup</Item>
    ...
  </Metadata>
  ...

ContentDefinition

O elemento ContentDefinition contém o seguinte atributo:

Atributo	Obrigatório	Descrição
ID	Sim	Um identificador para uma definição de conteúdo. O valor é especificado na seção ID de definição de conteúdo mais adiante nesta página.

O elemento ContentDefinition contém os seguintes elementos:

Elemento	Ocorrências	Descrição
LoadUri	1:1	Uma cadeia de caracteres que contém a URL da página HTML5 para a definição de conteúdo.
RecoveryUri	1:1	Uma cadeia de caracteres que contém a URL da página HTML para exibir um erro relacionado à definição de conteúdo. Não usado no momento; o valor deve ser `~/common/default_page_error.html`.
DataUri	1:1	Uma cadeia de caracteres que contém a URL relativa de um arquivo HTML que fornece a experiência do usuário a ser invocada para a etapa.
Metadados	0:1	Uma coleção de pares chave/valor que contém os metadados utilizados pela definição de conteúdo.
LocalizedResourcesReferences	0:1	Uma coleção de referências de recursos localizados. Use esse elemento para personalizar a localização de um atributo de declarações e a interface do usuário.

LoadUri

O elemento LoadUri é usado para especificar a URL da página HTML5 para a definição de conteúdo. Os pacotes de inicialização de política personalizada do Azure AD B2C vêm com definições de conteúdo que usam as páginas HTML do Azure AD B2C. O LoadUri começa com ~, que é um caminho relativo para seu locatário do Azure AD B2C.

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>~/tenant/templates/AzureBlue/unified.cshtml</LoadUri>
  ...
</ContentDefinition>

Você pode personalizar a interface do usuário com modelos HTML. Ao usar modelos HTML, forneça uma URL absoluta. O exemplo a seguir ilustra uma definição de conteúdo com modelo HTML:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://your-storage-account.blob.core.windows.net/your-container/customize-ui.html</LoadUri>
  ...
</ContentDefinition>

DataUri

O elemento DataUri é usado para especificar o identificador de página. O Azure AD B2C usa o identificador de página para carregar e iniciar a elementos de interface do usuário e o JavaScript do lado do cliente. O formato do valor é urn:com:microsoft:aad:b2c:elements:page-name:version. A tabela a seguir lista os identificadores de página que você pode usar.

Identificador de página	Descrição
`globalexception`	Exibe uma página de erro quando uma exceção ou um erro é encontrado.
`providerselection`, `idpselection`	Lista os provedores de identidade que os usuários podem escolher durante a entrada.
`unifiedssp`	Exibe um formulário de entrada para entrar com uma conta local baseada em endereço de email ou nome de usuário. Esse valor também oferece as funcionalidades "Mantenha-me conectado" e "Esqueceu sua senha?" link.
`unifiedssd`	Exibe um formulário de entrada para entrar com uma conta local baseada em endereço de email ou nome de usuário. Esse identificador de página foi preterido. Em vez disso, use o identificador de página `unifiedssp`.
`multifactor`	Verifica os números de telefone usando o texto ou voz durante a inscrição ou entrada.
`selfasserted`	Exibe um formulário para coletar dados de um usuário. Por exemplo, permite aos usuários criar ou atualizar o próprio perfil.

Selecionar um layout de página

Você pode habilitar o código do lado do cliente JavaScript inserindo contract entre elements e o tipo de página. Por exemplo, urn:com:microsoft:aad:b2c:elements:contract:page-name:version.

A parte da versão do DataUri especifica o pacote de conteúdo que contém HTML, CSS e JavaScript para os elementos da interface do usuário na sua política. Caso você pretenda habilitar o código JavaScript do lado do cliente, os elementos dos quais você baseia seu JavaScript devem ser imutáveis. Se não forem imutáveis, as alterações poderão causar um comportamento inesperado nas páginas do usuário. Para evitar esses problemas, aplique o uso de um layout de página e especifique uma versão de layout de página. Fazer isso garante que todas as definições de conteúdo nas quais você baseou seu JavaScript sejam imutáveis. Mesmo que você não pretenda habilitar o JavaScript, ainda precisará especificar a versão de layout da página para suas páginas.

O seguinte exemplo mostra DataUri de selfasserted versão 1.2.0:

<!-- 
<BuildingBlocks> 
  <ContentDefinitions>-->
    <ContentDefinition Id="api.localaccountpasswordreset">
      <LoadUri>~/tenant/templates/AzureBlue/selfAsserted.cshtml</LoadUri>
      <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:1.2.0</DataUri>
      <Metadata>
        <Item Key="DisplayName">Local account change password page</Item>
      </Metadata>
    </ContentDefinition>
  <!-- 
  </ContentDefinitions> 
</BuildingBlocks> -->

Como fazer a migração para o layout da página

Para migrar do antigo valor de DataUri (sem contrato de página) para a versão de layout da página, adicione a palavra contract seguida de uma versão da página. Use a tabela a seguir para migrar do antigo valor de DataUri para a versão de layout da página.

Valor antigo de DataUri	Novo valor de DataUri
`urn:com:microsoft:aad:b2c:elements:globalexception:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1`
`urn:com:microsoft:aad:b2c:elements:globalexception:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1`
`urn:com:microsoft:aad:b2c:elements:idpselection:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1`
`urn:com:microsoft:aad:b2c:elements:selfasserted:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.7`
`urn:com:microsoft:aad:b2c:elements:selfasserted:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.7`
`urn:com:microsoft:aad:b2c:elements:unifiedssd:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:unifiedssd:1.2.1`
`urn:com:microsoft:aad:b2c:elements:unifiedssp:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.5`
`urn:com:microsoft:aad:b2c:elements:unifiedssp:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.5`
`urn:com:microsoft:aad:b2c:elements:multifactor:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5`
`urn:com:microsoft:aad:b2c:elements:multifactor:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5`

O seguinte exemplo mostra os identificadores de definição de conteúdo e o DataUri correspondente com a versão de página mais recente:

<!-- 
<BuildingBlocks> -->
  <ContentDefinitions>
    <ContentDefinition Id="api.error">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.idpselections">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.idpselections.signup">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.signuporsignin">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.7</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.selfasserted">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.selfasserted.profileupdate">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.localaccountsignup">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.localaccountpasswordreset">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.phonefactor">
      <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5</DataUri>
    </ContentDefinition>
  </ContentDefinitions>
<!-- 
</BuildingBlocks> -->

Metadados

Um elemento Metadata contém os seguintes elementos:

Elemento	Ocorrências	Descrição
Item	0:n	Os metadados que se relacionam à definição do conteúdo.

O elemento Item do elemento Metadata contém os seguintes atributos:

Atributo	Obrigatório	Descrição
Chave	Sim	A chave de metadados.

Chaves de metadados

A definição de conteúdo dá suporte aos seguintes itens de metadados:

Chave	Obrigatório	Descrição
DisplayName	Não	Uma string que contém o nome da definição do conteúdo.

LocalizedResourcesReferences

O elemento LocalizedResourcesReferences contém os seguintes elementos:

Elemento	Ocorrências	Descrição
LocalizedResourcesReference	1:n	Uma lista de referências de recurso localizado para a definição de conteúdo.

O elemento LocalizedResourcesReference contém os seguintes atributos:

Atributo	Obrigatório	Descrição
Idioma	Sim	Uma cadeia de caracteres que contém uma linguagem com suporte para a política de acordo com a RFC 5646 – Marcas para identificar idiomas.
LocalizedResourcesReferenceId	Sim	O identificador do elemento LocalizedResources.

O exemplo a seguir mostra uma definição de conteúdo de entrada ou inscrição com uma referência à localização para inglês, francês e espanhol:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>~/tenant/default/unified.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:unifiedssp:1.0.0</DataUri>
  <Metadata>
    <Item Key="DisplayName">Signin and Signup</Item>
  </Metadata>
  <LocalizedResourcesReferences MergeBehavior="Prepend">
    <LocalizedResourcesReference Language="en" LocalizedResourcesReferenceId="api.signuporsignin.en" />
    <LocalizedResourcesReference Language="fr" LocalizedResourcesReferenceId="api.signuporsignin.rf" />
    <LocalizedResourcesReference Language="es" LocalizedResourcesReferenceId="api.signuporsignin.es" />
</LocalizedResourcesReferences>
</ContentDefinition>

Para saber como adicionar suporte de localização a definições de conteúdo, veja Localização.

IDs da definição de conteúdo

O atributo de ID do elemento ContentDefinition especifica o tipo de página relacionada à definição de conteúdo. O elemento define o contexto que um modelo personalizado HTML5/CSS aplicará. A tabela a seguir descreve o conjunto de IDs de definição de conteúdo reconhecidas pelo Identity Experience Framework e os tipos de página relacionados a elas. Você pode criar suas próprias definições de conteúdo com uma ID arbitrária.

ID	Modelo padrão	Descrição
api.error	exception.cshtml	Página de erro – exibe uma página de erro quando uma exceção ou um erro é encontrado.
api.idpselections	idpSelector.cshtml	Página de seleção do provedor de identidade – lista provedores de identidade entre os quais os usuários podem escolher durante a entrada. Normalmente, as opções são provedores de identidade corporativa, provedores de identidade social, como Facebook e Google+ ou contas locais.
api.idpselections.signup	idpSelector.cshtml	Seleção de provedor de identidade para inscrição – lista provedores de identidade entre os quais os usuários podem escolher durante a inscrição. Normalmente, as opções são provedores de identidade corporativa, provedores de identidade social, como Facebook e Google+ ou contas locais.
api.localaccountpasswordreset	selfasserted.cshtml	Página Esqueci a senha – exibe um formulário que os usuários precisam preencher para iniciar uma redefinição de senha.
api.localaccountsignin	selfasserted.cshtml	Página de entrada em conta local – exibe um formulário para entrar com uma conta local com base em um endereço de email ou nome de usuário. O formulário pode conter uma caixa de entrada de texto e caixa de entrada de senha.
api.localaccountsignup	selfasserted.cshtml	Página de inscrição de conta local – exibe um formulário para se inscrever para uma conta local com base em um endereço de email ou nome de usuário. O formulário pode conter diferentes controles de entrada, por exemplo: caixa de entrada de texto, caixa de entrada de senha, botão de opção, caixas de lista suspensa de seleção única e caixas de seleção múltipla.
api.phonefactor	multifactor-1.0.0.cshtml	Página de autenticação multifator – verifica os números de telefone usando texto ou voz durante a inscrição ou a entrada.
api.selfasserted	selfasserted.cshtml	Página de inscrição com conta social – exibe um formulário que os usuários devem preencher ao se inscreverem usando uma conta existente de um provedor de identidade social. Esta página é semelhante à página de inscrição de conta social anterior, exceto pelos campos de entrada de senha.
api.selfasserted.profileupdate	updateprofile.cshtml	Página de atualização de perfil – exibe um formulário que os usuários podem acessar para atualizar o perfil. Esta página é semelhante à página de inscrição de conta social, exceto pelos campos de entrada de senha.
api.signuporsignin	unified.cshtml	Página de inscrição ou entrada unificada – trata do processo de inscrição e entrada do usuário. Os usuários podem usar provedores de identidade corporativa, provedores de identidade social, como Facebook e Google+ ou contas locais.

Próximas etapas

Para obter um exemplo de personalização da interface do usuário usando definições de conteúdo, confira:

Personalizar a interface do usuário do aplicativo usando uma política personalizada

Compartilhar via