---
url: 'https://www.corbado.com/pt/blog/passkeys-cheat-sheet'
title: 'Guia de consulta rápida de chaves de acesso para desenvolvedores'
description: 'O guia para desenvolvedores sobre WebAuthn e implementação de chaves de acesso. Baixe a folha de referências em PDF ou use este site para ter todas as informações em um só lugar.'
lang: 'pt'
author: 'Lukas R.'
date: '2026-07-03T07:12:29.339Z'
lastModified: '2026-07-03T07:12:55.083Z'
keywords: 'folha de referências, cheat sheet, chaves de acesso, webauthn, guia para desenvolvedores'
category: 'Passkeys Implementation'
---
# Guia de consulta rápida de chaves de acesso para desenvolvedores
## Baixe aqui gratuitamente
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](https://www.corbado.com/passkeys-for-energy) e Stanford CS
- ✅ Sem jargões de marketing - apenas insights técnicos
## Key Facts
- A autenticação com chaves de acesso usa duas **cerimônias**: registro (attestation) e login (assertion), cada uma exigindo um desafio aleatório gerado pelo servidor e assinado pelo autenticador.
- **PublicKeyCredentialCreationOptions** governa o registro de chaves de acesso, enquanto **PublicKeyCredentialRequestOptions** governa o login. Ambos os objetos são gerados no lado do servidor e contêm o desafio para o autenticador assinar.
- A **Conditional UI** exibe as chaves de acesso disponíveis como sugestões de preenchimento automático, mas requer credenciais detectáveis (resident keys) e não é suportada em todas as combinações de SO e navegador.
- O **Relying Party ID (rpID)** vincula uma chave de acesso a um domínio: a autenticação só é bem-sucedida quando a URL corresponde ou é um subdomínio que não faz parte da lista de sufixos públicos do rpID.
- As chaves de acesso usam **algoritmos COSE** para geração de chaves, com o algoritmo específico registrado no atributo parsedCredentialPublicKey do objeto attestation.
## 1. Cerimônias do WebAuthn
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.
### 1.1 Registro (Attestation)
_A cerimônia de registro usa dois objetos centrais: PublicKeyCredentialCreationOptions e attestation._
[Watch on YouTube](https://www.youtube.com/watch?v=0hRYXHESA24)
### 1.2 Login (Assertion)
_A cerimônia de login usa dois objetos centrais: PublicKeyCredentialRequestOptions e assertion._
## 2. Objetos importantes
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.
### 2.1 Public Key Credential Creation Options
PublicKeyCredentialCreationOptions é o objeto central da fase de atestado (Registro). Ele é criado e retornado pelo [servidor WebAuthn](#webauthn-server).
```json
{
"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).](#relying-party-id)
- **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.](#database-schema)
- **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](#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
### 2.2 Public Key Credential Request Options
PublicKeyCredentialRequestOptions é o objeto central da fase de asserção (Login). Ele é criado e retornado pelo [servidor WebAuthn](#webauthn-server).
```json
{
"publicKeyCredentialRequestOptions": {
"challenge": "pT7HMA-…dFPHk",
"timeout": 500,
"rpId": "passkeys.eu",
"userVerification": "preferred",
"allowCredentials": [],
"extensions": []
}
}
```
O objeto contém estes atributos:
- **challenge, timeout, extensions:** veja [acima](#creationoptions).
- **rpId:** O identificador do Relying Party para a solicitação de asserção, consulte a seção [4.2 Relying Party ID (rpID).](#relying-party-id)
- **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.
### 2.3 Attestation
Durante a Cerimônia de **Atestado** / Registro, o Autenticador retorna esta **Resposta de Registro**. Você pode testar isso por si mesmo no [Passkeys Debugger](https://www.passkeys-debugger.io/).
```json
{
"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](#attestationObject), [algorithm](#algorithm) e as flags de [transport](#transport).
#### 2.3.1 attestationObject
Retirado da [especificação Webauthn da W3C](https://www.w3.org/TR/webauthn-2/#attestation-object)
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](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions).
#### algorithm
As chaves de acesso são geradas com **algoritmos COSE**, indicando o algoritmo usado no **atributo algorithm** de parsedCredentialPublicKey no [objeto de atestado](#attestation).
Aqui está uma visão geral dos algoritmos COSE mais relevantes:
#### 2.3.2 transport
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.
### 2.4 Assertion
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](https://www.passkeys-debugger.io/).
```json
{
"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.
#### 2.4.1 flags
Aqui está uma visão geral das **flags** mais relevantes e suas combinações:
#### 2.4.2 signature
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.
#### 2.4.3 userHandle
O **userHandle** é o user_id real. Leia mais sobre o user_id na seção [**4.1 Esquema de banco de dados.**](#database-schema)
### 2.5 authenticatorSelection
O objeto **authenticatorSelection** permite que o servidor dite as configurações para o autenticador e a criação de credenciais com os seguintes valores:
#### 2.5.1 authenticatorAttachment
- **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.
#### 2.5.2 residentKey
- **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).
> **Resident Keys (também chamadas de Discoverable Credential):** As chaves residentes são armazenadas no autenticador e recuperadas durante a autenticação. Dessa forma, o cliente pode descobrir uma lista de chaves possíveis, e é por isso que a \[Conditional UI]\(/blog/user-transition-passkeys-> conditional-ui) exige chaves residentes.
> **Non-Resident Keys (também chamadas de Non-Discoverable Credential):** No caso de chaves não residentes, a credencial ID é armazenada no servidor e fornecida durante a autenticação. A credencial ID é um [identificador opaco](https://www.w3.org/TR/webauthn-3/#sctn-credential-id) cuja estrutura interna é específica da implementação — os autenticadores podem armazenar chaves privadas diretamente, usar agrupamento de chaves criptografado (key wrapping) ou derivar chaves de segredos internos. O mecanismo exato varia de acordo com a implementação do autenticador.
#### 2.5.3 userVerification
- **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.
> **Aviso:** Se for definido como "**Preferred",** o usuário ou seu dispositivo pode ignorar a verificação do usuário no processo de autenticação (leia mais neste [artigo](https://web.dev/articles/passkey-form-autofill)).
## 3. Conditional UI
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.
### 3.1 Fluxo de login com Conditional UI
_Como um login normal, a Conditional UI também usa os objetos PublicKeyCredentialRequestOptions e assertion._
### 3.2 Compatibilidade de dispositivos
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.](https://caniuse.com/mdn-api_publickeycredential_isconditionalmediationavailable_static)
### 3.3 Exemplos de código
#### 3.3.1 Método da Conditional UI
Um código completo e minimalista para um método de Conditional UI é o seguinte:
```html
Conditional UI
```
#### 3.3.2 Verificação de compatibilidade do navegador
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](#device-compatibility)).
- 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).
```javascript
// 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",
});
/*
...
*/
}
}
```
#### 3.3.3 Token de preenchimento automático em campos de entrada
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.
```html
```
## 4. Servidor WebAuthn
### 4.1 Esquema de banco de dados
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._
#### 4.1.1 Dados relevantes de autenticação
- **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).
#### 4.1.2 Metadados para exibição e seleção de chaves de acesso:
- **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.
### 4.2 Relying Party ID (rpId)
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):
## 5. Sites e ferramentas úteis
Aqui está uma lista de ferramentas e sites úteis para a implementação de chaves de acesso.
- [**Passkeys Debugger:**](https://www.passkeys-debugger.io/) 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:**](https://www.w3.org/TR/webauthn-2/) Esta é a especificação oficial do WebAuthn.
- [**Chrome Device Log:**](http://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](https://docs.corbado.com/start) (para novos aplicativos) ou o [Corbado Connect](https://www.corbado.com/enterprise) (para aplicativos existentes).
## Perguntas frequentes
### Como faço para implementar a Conditional UI para o preenchimento automático de chaves de acesso no meu aplicativo web?
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.
### Quais são os dados mínimos que preciso armazenar em meu banco de dados para suportar a autenticação WebAuthn?
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.
### Qual é a diferença entre as chaves residentes (resident keys) e as não residentes no WebAuthn?
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".
### Como o userVerification funciona e quais são os riscos de defini-lo como preferred?
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.