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

  • Artigo

O Azure Active Directory B2C (Azure AD B2C) fornece suporte para confirmar um número de telefone usando um código de verificação ou confirmando um código de senha de uso único com validade limitada (TOTP).

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 da 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" />
    ...

Modo confirmar telefone

No modo confirmar telefone, o perfil técnico gera e envia um código para um número de telefone e, em seguida, confirma o código. O perfil técnico da 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 fornecido pelo usuário para que o percurso 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 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 do 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 por meio de mensagens de texto.

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

Screenshot showing TOTP flow

Enviar SMS

Para verificar um telefone, a primeira etapa gera um código e o envia para o número de telefone. É possível configurar as opções seguintes.

Declarações de entrada

O elemento InputClaims contém uma lista de declarações a serem enviadas para a autenticação multifator do Microsoft Entra. Também é possível mapear o nome da declaração para o nome definido no perfil técnico do MFA.

ClaimReferenceId Obrigatório Descrição
userPrincipalName Sim O identificador do usuário dono 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 da autenticação multifator do Microsoft Entra não retorna nenhuma declaração de saída, portanto, não é necessário especificar as declarações de saída.

Metadados

O elemento metadados contém o seguinte atributo.

Atributo Obrigatório Descrição
Operation Sim Deve ser OneWaySMS.
Elementos da interface do usuário

Os metadados a seguir podem ser usados para configurar as mensagens de erro exibidas após a falha do envio do SMS. Os metadados devem ser configurados no perfil técnico autodeclarado. A mensagem de erro pode ser localizada.

Atributo Obrigatório Descrição
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 usuário se o número de telefone fornecido não for válido.
UserMessageIfServerError Não Mensagem de erro do usuário se o servidor encontrar 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 da 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 o código

A etapa verificar código confirma um código enviado ao usuário. É possível configurar as opções seguintes.

Declarações de entrada

O elemento InputClaims contém uma lista de declarações a serem enviadas para a autenticação multifator do Microsoft Entra. Também é possível mapear o nome da declaração para o nome definido no perfil técnico do MFA.

ClaimReferenceId Obrigatório Descrição
phoneNumber Sim Mesmo número de telefone usado anteriormente para enviar um código. Ele também é usado para localizar uma sessão de verificação de 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 da autenticação multifator do Microsoft Entra não retorna nenhuma declaração de saída, portanto, não é necessário especificar as declarações de saída.

Metadados

O elemento metadados contém o seguinte atributo.

Atributo Obrigatório Descrição
Operation Sim Deve ser Verify.
Elementos da interface do usuário

Os metadados a seguir podem ser usados para configurar as mensagens de erro exibidas após a falha da verificação do código. Os metadados devem ser configurados no perfil técnico autodeclarado. A mensagem de erro pode ser localizada.

Atributo Obrigatório Descrição
UserMessageIfMaxAllowedCodeRetryReached Não Mensagem de erro do usuário se o usuário tiver tentado um código de verificação muitas vezes.
UserMessageIfServerError Não Mensagem de erro do usuário se o servidor encontrar um erro interno.
UserMessageIfThrottled Não Mensagem de erro do usuário se a solicitação for limitada.
UserMessageIfWrongCodeEntered Não Mensagem de erro do usuário se o código inserido para verificação estiver errado.

Exemplo: verificar um código

O exemplo a seguir mostra um perfil técnico da 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 é solicitado a instalar qualquer aplicativo autenticador que dê suporte à verificação TOTP (senha de uso único) baseada em tempo, como o aplicativo Microsoft Authenticator, em um dispositivo que ele possui.

Durante a primeira inscrição ou entrada, o usuário examina um código QR, abre um link profundo ou insere um código manualmente usando o aplicativo autenticador. Para verificar o código TOTP, use o botão Iniciar verificação de OTP seguido por verificar perfis técnicos de validação TOTP.

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 indicará que o usuário fez a inscrição 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 do Microsoft Entra para validar o código TOTP.
  • Verifica se um usuário já inscreveu seu dispositivo.

A captura de tela a seguir mostra um fluxo de verificação e registro TOTP. Ele começa verificando 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 passará pela etapa de orquestração de verificação.

Screenshot showing TOTP flow.

Obter dispositivos disponíveis

O modo obter 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 foi registrado.

Declarações de entrada

O elemento InputClaims contém uma lista de declarações a serem enviadas para a autenticação multifator do Microsoft Entra. Também é possível mapear o nome da declaração para o nome definido no perfil técnico do MFA.

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

Declarações de saída

O elemento declarações de saída contém uma lista de declarações a serem retornadas pela autenticação multifator do Microsoft Entra. Também é possível mapear o nome da declaraçã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 metadados 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 da 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>

Iniciar verificação TOTP

O iniciar verificação TOTP começa o processo de verificação. Esse perfil técnico de validação é chamado a partir do perfil técnico autodeclarado que apresenta e verifica os códigos TOTP. Esse 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 para a autenticação multifator do Microsoft Entra. Também é possível mapear o nome da declaração para o nome definido no perfil técnico do MFA.

ClaimReferenceId Obrigatório Descrição
userPrincipalName Sim Nome principal do usuário.
objectId Sim A ID de objeto de 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 da autenticação multifator do Microsoft Entra não retorna nenhuma declaração de saída, portanto, não é necessário especificar as declarações de saída.

Metadados

O elemento metadados contém o seguinte atributo.

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

Exemplo: Iniciar verificaçã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 do 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 Verificar TOTP verifica um código TOTP. Esse perfil técnico de validação é chamado a partir do perfil técnico autodeclarado que apresenta e verifica os códigos TOTP. Esse perfil técnico de validação deve ser precedido por uma chamada para verificar perfis técnicos de Iniciar verificação TOTP.

Declarações de entrada

O elemento InputClaims contém uma lista de declarações a serem enviadas para a autenticação multifator do Microsoft Entra. Também é possível mapear o nome da declaraçã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 da autenticação multifator do Microsoft Entra não retorna nenhuma declaração de saída, portanto, não é necessário especificar as declarações de saída.

Metadados

O elemento metadados 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 da 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óximas etapas