ContentDefinitions

Artigo
01/11/2024

Nota

No Azure Active Directory B2C, as políticas personalizadas são concebidas principalmente para abordar cenários complexos. Para a maioria dos cenários, recomendamos que utilize fluxos de utilizador incorporados. Se ainda não o fez, saiba mais sobre o pacote de introdução de políticas personalizadas em Introdução às políticas personalizadas no Active Directory B2C.

Pode personalizar o aspeto e a funcionalidade de qualquer perfil técnico auto-afirmado. O Azure Active Directory B2C (Azure AD B2C) executa código no browser do cliente e utiliza uma abordagem moderna denominada Partilha de Recursos Entre Origens (CORS).

Para personalizar a interface de utilizador, especifique um URL no elemento ContentDefinition com conteúdo HTML personalizado. No perfil técnico auto-afirmado ou OrchestrationStep, aponta 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 carregar. Azure AD B2C intercala elementos da interface de utilizador com o conteúdo HTML que é carregado a partir do URL e, em seguida, apresenta a página ao utilizador.

O elemento ContentDefinitions contém URLs para modelos HTML5 que podem ser utilizados num percurso de utilizador. O URI da página HTML5 é utilizado para um passo de interface de utilizador especificado. Por exemplo, as páginas de início de sessão ou inscrição, reposição de palavra-passe ou erro. Pode modificar o aspeto e a funcionalidade ao substituir o LoadUri para o ficheiro HTML5. Pode criar novas definições de conteúdo de acordo com as suas necessidades. Este elemento pode conter uma referência de recursos localizados ao identificador de localização especificado no elemento Localização .

O exemplo seguinte 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 auto-afirmado 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	Necessário	Descrição
Id	Yes	Um identificador para uma definição de conteúdo. O valor é um especificado na secção IDs de definição de conteúdo mais à frente nesta página.

O elemento ContentDefinition contém os seguintes elementos:

Elemento	Ocorrências	Descrição
LoadUri	1:1	Uma cadeia que contém o URL da página HTML5 para a definição de conteúdo.
RecoveryUri	1:1	Uma cadeia que contém o URL da página HTML para apresentar um erro relacionado com a definição de conteúdo. Não utilizado atualmente, o valor tem de ser `~/common/default_page_error.html`.
DataUri	1:1	Uma cadeia que contém o URL relativo de um ficheiro HTML que fornece a experiência do utilizador a invocar para o passo.
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. Utilize este elemento para personalizar a localização de um atributo de interface de utilizador e afirmações.

LoadUri

O elemento LoadUri é utilizado para especificar o URL da página HTML5 para a definição de conteúdo. Os Azure AD pacotes de introdução de políticas personalizadas B2C são fornecidos com definições de conteúdo que utilizam Azure AD páginas HTML B2C. O LoadUri começa com ~, que é um caminho relativo para o seu inquilino Azure AD B2C.

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

Pode personalizar a interface de utilizador com modelos HTML. Ao utilizar modelos HTML, forneça um URL absoluto. O exemplo seguinte ilustra uma definição de conteúdo com o 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 é utilizado para especificar o identificador de página. Azure AD B2C utiliza o identificador de página para carregar e iniciar elementos da IU e JavaScript do lado do cliente. O formato do valor é urn:com:microsoft:aad:b2c:elements:page-name:version. A tabela seguinte lista os identificadores de página que pode utilizar.

Identificador de página	Descrição
`globalexception`	Apresenta uma página de erro quando é encontrada uma exceção ou um erro.
`providerselection`, `idpselection`	Lista os fornecedores de identidade que os utilizadores podem escolher durante o início de sessão.
`unifiedssp`	Apresenta um formulário para iniciar sessão com uma conta local baseada num endereço de e-mail ou num nome de utilizador. Este valor também fornece a ligação "manter a funcionalidade de início de sessão" e "Esqueceu-se da palavra-passe?".
`unifiedssd`	Apresenta um formulário para iniciar sessão com uma conta local baseada num endereço de e-mail ou num nome de utilizador. Este identificador de página foi preterido. Em alternativa, utilize o `unifiedssp` identificador de página.
`multifactor`	Verifica os números de telefone utilizando texto ou voz durante a inscrição ou início de sessão.
`selfasserted`	Apresenta um formulário para recolher dados de um utilizador. Por exemplo, permite que os utilizadores criem ou atualizem o respetivo perfil.

Selecionar um esquema de página

Pode ativar o código do lado do cliente javaScript ao inserir 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údos que contém HTML, CSS e JavaScript para os elementos da interface de utilizador na sua política. Se pretender ativar o código do lado do cliente do JavaScript, os elementos em que baseou o JavaScript têm de ser imutáveis. Se não forem imutáveis, quaisquer alterações podem causar um comportamento inesperado nas páginas de utilizador. Para evitar estes problemas, aplique a utilização de um esquema de página e especifique uma versão de esquema de página. Ao fazê-lo, garante que todas as definições de conteúdo em que baseou o JavaScript são imutáveis. Mesmo que não pretenda ativar o JavaScript, ainda tem de especificar a versão do esquema de página para as suas páginas.

O exemplo seguinte mostra o DataUri da 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> -->

Migrar para o esquema de página

Para migrar do valor DataUri antigo (sem contrato de página) para a versão do esquema de página, adicione a palavra contract seguido de uma versão de página. Utilize a tabela seguinte para migrar do valor DataUri antigo para a versão do esquema de página.

Valor DataUri Antigo	Novo valor 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 exemplo seguinte mostra os identificadores de definição de conteúdo e o DataUri correspondente com a versão mais recente da página:

<!-- 
<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 metadados contém os seguintes elementos:

Elemento	Ocorrências	Descrição
Item	0:n	Os metadados relacionados com a definição de conteúdo.

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

Atributo	Necessário	Descrição
Chave	Yes	A chave de metadados.

Chaves de metadados

A definição de conteúdo suporta os seguintes itens de metadados:

Chave	Necessário	Descrição
DisplayName	No	Uma cadeia que contém o nome da definição de 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 recursos localizados para a definição de conteúdo.

O elemento LocalizedResourcesReference contém os seguintes atributos:

Atributo	Necessário	Descrição
Linguagem	Yes	Uma cadeia que contém um idioma suportado para a política por RFC 5646 - Etiquetas para Identificar Idiomas.
LocalizedResourcesReferenceId	Yes	O identificador do elemento LocalizedResources .

O exemplo seguinte mostra uma definição de conteúdo de inscrição ou início de sessã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 às definições de conteúdo, veja Localização.

IDs de definição de conteúdo

O atributo ID do elemento ContentDefinition especifica o tipo de página relacionado com a definição de conteúdo. O elemento define o contexto que um modelo HTML5/CSS personalizado vai aplicar. A tabela seguinte descreve o conjunto de IDs de definição de conteúdo que é reconhecido pelo Identity Experience Framework e os tipos de página relacionados com os mesmos. Pode criar as suas próprias definições de conteúdo com um ID arbitrário.

ID	Modelo predefinido	Descrição
api.error	exception.cshtml	Página de erro – apresenta uma página de erro quando é encontrada uma exceção ou um erro.
api.idpselections	idpSelector.cshtml	Página de seleção do fornecedor de identidade – lista os fornecedores de identidade que os utilizadores podem escolher durante o início de sessão. Normalmente, as opções são fornecedores de identidade empresarial, fornecedores de identidade social como o Facebook e Google+, ou contas locais.
api.idpselections.signup	idpSelector.cshtml	Seleção do fornecedor de identidade para inscrição – lista os fornecedores de identidade que os utilizadores podem escolher durante a inscrição. Normalmente, as opções são fornecedores de identidade empresarial, fornecedores de identidade social como o Facebook e Google+, ou contas locais.
api.localaccountpasswordreset	selfasserted.cshtml	Página Esqueci-me da palavra-passe – apresenta um formulário que os utilizadores têm de concluir para iniciar uma reposição de palavra-passe.
api.localaccountsignin	selfasserted.cshtml	Página de início de sessão da conta local – apresenta um formulário para iniciar sessão com uma conta local baseada num endereço de e-mail ou num nome de utilizador. O formulário pode conter uma caixa de entrada de texto e uma caixa de entrada de palavra-passe.
api.localaccountsignup	selfasserted.cshtml	Página de inscrição da conta local – apresenta um formulário para se inscrever numa conta local baseada num endereço de e-mail ou num nome de utilizador. O formulário pode conter vários controlos de entrada, tais como: uma caixa de entrada de texto, uma caixa de entrada de palavra-passe, um botão de opção, caixas pendentes de seleção única e caixas de verificação com seleção múltipla.
api.phonefactor	multifactor-1.0.0.cshtml	Página de autenticação multifator – verifica os números de telefone, utilizando texto ou voz, durante a inscrição ou o início de sessão.
api.selfasserted	selfasserted.cshtml	Página de inscrição de conta social – apresenta um formulário que os utilizadores têm de preencher quando se inscrevem através de uma conta existente de um fornecedor de identidade social. Esta página é semelhante à página de inscrição da conta social anterior, exceto os campos de entrada de palavra-passe.
api.selfasserted.profileupdate	updateprofile.cshtml	Página de atualização de perfil – apresenta um formulário ao qual os utilizadores podem aceder para atualizar o respetivo perfil. Esta página é semelhante à página de inscrição da conta social, exceto os campos de entrada de palavra-passe.
api.signuporsignin	unified.cshtml	Página de inscrição ou início de sessão unificada – processa o processo de inscrição e início de sessão do utilizador. Os utilizadores podem utilizar fornecedores de identidade empresarial, fornecedores de identidade social, como o Facebook, Google+, ou contas locais.

Passos seguintes

Para obter um exemplo de personalização da interface de utilizador através de definições de conteúdo, consulte:

Personalizar a interface de utilizador da sua aplicação com uma política personalizada

Partilhar via