Login com certificado

Autenticar o usuário pela posse da chave do e-CPF ou e-CNPJ, sem senha.

O login por certificado prova que a pessoa tem a chave privada de um certificado (e-CPF ou e-CNPJ, em token, arquivo ou nuvem), sem senha. A API emite um desafio de uso único que o usuário assina com a chave; você confere o resultado e vincula o CPF ou CNPJ do certificado a um usuário do seu sistema.

O fluxo#

São duas chamadas do seu servidor e uma assinatura no navegador:

Navegador                          Seu servidor (chave de API)                     API
  GET /login/desafio  ───────────▶ startCertificateAuthentication ─────────────▶ POST /v1/certificate-authentications
                      ◀─────────── { token, dataToSign, digestAlgorithm }
  cert = signer.certificate()
  sig  = signer.sign(dataToSign, digestAlgorithm)       ← use o `digestAlgorithm` devolvido; com token A3 a extensão pede o PIN
  POST /login/concluir { token, cert, sig } ─▶ completeCertificateAuthentication ▶ POST /v1/certificate-authentications/{token}/complete
                      ◀─────────── { authenticated, certificate { pkiBrazil } }

$ch = $api->startCertificateAuthentication('icp-brasil', 'https://app.suaempresa.com.br');
// $ch['token'] e $ch['dataToSign'] (base64) vão ao navegador, que assina dataToSign

$r = $api->completeCertificateAuthentication($token, $certDerBase64, $signatureBase64);
if ($r['authenticated'] === true) {
    // agora VOCÊ decide quem é: compare com o seu cadastro
    $cpf = $r['certificate']['pkiBrazil']['cpf'];            // e-CPF
    // e-CNPJ: $r['certificate']['pkiBrazil']['cnpj'] e ['responsibleCpf']
}

O segundo argumento é a origem exata do seu site de login (esquema, domínio e porta, sem barra no fim).

Regras de segurança#

1. O desafio é consumido por qualquer tentativa, certa ou errada. Para tentar de novo, peça outro.
2. O desafio vale 5 minutos.
3. A API monta a mensagem a assinar: ela inclui o seu cliente, o contexto, a origem do seu site e um valor aleatório. O navegador não escolhe o que assina, a mesma assinatura não vale em outro desafio, e a extensão recusa assinar se o site que pede não for a origem embutida. Um site de phishing não consegue repassar o seu desafio.
4. authenticated: true é prova de posse da chave, não de identidade no seu sistema. Faça o vínculo CPF/CNPJ → usuário no seu servidor.
5. A revogação é exigida por padrão (checkRevocation = true): na ICP-Brasil a API consulta LCR e OCSP; em PKI privada usa as LCRs enviadas; e falha fechado se não conseguir. Passe checkRevocation: false só em ambientes sem fonte de revogação, e nunca em produção com certificados reais.
6. Chaves EC de até 256 bits (P-256) não são aceitas (422 certificate_key_not_supported): o login é assinado com SHA-384, e o ECDSA P-256 truncaria o resumo, o que permitiria repassar o login a outro site. RSA e EC P-384 ou maior funcionam.

Cobrança#

Cada login concluído é registrado como uma transação certificate_authentication, com preço definido no seu plano.

Em JavaScript (Node)#

const r = await client.authenticateWithCertificate({
  signer, origin: "https://app.suaempresa.com.br", securityContextId: "icp-brasil",
});

Veja a Referência da API para o contrato completo.