Como usar a API Authy com o Google Authenticator (ou qualquer app autenticador compatível)

Tempo de leitura: 4 minutos

August 18, 2020

Escrito por

Kelley Robinson

Twilion

Revisado por

Matthew Gilliard

Twilion

Como usar a API Authy com o Google Authenticator (ou qualquer app autenticador compatível)

TOTP, ou Time-based One-time Password (senha de uso único), é uma maneira de gerar tokens de autenticação de curta duração que são comumente usados para autenticação de dois fatores (2FA). O algoritmo de TOTP é definido no RFC 6238, o que significa que o padrão aberto pode ser implementado de forma compatível em vários aplicativos. Você pode estar familiarizado com a TOTP de aplicativos como o Authy ou o Google Authenticator, mas há muitas outras opções, incluindo o Duo e o Microsoft Authenticator.

Fazer com que os usuários habilitem a 2FA é metade da batalha para melhorar a segurança da conta. Portanto, recomendo dar flexibilidade aos clientes para que eles escolham o app autenticador de sua preferência.

A API Authy (conectado a, mas diferente do app Authy) tem como padrão inscrever o usuário no Authy App mas esta publicação mostrará como a API pode permitir que seus clientes usem o app autenticador da escolha deles.

Você sabia? A TOTP é um padrão aberto, portanto, sempre que um app solicitar o uso do Google Authenticator, você poderá ler o código QR com o Authy, Duo, Microsoft Authenticator ou qualquer app em que o padrão foi implementado.

Como funciona a TOTP?

As entradas para o algoritmo TOTP contém uma chave secreta e a hora do sistema. Elas são inseridas em uma função unidirecional que cria um token truncado e legível. Como as entradas estão disponíveis off-line, todo o método também funciona off-line. Esta é uma ótima opção para usuários que podem ter conexões celulares instáveis para receber SMS 2FA ou para usuários que querem um canal mais seguro do que o SMS 2FA.

Veja como o app Authy solicita que um usuário adicione uma nova conta. Recomendamos a leitura de um código QR, mas você também pode inserir a chave manualmente. É assim que a conta e o app autenticador sincronizam a chave secreta.

Como implementar a TOTP 2FA em seu app

Recomendamos o uso da API Authy para implementar a TOTP em seu app porque ela:

gerencia a geração e a verificação de senhas para você
é compatível com SOC2
inclui nosso suporte ao usuário final
e também tem canais de SMS, voz e e-mail para dar suporte a fallback ou à escolha do usuário

Para registrar um usuário do seu app em qualquer app autenticador, siga as seguintes etapas.

Primeiro, faça login na sua conta da Twilio (ou crie uma nova conta) e crie um app Authy no Console da Twilio.

Em seguida, habilite os tokens TOTP genéricos no console. Role até a parte inferior e "Save" (Salve) suas alterações.

Habilitar tokens genéricos do Authenticator no console

Para validar os códigos TOTP, registre cada usuário com a API para gerar um ID do Authy exclusivo para cada usuário.

Você pode registrar usuários no seu app por uma dessas três maneiras

No console (é necessário o número de telefone e o endereço de e-mail do usuário)
Com a API Authy (usando o número de telefone e o endereço de e-mail do usuário)
Com a API Authy (sem IPI, como número de telefone ou e-mail)

Registrando usuários no seu app usando o console do Twilio Authy

Na guia Users (Usuários) do app Authy no console, clique no sinal de mais vermelho para adicionar um novo usuário. Você precisará do endereço de e-mail e do número de telefone do usuário.

Visualização dos usuários no console do Authy

Registrando usuários no seu app usando a API Authy

Há duas maneiras de adicionar um usuário com a API: com e sem IPI. Vamos ver o exemplo que usa IPI aqui.

Faça uma solicitação ao recurso Users (Usuários) para criar um novo usuário com a chave API Authy para seu app. Este exemplo usa cURL, mas você pode fazer isso na sua linguagem preferida. Veja exemplos em mais linguagens nos documentos.

Você pode encontrar sua chave API Authy pelo console na guia de configurações do app Authy:

Registre o usuário com o seguinte comando:

curl -XPOST "https://api.authy.com/protected/json/users/new" \
-H "X-Authy-API-Key: <your Authy API Key here>" \
--data-urlencode 'user[email]=user@domain.com' \
--data-urlencode 'user[cellphone]=317-338-9302' \
--data-urlencode 'user[country_code]=54'

Ou: siga as instruções na documentação para adicionar um usuário sem IPI.

Todos esses métodos retornam um Authy ID para o usuário recém-registrado. Salve isso com seus registros de usuário, pois ele é um parâmetro obrigatório para futuras solicitações de API.

Crie um código QR para permitir que os usuários façam a integração com o Google Authenticator ou com o app de TOTP da escolha deles

Nesse ponto, o usuário está inscrito no Authy App. Desde que eles tenham se inscrito no app cliente (iOS, Android ou Desktop) com o mesmo número de telefone usado na inscrição, automaticamente eles terão sua conta sendo mostrada como um item dentro do app Authy.

Se o usuário decidir que quer usar um app diferente, você precisará criar um código QR para que ele possa sincronizar a chave secreta com o app autenticador da escolha dele.

Crie um código QR com o seguinte comando. Recomendamos colocar algo identificável no campo de rótulo para que o usuário saiba a qual nome de usuário ou e-mail este fator de autenticação está vinculado:

curl -XPOST "https://api.authy.com/protected/json/users/<AUTHYID>/secret" \
-H "X-Authy-API-Key: <your Authy API Key here>" \
-d label="Kelley - krobinson@twilio.com"

Isso retornará o seguinte JSON:

{
  "issuer": "Authy and Google Authenticator",
  "label": "Kelley - krobinson@twilio.com",
  "qr_code": "https://s3.amazonaws.com/qr-codes-xxxxxxxxxxxxx/yyyyyyyyyyyyyy.png",
  "success": true
}

As chaves secretas codificadas nos códigos QR são válidas por 24 horas. Depois disso, elas expirarão e será necessário gerar um novo código QR. Mostre o código QR no link para o usuário final para ler com o app da escolha dele. Veja como isso aparece no Google Authenticator depois que eu digitalizo o código QR:

Token adicionado ao Google Authenticator

Antes de marcar um usuário como "2FA ativado", certifique-se de que ele conclua pelo menos uma verificação com êxito com a nova configuração do app autenticador.

Como verificar um código TOTP com a API Authy

Use o seguinte comando, substituindo o TOKEN e AUTHY_ID pelos valores apropriados.

curl -i "https://api.authy.com/protected/json/verify/{TOKEN}/{AUTHY_ID}" \
   -H "X-Authy-API-Key: <your Authy API Key here>"

A execução deste comando com um token de autenticador genérico, como um do Google ou Microsoft Authenticator, retornará o seguinte:

{
  "message": "Token is valid.",
  "token": "is valid",
  "success": "true",
  "device": {
    "id": null,
    "os_type": "generic",
    "registration_date": 1597437548,
    "registration_method": null,
    "registration_country": null,
    "registration_region": null,
    "registration_city": null,
    "country": null,
    "region": null,
    "city": null,
    "ip": null,
    "last_account_recovery_at": null,
    "last_sync_date": null
  }
}

Há muitos dados null, porque não sabemos nada sobre o dispositivo que o usuário tem. Como alternativa, se o usuário usar um token do app Authy, a resposta da API incluirá informações adicionais disponíveis sobre o dispositivo.

As bibliotecas de ajuda do Authy para Python, Ruby, PHP, Node.js e Java também tem suporte para essa chamada de API. Saiba mais na documentação para Senhas de uso único do Authy.

O que vem a seguir?

Parabéns por inscrever seus usuários na 2FA! Para ter mais flexibilidade, confira os documentos da API para enviar senhas de uso único por SMS, voz ou até mesmo e-mail. A beleza da API Authy está no método independente usado para enviar o token, é possível verificar os tokens com a mesma API.

Precisa de ajuda para habilitar a 2FA para seus usuários? Escrevi sobre como incentivar a 2FA. Se quiser saber mais, confira meus canais de apresentação sobre 2FA e as vantagens e desvantagens do BSides San Francisco de 2020.

Tem dúvidas sobre como começar a usar a 2FA? Encontre-me no Twitter em @luisleao. Estamos ansiosos para ver o que você vai criar.

Este artigo foi traduzido do original "How to use the Authy API with Google Authenticator (or any compatible

authenticator app)". Enquanto melhoramos nossos processos de tradução, adoraríamos receber seus comentários em help@twilio.com - contribuições valiosas podem render brindes da Twilio.

Publicações relacionadas

Recursos relacionados

Twilio Docs

De APIs a SDKs e aplicativos de amostra

Documentação de referência de API, SDKs, bibliotecas auxiliares, guias de início rápido e tutoriais para sua linguagem e plataforma.

Centro de Recursos

Os mais recentes e-books, relatórios do setor e webinars

Aprenda com especialistas em engajamento do cliente para melhorar sua própria comunicação.

Ahoy

Centro da comunidade de desenvolvedores da Twilio

Melhores práticas, exemplos de código e inspiração para criar comunicações e experiências de engajamento digital.