Guia de consulta rápida de chaves de acesso para desenvolvedores

Baixe o Guia de consulta rápida de chaves de acesso gratuitamente e obtenha todos os insights.

• ✅ Mais de 4.000 downloads já realizados
• ✅ Solicitado por equipes de desenvolvimento da Ally, Kmart, Octopus Energy e Stanford CS
• ✅ Sem jargões de marketing - apenas insights técnicos

O guia definitivo de chaves de acesso para desenvolvedores

Baixe o Guia de consulta rápida de chaves de acesso

Obtenha uma referência focada no desenvolvedor para tudo sobre chaves de acesso, cobrindo suporte de plataforma, comportamento do navegador, melhores práticas de UX e dicas de integração.

Baixe o Guia de consulta rápida gratuito de chaves de acesso

E-mail profissional *

Nome *

Empresa *

Cargo *

Baixar gratuitamente

A autenticação com chaves de acesso é baseada em dois processos, também chamados de cerimônias: registro (também conhecido como fase de atestado) e login (também conhecido como fase de asserção).
Cada fase requer um desafio aleatório gerado pelo servidor, que é assinado pelo autenticador e enviado de volta ao servidor WebAuthn para verificar o usuário.

Experimente fluxos de passkeys no Passkeys Debugger.

Testar grátis

A cerimônia de registro usa dois objetos centrais: PublicKeyCredentialCreationOptions e attestation.

A cerimônia de login usa dois objetos centrais: PublicKeyCredentialRequestOptions e assertion.

Veja quantas pessoas realmente usam passkeys.

Ver dados de adoção

Para o registro e login com chaves de acesso, existem quatro objetos principais:

• PublicKeyCredentialCreationOptions
• PublicKeyCredentialRequestOptions
• attestation
• assertion

Esta seção também explica o objeto authenticatorSelection, que é usado em PublicKeyCredentialCreationOptions.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

PublicKeyCredentialCreationOptions é o objeto central da fase de atestado (Registro). Ele é criado e retornado pelo servidor WebAuthn.

{
    "PublicKeyCredentialCreationOptions": {
        "rp": {
            "id": "passkeys.eu",
            "name": "Corbado Passkeys Demo"
        },
        "user": {
            "displayName": "john.doe",
            "id": "dXNyLZ….DU10Tc",
            "name": "john@doe.com"
        },
        "challenge": "888fix4Bus...pHHr3Y",
        "pubKeyCredParams": [
            {
                "alg": -7,
                "type": "public-key"
            },
            {
                "alg": -257,
                "type": "public-key"
            }
        ],
        "excludeCredentials": [],
        "authenticatorSelection": {
            "authenticatorAttachment": "platform",
            "residentKey": "required",
            "userVerification": "required"
        },
        "attestation": "none",
        "extensions": {}
    }
}

O objeto contém estes atributos:

• rp: Identifica o Relying Party (= o servidor que procura autenticar o usuário), consulte a seção 4.2 Relying Party ID (rpID).
• user: Contém dados sobre a conta de usuário que solicita o atestado. O ID é uma sequência de bytes escolhida pelo Relying Party, que não deve conter informações pessoais. O nome de usuário ou endereço de e-mail é salvo em vez disso no atributo name ou displayName. Leia mais sobre isso na seção 4.1 Esquema de banco de dados.
• challenge: Um BufferSource gerado aleatoriamente e codificado em base64URL que precisa ser assinado pelo autenticador.
• pubKeyCredParams: Atributos especificados da credencial a ser criada, geralmente o(s) algoritmo(s) suportado(s).
• timeout: Tempo opcional em milissegundos para o cliente aguardar a conclusão da chamada.
• excludeCredentials: Lista opcional de credenciais para limitar a criação de várias chaves de acesso em um dispositivo.
• authenticatorSelection: Seleção opcional do autenticador usado para o método, por exemplo, se um residentKey é necessário. Consulte 2.5 authenticatorSelection.
• attestation: Pode ser usado para solicitar que o objeto de atestado seja passado para o Relying Party em uma forma específica. Os valores possíveis são none (padrão), indirect, direct e enterprise.
• extensions: Solicitação(ões) opcional(is) para processamento adicional, como valores de retorno específicos. Por exemplo:
  • credProbs solicita informações sobre se a credencial criada é detectável
  • prf permite que o Relying Party use saídas de uma função pseudoaleatória (PRF) associada a uma credencial

Assine nosso Substack de passkeys para receber as últimas novidades.

Assinar

PublicKeyCredentialRequestOptions é o objeto central da fase de asserção (Login). Ele é criado e retornado pelo servidor WebAuthn.

{
    "publicKeyCredentialRequestOptions": {
        "challenge": "pT7HMA-…dFPHk",
        "timeout": 500,
        "rpId": "passkeys.eu",
        "userVerification": "preferred",
        "allowCredentials": [],
        "extensions": []
    }
}

O objeto contém estes atributos:

• challenge, timeout, extensions: veja acima.
• rpId: O identificador do Relying Party para a solicitação de asserção, consulte a seção 4.2 Relying Party ID (rpID).
• allowCredentials: Lista opcional de credenciais que são permitidas para autenticação, indicando a preferência dos chamadores em ordem decrescente. Esta lista seria preenchida com PublicKeyCredentialDescriptors.
• userVerification: Valor opcional para especificar os requisitos de verificação do usuário durante a operação. Os valores possíveis são preferred (padrão), required ou discouraged.

Durante a Cerimônia de Atestado / Registro, o Autenticador retorna esta Resposta de Registro. Você pode testar isso por si mesmo no Passkeys Debugger.

{
    "authenticatorAttachment": "platform",
    "id": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "rawId": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "response": {
        "attestationObject": {
            "fmt": "none",
            "attStmt": {},
            "authData": {
                "rpIdHash": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkM",
                "flags": {
                    "userPresent": true,
                    "userVerified": true,
                    "backupEligible": true,
                    "backupStatus": true,
                    "attestedData": true,
                    "extensionData": false
                },
                "counter": 0,
                "aaguid": {
                    "raw": "fbfc3007-154e-4ecc-8c0b-6e020557d7bd",
                    "name": "iCloud Keychain"
                },
                "credentialID": "JKZbixUfKN_aZtimefYT-OjH5dw",
                "credentialPublicKey": "pQECAyYgASFYIPWLalDzyxIDmAADvfK8iNM5To50kh7TyPH-teEz8RMdIlgg3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA",
                "parsedCredentialPublicKey": {
                    "keyType": "EC2 (2)",
                    "algorithm": "ES256 (-7)",
                    "curve": 1,
                    "x": "9YtqUPPLEgOYAAO98ryI0zlOjnSSHtPI8f614TPxEx0",
                    "y": "3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA"
                }
            }
        },
        "clientDataJSON": {
            "type": "webauthn.create",
            "challenge": "k2p6f-upzP_hc6NZvmMAxiI0VSTeQIeXXVRGW62LTj0",
            "origin": "https://www.passkeys-debugger.io",
            "crossOrigin": false
        },
        "transports": ["hybrid", "internal"],
        "authenticatorData": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkNdAAAAAPv8MAcVTk7MjAtuAgVX170AFCSmW4sVHyjf2mbYpnn2E_jox-XcpQECAyYgASFYIPWLalDzyxIDmAADvfK8iNM5To50kh7TyPH-teEz8RMdIlgg3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA",
        "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9YtqUPPLEgOYAAO98ryI0zlOjnSSHtPI8f614TPxEx3cPts8hZAnzP5YWffN1hnMnD1zuaE92Z-VCoP29Xt58A",
        "publicKeyAlgorithm": -7
    },
    "type": "public-key",
    "clientExtensionResults": {}
}

O attestation contém alguns componentes importantes como attestationObject, algorithm e as flags de transport.

Retirado da especificação Webauthn da W3C

O attestationObject é um objeto codificado em CBOR, contendo informações sobre as credenciais recém-criadas, a chave pública e outros dados relevantes:

• fmt é normalmente avaliado como "none" para chaves de acesso
• attStmt fica vazio para chaves de acesso e é preenchido para outros autenticadores, por exemplo, chave de segurança de hardware
• authData é um buffer de valores contendo os seguintes dados:

Leia mais sobre as extensões.

As chaves de acesso são geradas com algoritmos COSE, indicando o algoritmo usado no atributo algorithm de parsedCredentialPublicKey no objeto de atestado.
Aqui está uma visão geral dos algoritmos COSE mais relevantes:

A propriedade transports indica os mecanismos através dos quais um autenticador pode se comunicar com um cliente. Algumas combinações de valores de exemplo comuns são:

• "transports": ["internal","hybrid"]: As chaves de acesso podem ser usadas a partir do autenticador da plataforma (por exemplo, Face ID, Touch ID, Windows Hello) ou via autenticação entre dispositivos (usando código QR e Bluetooth).
• "transports": ["internal"]: As chaves de acesso só podem ser usadas a partir do autenticador da plataforma (por exemplo, Face ID, Touch ID, Windows Hello).
• Nenhuma propriedade "transports" definida: comportamento padrão que não fornece indicações.

Durante a Cerimônia de Asserção / Login, o Autenticador retorna esta Resposta de Login. Você pode testar isso por si mesmo no Passkeys Debugger.

{
    "id": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "rawId": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
        "authenticatorData": {
            "rpIdHash": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkM",
            "flags": {
                "userPresent": true,
                "userVerified": true,
                "backupEligible": true,
                "backupStatus": true,
                "attestedData": false,
                "extensionData": false
            },
            "counter": 0
        },
        "clientDataJSON": {
            "type": "webauthn.get",
            "challenge": "GCVkITWbe2l2dttsn_DgJYvH9QPHPDo0ygWgcgI6B7U",
            "origin": "https://www.passkeys-debugger.io",
            "crossOrigin": false,
            "other_keys_can_be_added_here": "do not compare clientDataJSON against a template. See https://goo.gl/yabPex"
        },
        "signature": "MEQCIA-orC8N2KKWOxyY17BWP8lB-Be5to9btXRnJZf2SLhXAiBGxJe5Eu5LwOTbsyzAYmIXHOhlC3pN7s7Q1fRLvEW57g",
        "userHandle": "_FKz1uwqmR_3yGq6hJntzoIFwFC_d1u_53YRELh0KlE"
    }
}

A assertion contém alguns componentes importantes como flags, signature e userHandle.

Aqui está uma visão geral das flags mais relevantes e suas combinações:

A signature é usada para verificar se o usuário que está tentando fazer login possui a chave privada. A assinatura é criada concatenando o authenticatorData e o clientDataHash (ou seja, a versão SHA-256 de ClientDataJSON) e assinando o resultado com a chave privada (no autenticador). Para verificar com a chave pública, também concatenamos o authenticatorData e o clientDataHash. Se o resultado da verificação retornar verdadeiro, a autenticação será bem-sucedida.

O userHandle é o user_id real. Leia mais sobre o user_id na seção 4.1 Esquema de banco de dados.

O objeto authenticatorSelection permite que o servidor dite as configurações para o autenticador e a criação de credenciais com os seguintes valores:

• Platform: O autenticador está anexado à plataforma do cliente e, portanto, não é removível.
• Cross-platform: O autenticador não está vinculado à plataforma do cliente e pode ser usado em vários dispositivos.

• Required: O autenticador deve criar uma resident key (se não for possível, a operação deve falhar).
• Preferred: O autenticador deve tentar criar uma resident key (se não for possível, deve criar uma non-resident key).
• Discouraged: O autenticador deve criar uma non-resident key (se não for possível, a operação deve falhar).

• Required: A operação deve verificar o usuário.
• Preferred: A operação deve verificar o usuário, mas pode prosseguir sem ela (opção padrão).
• Discouraged: A operação não deve verificar o usuário.

A Conditional UI (preenchimento automático de chave de acesso) exibe as chaves de acesso disponíveis em uma lista suspensa de seleção para o usuário, quando um usuário possui uma chave residente registrada no Relying Party. Ela melhora a usabilidade das chaves de acesso, mas exige esforços adicionais de desenvolvimento e não está disponível para todas as combinações de SO/navegador.

Como um login normal, a Conditional UI também usa os objetos PublicKeyCredentialRequestOptions e assertion.

A Conditional UI não está disponível em todas as combinações de sistemas operacionais e navegadores (ainda). Aqui está uma visão geral da cobertura atual do navegador (março de 2024):

Para obter uma visão geral atualizada, acesse este site.

Um código completo e minimalista para um método de Conditional UI é o seguinte:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Conditional UI</title>
    </head>
    <body>
        <input type="text" id="username" autocomplete="username webauthn" />
 
        <script>
            async function passkeyLogin() {
                try {
                    // recupera as request options (incl. o challenge) do servidor WebAuthn
                    let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
                    const credential = await navigator.credentials.get({
                        publicKey: options.publicKeyCredentialRequestOptions,
                        mediation: "conditional",
                    });
 
                    const userData = await WebAuthnClient.sendSignedChallenge(credential);
                    window.location.href = "/logged-in";
                } catch (error) {
                    console.log(error);
                }
            }
 
            passkeyLogin();
        </script>
    </body>
</html>

A Conditional UI funciona apenas com chaves residentes (resident keys) / credenciais detectáveis.
Recomenda-se fornecer um endpoint de servidor diferente para iniciar o login da Conditional UI.
O cliente precisa atender a vários requisitos:

• O navegador precisa oferecer suporte à Conditional UI (consulte 3.2 Compatibilidade de dispositivos).
• O JavaScript deve estar ativado e a página da web deve fornecer um campo de entrada (input) HTML.
• Parâmetros de timeout devem ser desconsiderados.

Para evitar erros, o servidor deve testar primeiro a disponibilidade dos clientes com esta função: No tráfego real, problemas de detecção e ciclo de vida costumam surgir como NotAllowedError ou AbortError. Use o guia de erros de WebAuthn para classificação de erros esperados vs. inesperados, incluindo erros de chaves de acesso nativas no Gerenciador de Credenciais (Credential Manager).

// fonte: https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/isConditionalMediationAvailable#examples
 
// A disponibilidade de `window.PublicKeyCredential` significa que o WebAuthn pode ser usado.
if (window.PublicKeyCredential && PublicKeyCredential.isConditionalMediationAvailable) {
    // Verifica se a mediação condicional está disponível.
    const isCMA = await PublicKeyCredential.isConditionalMediationAvailable();
    if (isCMA) {
        // Chama o endpoint de início de autenticação do WebAuthn
 
        let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
        const credential = await navigator.credentials.get({
            publicKey: options.publicKeyCredentialRequestOptions,
            mediation: "conditional",
        });
        /*
    ...
    */
    }
}

O campo de entrada deve receber um token de preenchimento automático (autofill) HTML, que sinaliza ao cliente para preencher chaves de acesso na solicitação em andamento. Além de chaves de acesso, os tokens de preenchimento automático podem ser combinados com tokens existentes, por exemplo, nomes de usuário e senhas:

• autocomplete="username webauthn": Além de exibir chaves de acesso, também sugere preenchimento automático de nome de usuário.
• autocomplete="current-password webauthn": Além de exibir chaves de acesso, isso solicita preenchimento automático de senha.

<label for="name">Nome de usuário:</label>
<input type="text" name="name" autocomplete="username webauthn" />
<label for="password">Senha:</label>
<input type="password" name="password" autocomplete="current-password webauthn" />

Não há um esquema de banco de dados obrigatório ou padronizado para servidores WebAuthn. No entanto, este exemplo de esquema de banco de dados pode ser usado para armazenar as informações necessárias e fornecer todas as funcionalidades de um servidor WebAuthn:

Os atributos em negrito são obrigatórios para uma implementação viável mínima, enquanto os outros são necessários apenas para recursos opcionais, mas úteis.

• Credential ID: Um ID exclusivo gerado pelo autenticador durante o registro de uma chave de acesso. Ele deve ser usado para procurar a conta de usuário real que está associada à chave de acesso. Além disso, o userHandle (do user_id) deve ser comparado para validar a conta usada para autenticação. Não use o atributo user.name para comparação, pois ele pode mudar com o tempo.
• User ID (user_id): ID exclusivo especificado pelo Relying Party para representar uma conta de usuário em seu sistema. É retornado como o userHandle no objeto de asserção (assertion).

• User DisplayName (user.displayName): Nome amigável e legível que normalmente é o nome completo do usuário. Ele é exibido para o usuário, mas não é usado durante a autenticação.

• User Name (user.name): Nome exclusivo e legível que normalmente é um endereço de e-mail ou um nome de usuário. Ele pode ser exibido para o usuário, mas não é usado durante a autenticação.

O Relying Party ID (rpID) é um domínio armazenado na chave de acesso, garantindo que a chave de acesso só funcione para o domínio correto (URL do navegador; consulte este artigo para aplicativos nativos). Durante a autenticação, o rpID é verificado em relação à URL do navegador e é permitido apenas nestes dois casos:

1. A URL corresponde exatamente ao rpId OU
2. A URL é um subdomínio que corresponde ao rpId e o domínio pai não está na Public Suffix List (Lista de Sufixos Públicos).

Aqui estão exemplos de combinações permitidas (ou não):

Aqui está uma lista de ferramentas e sites úteis para a implementação de chaves de acesso.

• Passkeys Debugger: Ferramenta para depurar as respostas do WebAuthn como JSON e testar as operações do WebAuthn com opções diferentes.
• Passkeys Glossary: Explicação dos termos e conceitos relacionados a chaves de acesso.
• Especificação WebAuthn: Esta é a especificação oficial do WebAuthn.
• Chrome Device Log: Ferramenta para exibir um registro das operações do WebAuthn em seu dispositivo (disponível apenas no Chrome via chrome://device-log).

Para estratégias sobre a otimização de UX de chaves de acesso além da implementação técnica, consulte nossos guias sobre práticas recomendadas de criação de chaves de acesso e práticas recomendadas de login com chaves de acesso.

Se quiser implementar chaves de acesso com apenas algumas linhas de código em qualquer aplicativo, você também pode usar o Corbado Complete (para novos aplicativos) ou o Corbado Connect (para aplicativos existentes).

Sobre a Corbado

Corbado é a Authentication Intelligence Platform para times de CIAM que rodam autenticação consumer em escala. Mostramos o que logs de IDP e ferramentas genéricas de analytics não enxergam: quais dispositivos, versões de SO, navegadores e gerenciadores de credenciais suportam passkeys, por que os registros não viram logins, onde o fluxo WebAuthn falha e quando uma atualização de SO ou navegador quebra silenciosamente o login — tudo sem substituir Okta, Auth0, Ping, Cognito ou seu IDP interno. Dois produtos: Corbado Observe adiciona observabilidade para passkeys e qualquer outro método de login. Corbado Connect entrega passkeys gerenciados com analytics integrado (junto ao seu IDP). VicRoads roda passkeys para mais de 5M de usuários com Corbado (+80% de ativação de passkey). Fale com um especialista em Passkeys →

A Conditional UI requer a verificação do suporte do navegador por meio de PublicKeyCredential.isConditionalMediationAvailable() antes de iniciar a autenticação. O campo de entrada (input) deve incluir o token HTML autocomplete="username webauthn" e o usuário deve ter uma chave residente (resident key / credencial detectável) registrada. Recomenda-se um endpoint de servidor separado para lidar com o fluxo de login da Conditional UI.

No mínimo, armazene a Credential ID, gerada pelo autenticador durante o registro, e o User ID (user_id), que é retornado como o userHandle no objeto de asserção. Use a Credential ID para pesquisar a conta de usuário associada e compare o userHandle para validar a autenticação. Evite usar user.name para comparação, pois ele pode mudar com o tempo.

As chaves residentes (credenciais detectáveis) são armazenadas no próprio autenticador e recuperadas durante a autenticação, o que é necessário para que a Conditional UI funcione. As chaves não residentes armazenam a ID da credencial no servidor e a enviam ao autenticador durante a autenticação. O campo residentKey em authenticatorSelection controla esse comportamento com os valores "required", "preferred" ou "discouraged".

O campo userVerification controla se o autenticador deve verificar o usuário durante o login, aceitando os valores "required", "preferred" (padrão) ou "discouraged". Quando definido como "preferred", o usuário ou seu dispositivo pode ignorar totalmente a verificação durante o processo de autenticação, o que pode enfraquecer a segurança. Defini-lo como "required" garante que a verificação sempre ocorra antes da conclusão da autenticação.