Com a GUI

É possível configurar o canal de e-mail do MFA por meio da GUI.

1. Navegue para a guia Cloud Directory > Autenticação de diversos fatores do painel do App ID.

2. Na caixa Ativar autenticação de diversos fatores, na guia Configurações, alterne a MFA para Ativada. Esteja ciente de que o MFA é cobrado como um evento de segurança avançado. Por padrão, E-mail é selecionado como o Método de autenticação.

3. Na guia Canal de email, revise o Modelo de email. É possível optar por enviar o modelo com o texto fornecido ou gravar sua própria mensagem. Certifique-se de usar a identificação HTML correta. No console, você pode adicionar parâmetros e inserir imagens. Para alterar o idioma da mensagem, você pode usar as APIs para definir o idioma. No entanto, você é responsável pelo conteúdo e pela conversão da mensagem. Consulte a tabela a seguir para ver a lista de tabelas que podem ser usadas nessa mensagem e em todas as outras mensagens que pode enviar. Se um usuário não fornecer as informações extraídas pelo parâmetro, elas aparecerão em branco.

   Parâmetros da mensagem MFA

   Parâmetro	Descrição
   %{display.logo}	Exibe a imagem que você configurou para o widget de login.
   %{user.displayName}	Exibe o nome da tela que um usuário escolheu usar ao interagir com o app.
   %{user.email}	Exibe o endereço de e-mail do usuário registrado.
   %{user.username}	Exibe o nome do usuário especificado quando o método de autenticação é configurado para o nome do usuário e a senha.
   %{user.firstName}	Exibe o nome especificado do usuário.
   %{user.formattedName}	Exibe o nome completo do usuário.
   %{user.lastName}	Exibe o sobrenome especificado do usuário.
   %{mfa.code}	Exibe um código de verificação de MFA único.

   Se um usuário não fornecer as informações extraídas pelo parâmetro, elas aparecerão em branco.

Com as APIs

Certifique-se de que você tenha os pré-requisitos a seguir:

• O seu ID do locatário da instância do App ID. Esse ID pode ser localizado na seção Credenciais de serviço do painel.
• O seu token de Gerenciamento de identidade e acesso (IAM). Para obter ajuda com a obtenção de um token do IAM, consulte os docs do IAM.

Para ativar a MFA:

1. Ative o MFA fazendo uma solicitação PUT para o terminal /config/cloud_directory/mfa com a sua configuração do MFA para definir isActive como true.

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa \
      --header 'Content-Type: application/json' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <IAMToken>' \
      -d '"isActive": true'
   

2. Habilite seu canal MFA fazendo uma solicitação PUT para o ponto de extremidade /mfa/channels/<channel> com sua configuração MFA. Quando isActive é configurado como true, seu canal da MFA está ativado.

   $ curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/mfa/channels/email \
      --header 'Content-Type: application/json' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <IAMToken>' \
      -d '"isActive": true'
   

Se sua instância do App ID Cloud Directory estiver configurada para trabalhar com um remetente de e-mail customizado, a MFA usará o mesmo remetente para entregar o código descartável. Para obter mais informações, consulte os Docs do Cloud Directory.

Antes de Iniciar

App ID usa a Vonage (formalmente Nexmo) para enviar códigos únicos MFA SMS.

• Obtenha sua chave de API e o segredo do Vonage. É possível localizar a chave de API e o segredo do Vonage na página de configurações de sua conta no painel do Vonage. Consulte a documentação da Vonage para obter mais informações sobre como obter suas credenciais.

• Registre seu ID do remetente ou o número from com o Vonage. Esse número from é o que aparece no telefone do seu usuário para mostrar de quem é o SMS. Em alguns países, o Vonage suporta IDs de remetente alfanuméricos. O App ID usa o valor que você insere como ID de remetente do Vonage. Portanto, se eles forem suportados pelo Vonage, será possível usar os IDs com o App ID.

Com a GUI

Para configurar o MFA com a GUI, consulte o Cloud Directory.

1. Navegue para a guia Cloud Directory > Autenticação de diversos fatores do painel do App ID.

2. Na caixa Ativar autenticação de diversos fatores, na guia Configurações, alterne a MFA para Ativada. Esteja ciente de que o MFA é cobrado como um evento de segurança avançado.

3. Selecione SMS como seu Método de autenticação.

4. Na guia Canal SMS, configure as informações de conta do Vonage.

   1. Se você ainda não tiver uma conta com o Vonage. Crie uma.

   2. No painel do Vonage, clique em SMS.

   3. Na seção Codifique você mesmo, copie a chave de API e cole-a na caixa chave no painel do App ID.

   4. Copie o segredo da API no painel do Vonage e cole-o na caixa Segredo no painel do App ID.

   5. Digite o ID do qual você deseja enviar mensagens. Um formato de número válido segue o formato de numeração internacional E.164. Por exemplo, um número dos EUA tem o formato +19998887777. Deve-se especificar o código do país, começando com um símbolo + e o número do assinante nacional. Em alguns países, o Vonage suporta IDs de remetente alfanuméricos. O App ID usa o valor que você insere como ID de remetente do Vonage. Portanto, se eles forem suportados pelo Vonage, será possível usar os IDs com o App ID.

Com as APIs

Antes de começar a usar a API, certifique-se de que você tenha os pré-requisitos a seguir:

• O seu ID do locatário da instância do App ID. Esse ID pode ser localizado na seção Credenciais de serviço do painel.
• O seu token de Gerenciamento de identidade e acesso (IAM). Para obter ajuda com a obtenção de um token do IAM, consulte os docs do IAM.

1. Ative o MFA fazendo uma solicitação PUT para o terminal /config/cloud_directory/mfa com a sua configuração do MFA para definir isActive como true.

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{"isActive": true}'
   

2. Habilite seu canal MFA fazendo uma solicitação PUT para o ponto de extremidade /mfa/channels/<channel> com sua configuração MFA. Quando isActive é configurado como true, seu canal da MFA está ativado. A configassume a chave e o segredo da API Nexmo, bem como o número from.

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/mfa/channels/nexmo' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{
      "isActive": true,
      "config": {
         "key": "<nexmoKey>",
         "secret": "<nexmoSecret>",
         "from": <senderPhoneNumber>
      }
   }'
   

3. Depois que o canal for configurado com êxito, verifique se a configuração e a conexão do Nexmo estão definidas corretamente usando o botão de teste no console ou usando a API de gerenciamento.

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/sms_dispatcher/test \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{"phone_number": "+1 999 999 9999"}'
   

Antes de Iniciar

Antes de você registrar a sua extensão, certifique-se de ter os pré-requisitos a seguir:

• O seu ID do locatário da instância do App ID. Esse ID pode ser localizado na seção Aplicativos do painel.
• O seu token de Gerenciamento de identidade e acesso (IAM). Para obter ajuda com a obtenção de um token do IAM, consulte os docs do IAM.

Para obter mais informações sobre as restrições e limitações de trabalhar com extensões, consulteLimites do App ID.

Configurando a pré-MFA

Com uma extensão pré-MFA, é possível definir os critérios que permitem que os usuários evitem ter que inserir um segundo formulário de autenticação quando interagem com o seu aplicativo.

1. Quando um usuário se conecta ao seu aplicativo, o App ID envia uma solicitação de POST para a sua extensão.
2. A sua extensão usa as informações da solicitação de POST para determinar se aquele usuário específico pode ignorar o segundo requisito do fator de autenticação com base nos critérios que você definiu.
3. A sua configuração retorna uma resposta de JSON para o App ID que parece semelhante a {'skipMfa': true}.
4. Com base na resposta de sua configuração, o App ID continua com o fluxo de MFA ou concede acesso ao seu aplicativo.

Por padrão, se ocorrer um erro durante a solicitação para o seu ponto de extensão, o App ID requererá que o usuário conclua o MFA.

Para configurar uma extensão pré-MFA:

1. Defina os critérios que você deseja que um usuário atenda antes que ele esteja apto a ignorar o segundo fator de autenticação. Consulte os exemplos a seguir para obter algumas ideias, se você não tiver certeza.

   Exemplos de critérios para pular o MFA

   Caso de uso de exemplo	Validação de exemplo
   Você deseja que os usuários forneçam um segundo fator de autenticação apenas uma vez por dia.	Configure a sua extensão para validar que o last_successful_first_factor está dentro do mesmo dia.
   Você tem uma lista de permissões de usuários aprovados que não precisam fornecer o segundo fator toda vez.	Configure sua extensão para verificar se o username ou user_id está na lista de permissões.
   Você não deseja que os usuários acessem o seu app em uma área de trabalho para fornecer o segundo fator toda vez.	Configure a sua extensão para validar que o device_type está configurado como web.

2. Quando você souber os seus critérios, configure uma extensão que possa atender uma solicitação de POST. O terminal deve estar apto a ler a carga útil que se origina do App ID. O corpo que é enviado pelo App ID antes do fluxo do MFA iniciar está no formato: {"jws": "jws-format-string"}. A sua extensão também pode decodificar e validar a carga útil, o conteúdo é um objeto de JSON e retornar uma resposta de JSON com o esquema a seguir: {"skipMfa": Boolean }. Por exemplo,: {'skipMfa': true}.

   As informações que o App ID encaminha ao seu ponto de ramal.

   Informações	Descrição
   correlation_id	Um número aleatório que é gerado para cada sessão de MFA. Se você tiver tanto uma extensão pré-MFA quanto uma pós-MFA, o número será o mesmo para cada uma delas para a mesma sessão. Por exemplo, 3bb9236c-792f-4cca-8ae1-ada754cc4555.
   extension	O nome de sua extensão. Para esse caso de uso, a extensão é denominada premfa.
   device_type	O tipo de dispositivo com o qual o usuário está acessando o seu aplicativo. As opções incluem: web e mobile.
   source_ip	O endereço IP do dispositivo que faz a solicitação para o seu app. Por exemplo, 127.0.0.1.
   headers	As informações que são retornadas pelo navegador quando um usuário tenta se conectar a seu app. O cabeçalho é semelhante a: {"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0"}.
   tenant_id	O ID do locatário do seu aplicativo.
   client_id	O ID do cliente do seu aplicativo.
   user_id	O ID do usuário que faz a solicitação de autenticação. Por exemplo, 11112222-3333-4444-2222-555522226666.
   username	O nome de usuário do usuário que faz a solicitação de autenticação. Por exemplo, testuser@email.com.
   application_type	O tipo do seu aplicativo. Por exemplo, se o seu aplicativo for um aplicativo da web JavaScript de página única, browserapp será retornado. As opções incluem: browserapp, serverapp e mobileapp.
   first_name	O nome dado pelos usuários.
   last_name	O sobrenome dos usuários.
   last_successful_first_factor	A data da última vez em que o usuário inseriu corretamente as credenciais dele. Por exemplo, 1660032586651.
   last_successful_mfa	A data da última vez em que o usuário concluiu o fluxo do MFA completo. Por exemplo, 1660032586651.

   Para ver um exemplo de extensão, confira a amostra.

3. Registre a sua extensão com a sua instância de App ID fazendo uma solicitação de PUT para config/cloud_directory/mfa/extensions/premfa. A configuração inclui a URL do seu ramal e qualquer informação de autorização que seja necessária para acessar o terminal. Para fins de desenvolvimento, isActive é configurado como false. Certifique-se de testar a sua configuração antes de ativá-la.

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/premfa' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{
      "isActive": false,
      "config": {
         "url": "<extensionsURL>",
         "headers": {
               "Authorization": "<customExtensionAuthorizationHeader>"
            }
      }
   }'
   

   É altamente recomendável que você sempre use HTTPS em vez de HTTP para o extensions_URL para assegurar que sua conexão seja criptografada.

4. Depois que a extensão for configurada com sucesso, verifique se o seu terminal funciona corretamente usando a API de teste. O App ID faz uma solicitação POST para a sua extensão configurada com os valores de exemplo.

   curl -X POST https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/premfa/test \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>'
   

5. Ative a sua extensão fazendo uma solicitação de PUT que configure isActive comotrue.

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/premfa \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{"isActive": true}'
   

   Para desativar a sua extensão, configure isActive como false.

Configurando a pós-MFA

Ao configurar uma extensão e registrá-la no App ID, o serviço chama a sua extensão após cada tentativa de autenticação na qual um segundo fator de identificação está presente. É possível usar essas informações para tomar as melhores decisões para seus usuários. Por exemplo, é possível usar informações de coleta da extensão pós-MFA para sua heurística e suas regras e, em seguida, aplicá-las usando a extensão pré-MFA.

1. Quando um usuário se conecta com sucesso ao seu aplicativo, é solicitado que ele insira o segundo fator de autenticação dele.

2. Quando o segundo fator de autenticação é concluído com sucesso, duas ações simultâneas ocorrem:

   1. O App ID envia informações sobre a conexão à sua extensão configurada.

   2. O usuário é redirecionado para o seu aplicativo.

Para configurar uma extensão pós-MFA:

1. Configure um ponto de extensão que possa atender a uma solicitação de POST. O terminal deve estar apto a ler a carga útil que é enviada por App ID. Opcionalmente, ele também pode decodificar e validar que a carga útil JSON que é retornada pelo App ID não é alterada por um terceiro de maneira alguma. É retornada uma sequência que é formatada como {"jws": "jws-format-string"} que contém as informações a seguir:

   As informações que o App ID encaminha ao seu ponto de ramal.

   Informações	Descrição
   correlation_id	Um número aleatório que é gerado para cada sessão de MFA. Se você tiver tanto uma extensão pré-MFA quanto uma pós-MFA, o número será o mesmo para cada uma delas. Por exemplo, 3bb9236c-792f-4cca-8ae1-ada754cc4555.
   extension	O nome de sua extensão. Para esse caso de uso, a extensão é denominada postmfa.
   status	O status da MFA. As opções incluem: success e failed.
   reason	O motivo para uma falha da MFA. Por exemplo, user locked out - exceeded maximum number of verification attempts.
   device_type	O tipo de dispositivo com o qual o seu usuário acessa o seu aplicativo. As opções incluem: web, mobile.
   source_ip	O endereço IP do dispositivo que faz a solicitação para o seu app. Por exemplo, 127.0.0.1.
   headers	As informações que são retornadas pelo navegador quando um usuário tenta se conectar a seu app. O cabeçalho é semelhante a {"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0"}.
   tenant_id	O ID do locatário do seu aplicativo.
   client_id	O ID do cliente do seu aplicativo.
   user_id	O ID do usuário que faz a solicitação de autenticação.
   username	O nome de usuário do usuário que faz a solicitação de autenticação. Por exemplo, testuser@email.com.
   application_type	O tipo do seu aplicativo. Por exemplo, se o seu aplicativo for um aplicativo da web JavaScript de página única, browserapp será retornado. As opções incluem: browserapp, serverapp e mobileapp.
   first_name	O nome dado pelos usuários.
   last_name	O sobrenome dos usuários.

2. Registre a sua extensão com a sua instância de App ID fazendo uma solicitação de PUT para config/cloud_directory/mfa/extensions/postmfa. A configuração inclui a URL do seu ramal e qualquer informação de autorização que seja necessária para acessar o terminal. Para fins de desenvolvimento, isActive é configurado como false. Certifique-se de testar a sua configuração antes de ativá-la.

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/postmfa' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{
      "isActive": false,
      "config": {
         "url": "<extensionsURL>",
         "headers": {
               "Authorization": "<customExtensionAuthorizationHeader>"
            }
      }
   }'
   

   É altamente recomendável que você sempre use HTTPS em vez de HTTP para o extensions_URL para assegurar que sua conexão seja criptografada.

3. Depois que a extensão for configurada com sucesso, verifique se o seu terminal funciona corretamente usando a API de teste. O App ID faz uma solicitação de POST para a sua extensão configurada com os valores de exemplo.

   curl -X POST https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/postmfa/test \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>'
   

4. Ative a sua extensão configurando isActive como true.

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/postmfa \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{"isActive": true}'
   

   Para desativar a sua extensão, configure isActive como false.