Definir um perfil técnico de autenticação multifator do Microsoft Entra ID em uma política personalizada do Azure AD B2C

  • Artigo

O Azure Ative Directory B2C (Azure AD B2C) fornece suporte para verificar um número de telefone usando um código de verificação ou verificando um código TOTP (One-time Password - Senha de Uso Único) baseada no tempo.

Protocolo

O atributo Name do elemento Protocol precisa ser definido como Proprietary. O atributo handler deve conter o nome totalmente qualificado do assembly do manipulador de protocolo usado pelo Azure AD B2C:

Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

O exemplo a seguir mostra um perfil técnico de autenticação multifator do Microsoft Entra ID:

<TechnicalProfile Id="AzureMfa-SendSms">
    <DisplayName>Send Sms</DisplayName>
    <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
    ...

Verificar o modo de telefone

No modo de verificação de telefone, o perfil técnico gera e envia um código para um número de telefone e, em seguida, verifica o código. O perfil técnico de autenticação multifator do Microsoft Entra ID também pode retornar uma mensagem de erro. O perfil técnico de validação valida os dados fornecidos pelo usuário antes que a jornada do usuário continue. Com o perfil técnico de validação, uma mensagem de erro é exibida em uma página autodeclarada. O perfil técnico:

  • Não fornece uma interface para interagir com o usuário. Em vez disso, a interface do usuário é chamada a partir de um perfil técnico autodeclarado ou um controle de exibição como um perfil técnico de validação.
  • Usa o serviço de autenticação multifator Microsoft Entra para gerar e enviar um código para um número de telefone e, em seguida, verifica o código.
  • Valida um número de telefone através de mensagens de texto.

O perfil técnico fornece métodos para enviar o código de verificação via mensagem de texto SMS e verificar o código. A captura de tela a seguir mostra o fluxo do verificador do telefone.

Screenshot showing TOTP flow

Enviar SMS

Para verificar um telefone, o primeiro passo gera um código e envia-o para o número de telefone. As opções a seguir podem ser configuradas para esta etapa.

Declarações de entrada

O elemento InputClaims contém uma lista de declarações a serem enviadas à autenticação multifator do Microsoft Entra. Você também pode mapear o nome da sua reivindicação para o nome definido no perfil técnico do MFA.

ClaimReferenceId Obrigatório Descrição
userPrincipalName Sim O identificador do usuário proprietário do número de telefone.
phoneNumber Sim O número de telefone para o qual enviar um código SMS.
companyName Não O nome da empresa no SMS. Se não for fornecido, o nome do seu aplicativo será usado.
locale Não A localidade do SMS. Se não for fornecida, a localidade do navegador do usuário será usada.

Declarações de saída

O provedor de protocolo de autenticação multifator Microsoft Entra não retorna nenhuma declaração de saída, portanto, não há necessidade de especificar declarações de saída.

Metadados

O elemento Metadata contém o seguinte atributo.

Atributo Obrigatório Descrição
Operation Sim Deve ser OneWaySMS.
Elementos da IU

Os metadados a seguir podem ser usados para configurar as mensagens de erro exibidas após o envio de falha de SMS. Os metadados devem ser configurados no perfil técnico autodeclarado . As mensagens de erro podem ser localizadas.

Atributo Obrigatório Description
UserMessageIfCouldntSendSms Não Mensagem de erro do usuário se o número de telefone fornecido não aceitar SMS.
UserMessageIfInvalidFormat Não Mensagem de erro do utilizador se o número de telefone fornecido não for um número de telefone válido.
UserMessageIfServerError Não Mensagem de erro do usuário se o servidor encontrou um erro interno.
UserMessageIfThrottled Não Mensagem de erro do usuário se uma solicitação tiver sido limitada.

Exemplo: enviar um SMS

O exemplo a seguir mostra um perfil técnico de autenticação multifator do Microsoft Entra ID que é usado para enviar um código via SMS.

<TechnicalProfile Id="AzureMfa-SendSms">
  <DisplayName>Send Sms</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="Operation">OneWaySMS</Item>
  </Metadata>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="CombinePhoneAndCountryCode" />
    <InputClaimsTransformation ReferenceId="ConvertStringToPhoneNumber" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userPrincipalName" />
    <InputClaim ClaimTypeReferenceId="fullPhoneNumber" PartnerClaimType="phoneNumber" />
  </InputClaims>
</TechnicalProfile>

Verificar código

A etapa de verificação de código verifica um código enviado ao usuário. As opções a seguir podem ser configuradas para esta etapa.

Declarações de entrada

O elemento InputClaims contém uma lista de declarações a serem enviadas à autenticação multifator do Microsoft Entra. Você também pode mapear o nome da sua reivindicação para o nome definido no perfil técnico do MFA.

ClaimReferenceId Obrigatório Descrição
phoneNumber Sim O mesmo número de telefone usado anteriormente para enviar um código. Ele também é usado para localizar uma sessão de verificação por telefone.
verificationCode Sim O código de verificação fornecido pelo usuário a ser verificado

Declarações de saída

O provedor de protocolo de autenticação multifator Microsoft Entra não retorna nenhuma declaração de saída, portanto, não há necessidade de especificar declarações de saída.

Metadados

O elemento Metadata contém o seguinte atributo.

Atributo Obrigatório Descrição
Operation Sim Deve ser Verify.
Elementos da IU

Os metadados a seguir podem ser usados para configurar as mensagens de erro exibidas após falha na verificação de código. Os metadados devem ser configurados no perfil técnico autodeclarado . As mensagens de erro podem ser localizadas.

Atributo Obrigatório Description
UserMessageIfMaxAllowedCodeRetryReached Não Mensagem de erro do usuário se o usuário tentou um código de verificação muitas vezes.
UserMessageIfServerError Não Mensagem de erro do usuário se o servidor encontrou um erro interno.
UserMessageIfThrottled Não Mensagem de erro do usuário se a solicitação estiver limitada.
UserMessageIfWrongCodeEntered Não Mensagem de erro do utilizador se o código introduzido para verificação estiver errado.

Exemplo: verificar um código

O exemplo a seguir mostra um perfil técnico de autenticação multifator do Microsoft Entra ID usado para verificar o código.

<TechnicalProfile Id="AzureMfa-VerifySms">
    <DisplayName>Verify Sms</DisplayName>
    <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
    <Metadata>
        <Item Key="Operation">Verify</Item>
    </Metadata>
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="phoneNumber" PartnerClaimType="phoneNumber" />
        <InputClaim ClaimTypeReferenceId="verificationCode" />
    </InputClaims>
</TechnicalProfile>

Modo TOTP

Nesse modo, o usuário deve instalar qualquer aplicativo autenticador que ofereça suporte à verificação de senha única baseada no tempo (TOTP), como o aplicativo Microsoft Authenticator, em um dispositivo de sua propriedade.

Durante a primeira inscrição ou login, o usuário escaneia um código QR, abre um link direto ou insere o código manualmente usando o aplicativo autenticador. Para verificar o código TOTP, use Begin verify OTP seguido de Verify TOTP validation technical profiles.

Para entradas subsequentes, use o método Obter dispositivos disponíveis para verificar se o usuário já registrou seu dispositivo. Se o número de dispositivos disponíveis for maior que zero, isso indica que o usuário se inscreveu antes. Nesse caso, o usuário precisa digitar o código TOTP que aparece no aplicativo autenticador.

O perfil técnico:

  • Não fornece uma interface para interagir com o usuário. Em vez disso, a interface do usuário é chamada a partir de um perfil técnico autodeclarado , com os controles de exibição TOTP.
  • Usa o serviço de autenticação multifator Microsoft Entra para validar o código TOTP.
  • Verifica se um usuário já registrou seu dispositivo.

A captura de tela a seguir mostra um fluxo de registro e verificação do TOTP. Começa por verificar o número de dispositivos disponíveis. Se o número de dispositivos disponíveis for zero, o usuário passará pela etapa de orquestração de registro. Caso contrário, o usuário passa pela etapa de orquestração de verificação.

Screenshot showing TOTP flow.

Obtenha dispositivos disponíveis

O modo de dispositivo disponível verifica o número de dispositivos disponíveis para o usuário. Se o número de dispositivos disponíveis for zero, isso indica que o usuário ainda não se inscreveu.

Declarações de entrada

O elemento InputClaims contém uma lista de declarações a serem enviadas à autenticação multifator do Microsoft Entra. Você também pode mapear o nome da sua reivindicação para o nome definido no perfil técnico do MFA.

ClaimReferenceId Obrigatório Descrição
userPrincipalName Sim O nome principal do usuário.

Declarações de saída

O elemento de declarações de saída contém uma lista de declarações a serem retornadas da autenticação multifator do Microsoft Entra. Você também pode mapear o nome da sua reivindicação para o nome definido no perfil técnico do MFA.

ClaimReferenceId Obrigatório Descrição
numberOfAvailableDevices Sim O número de dispositivos disponíveis para o usuário.

Metadados

O elemento Metadata contém o seguinte atributo.

Atributo Obrigatório Descrição
Operation Sim Deve ser GetAvailableDevices.

Exemplo: Obter dispositivos disponíveis

O exemplo a seguir mostra um perfil técnico de autenticação multifator do Microsoft Entra ID usado para obter o número de dispositivos disponíveis.

<TechnicalProfile Id="AzureMfa-GetAvailableDevices">
  <DisplayName>Get Available Devices</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="Operation">GetAvailableDevices</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userPrincipalName" />
  </InputClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="numberOfAvailableDevices" />
  </OutputClaims>
</TechnicalProfile>

Comece a verificar o TOTP

O TOTP start verify inicia o processo de verificação. Este perfil técnico de validação é chamado a partir do perfil técnico autoafirmado que apresenta e verifica os códigos TOTP. Este perfil técnico de validação deve ser seguido por uma chamada para Verificar perfis técnicos de validação TOTP .

Declarações de entrada

O elemento InputClaims contém uma lista de declarações a serem enviadas à autenticação multifator do Microsoft Entra. Você também pode mapear o nome da sua reivindicação para o nome definido no perfil técnico do MFA.

ClaimReferenceId Obrigatório Descrição
userPrincipalName Sim O nome principal do usuário.
objectId Sim O ID do objeto do usuário.
secretKey Sim A chave secreta do usuário. Essa chave é armazenada no perfil do usuário no diretório do Azure AD B2C e é compartilhada com o aplicativo autenticador. O aplicativo autenticador usa o segredo para gerar o código TOTP. Este perfil técnico usa o segredo para verificar o código TOTP.

Declarações de saída

O provedor de protocolo de autenticação multifator Microsoft Entra não retorna nenhuma declaração de saída, portanto, não há necessidade de especificar declarações de saída.

Metadados

O elemento Metadata contém o seguinte atributo.

Atributo Obrigatório Descrição
Operation Sim Deve ser BeginVerifyOTP.

Exemplo: Começar a verificar o TOTP

O exemplo a seguir mostra um perfil técnico de autenticação multifator do Microsoft Entra ID usado para iniciar o processo de verificação TOTP.

<TechnicalProfile Id="AzureMfa-BeginVerifyOTP">
  <DisplayName>Begin verify TOTP"</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="Operation">BeginVerifyOTP</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="secretKey" />
    <InputClaim ClaimTypeReferenceId="objectId" />
    <InputClaim ClaimTypeReferenceId="userPrincipalName" />
  </InputClaims>
</TechnicalProfile>

Verificar TOTP

O método verify TOTP verifica um código TOTP. Este perfil técnico de validação é chamado a partir do perfil técnico autoafirmado que apresenta e verifica os códigos TOTP. Este perfil técnico de validação deve ser precedido por uma chamada para os perfis técnicos de validação Begin verify TOTP .

Declarações de entrada

O elemento InputClaims contém uma lista de declarações a serem enviadas à autenticação multifator do Microsoft Entra. Você também pode mapear o nome da sua reivindicação para o nome definido no perfil técnico do MFA.

ClaimReferenceId Obrigatório Descrição
otpCode Sim O código TOTP fornecido pelo usuário.

Declarações de saída

O provedor de protocolo de autenticação multifator Microsoft Entra não retorna nenhuma declaração de saída, portanto, não há necessidade de especificar declarações de saída.

Metadados

O elemento Metadata contém o seguinte atributo.

Atributo Obrigatório Descrição
Operation Sim Deve ser VerifyOTP.

Exemplo: Verificar TOTP

O exemplo a seguir mostra um perfil técnico de autenticação multifator do Microsoft Entra ID usado para verificar um código TOTP.

<TechnicalProfile Id="AzureMfa-VerifyOTP">
  <DisplayName>Verify OTP</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="Operation">VerifyOTP</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="otpCode" />
  </InputClaims>
</TechnicalProfile>

Próximos passos