Chaves públicas e secretas: mantendo os dados de verificação fora do alcance do cliente.

Toden oferece dois tipos de API chave, e a regra para usá-las é curta: a chave publicável (pk_) vai na sua página web ou aplicativo móvel, e a chave secreta (sk_A chave pública nunca sai do seu servidor. Uma chave pública pode iniciar uma verificação e ler um status mínimo. Ela não pode ler um nome, uma data de nascimento, um número de identificação ou uma selfie. Uma chave secreta pode ler tudo isso.

Para restringir o acesso a uma chave vazada, você tem três opções: uma lista de permissões para a chave (origens da web para uma chave pública, endereços IP ou intervalos para uma chave secreta), chaves por serviço para que uma revogação não derrube tudo e revogação imediata. O restante deste artigo explica por que a divisão funciona dessa maneira e como usar essas opções antes que você precise delas.

Por que uma verificação API Precisa de dois tipos de chave?

Porque qualquer chave que você insira em um cliente eventualmente será lida por alguém que você não pretendia. Um aplicativo móvel pode ser descompilado. Um pacote web pode ser aberto em ferramentas de desenvolvedor. Tratar uma chave de cliente como secreta é uma esperança, não um controle.

Assim, o projeto pressupõe vazamento da chave do cliente e limita suas ações. A tabela abaixo foi extraída da documentação de autenticação (abre num novo separador) .

Uma chave é o seu prefixo seguido por 32 caracteres alfanuméricos aleatórios, por exemplopk_test_aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xYO prefixo indica rapidamente ao revisor humano qual escopo e ambiente ele está analisando, o que é útil quando uma chave aparece em um log ou em uma solicitação de pull request.

O que alguém pode fazer com uma chave publicável vazada?

Eles podem iniciar verificações em sua conta e consultar o status mínimo. Eles não podem ler o resultado de nenhuma verificação, sua ou deles, porque o endpoint de resultado completo rejeita uma chave publicável com403 secret_key_required.

Esse é um limite significativo, mas não é zero. Em Produção, cada verificação concluída é debitada do seu saldo de crédito, conforme estabelecido na documentação do ambiente (abre num novo separador) . Uma chave publicável copiada para outro site pode ser usada para executar verificações pelas quais você paga. É esse risco que a lista de permissões de origem abaixo visa reduzir.

O que alguém pode fazer com uma chave secreta vazada?

Leia os dados de identidade. Uma chave secreta pode fazer a chamada.GET /api/kyc/verifications/:idpara o resultado completo (dados biográficos, número de identificação em texto simples, correspondência facial) eGET /api/kyc/verifications/:id/media/:kindPara selfies, imagens de documentos e vídeos de visualização capturados. Também pode acessar qualquer endpoint do Risk Intelligence.

Trate uma chave secreta como uma senha de banco de dados. Um vazamento de dados é um incidente de exposição de dados para sua organização, e seus próprios processos de resposta a incidentes e obrigações legais se aplicam. Estes variam de acordo com a jurisdição, e este artigo fornece informações gerais, não constituindo aconselhamento jurídico.

Em uma integração típica, onde cada chave deve ser posicionada?

Aqui está um formato comum para um aplicativo que integra clientes:

1. O aplicativo monta o Toden SDK com uma chave publicável . O requerente preenche o formulário de consentimento, captura e verificação de atividade, e o SDK submete a verificação.

2. O aplicativo exibe uma tela "Estamos verificando seus dados". Se precisar mostrar o progresso, ele consulta o status mínimo com a chave publicável.

3. Seu servidor recebe o webhook assinado para verificação.

4. Seu sistema de backend acessa o resultado completo com uma chave secreta , atualiza o registro do cliente e decide o que o aplicativo exibirá em seguida.

Os dados de identidade do solicitante são transferidos do dispositivo para Toden e de Toden para o seu servidor. Ele nunca precisa retornar ao dispositivo e, com esse layout, isso não é possível, pois a única chave no dispositivo não tem permissão para buscá-lo.

Um erro comum é pular a etapa 4 chamando o endpoint de resultado do aplicativo "apenas para a tela de sucesso". Isso exige uma chave secreta no dispositivo, o que compromete todo o projeto. Em vez disso, envie ao aplicativo as poucas informações necessárias a partir do seu próprio backend.

Como os ambientes interagem com as chaves?

Cada chave pertence a um ambiente específico, e os dados nunca são transferidos entre eles.pk_test_trabalhos principais contra Sandbox e umpk_live_A chave é vinculada ao ambiente de produção. Chaves, verificações, endpoints de webhook e configurações são todos restritos a um único ambiente.

Usar uma tecla no lugar errado retorna403 environment_mismatchA regra prática da documentação é manter um único ambiente durante todo o fluxo: o SDK O suporte Sandbox usa umpk_test_chave, e o backend que lê esses resultados usa umsk_test_chave.

As chaves de produção também dependem do perfil da sua empresa. Até que a verificação comercial da sua organização ( KYB ) é aprovado, a verificação de produção e as solicitações de upload são rejeitadas combusiness_not_approvedO modo Sandbox funciona em todas as situações.

Como restringir uma chave antes que ela vaze?

No painel de controle, em Desenvolvedores → API Chaves : cada chave pode conter uma lista de permissões. O tipo da lista de permissões segue o escopo da chave, pois é nesse escopo que cada controle opera.

Dessa tabela decorrem dois pontos.

Primeiramente, uma lista de permissões de origem é um controle do navegador. Ela é útil para integrações web, mas não tem efeito em um aplicativo móvel, pois um aplicativo nativo não envia nenhuma solicitação de origem.OriginPara dispositivos móveis, o limite para uma chave publicável vazada é o seu escopo, não a lista de permissões.

Em segundo lugar, uma lista de permissões de IP é o controle mais rigoroso que você tem sobre uma chave secreta e é barata se o seu backend tiver endereços de saída fixos. Liste os IPs de saída públicos dos seus servidores. Se o seu backend estiver rodando em uma infraestrutura sem saída fixa, é importante saber disso antes de escolher onde a chave secreta será armazenada.

Uma lista de permissões vazia significa que a chave funciona em qualquer lugar. Deixá-la vazia é uma escolha, portanto, faça-a deliberadamente.

O que você deve fazer quando uma chave vaza?

Siga esta ordem:

1. Revogar a chave em Desenvolvedores → API Chaves . A revogação é imediata: a próxima solicitação com essa chave retorna401.

2. Crie a substituição com o mesmo escopo e ambiente e implemente-a. Para uma chave publicável em um aplicativo móvel, isso significa uma nova versão do aplicativo, portanto, a diferença entre as etapas 1 e 2 é real. Planeje-se para isso.

3. Verifique seu histórico de auditoria. A criação e revogação de chaves emitem oapi_key.createdeapi_key.revokedwebhooks, para que suas ferramentas de segurança possam registrar quem alterou o quê e quando.

4. Para uma chave secreta, avalie a exposição. Estabeleça o alcance da chave e por quanto tempo, e siga seu próprio protocolo de resposta a incidentes.

Se a chave não tiver sido realmente vazada e você estiver fazendo rotações programadas, inverta os passos 1 e 2: primeiro crie e implemente a nova chave, confirme se o tráfego foi redirecionado e, em seguida, revogue a chave antiga. Revogar a chave antiga primeiro interromperia todas as requisições intermediárias.

Quais hábitos mantêm o raio da explosão pequeno?

• Uma chave por serviço ou ambiente. Se o seu serviço de integração e o seu trabalho de geração de relatórios compartilham uma chave secreta, revogá-la desativará ambos. Chaves separadas permitem revogar apenas uma delas.

• Armazene as chaves secretas em um gerenciador de segredos no momento da criação. Uma chave secreta é exibida apenas uma vez. Depois disso, o painel mostra apenas o prefixo, portanto, não há nada para copiar posteriormente.

• Mantenha as chaves fora dos repositórios. Uma chave enviada para um repositório público deve ser tratada como vazada, mesmo que o commit seja removido.

• Usar_test_Chaves no desenvolvimento e CI. Reserve_live_Chaves para tráfego de produção.

• Limitar quem pode gerenciar chaves. A criação ou revogação de uma chave requer aapi_keys:createPermissão. Membros sem ela visualizam as chaves como somente leitura.

A regra a aplicar

Ao analisar uma integração, faça a seguinte pergunta para cada local onde uma chave aparece: a pessoa que possui este dispositivo ou que está lendo este pacote poderia usar esta chave para ler dados de identidade? Se a resposta for sim, em qualquer lugar fora dos seus servidores, o projeto está errado, independentemente de qualquer outra coisa que esteja certa nele.

Em seguida, verifique três coisas: a chave publicável na web possui uma lista de permissões de origem, cada chave secreta possui uma lista de permissões de IP onde sua infraestrutura permite o acesso e sua equipe praticou os procedimentos de revogação e substituição. A documentação do desenvolvedor abrange os endpoints que cada chave alcança e a página de segurança explica como. Toden processa os dados internamente.