Device possession protocol · Auth21 reference implementation · poap.auth21.cloud

Proof of Ownership Authentication Protocol

POAP Identidade prova quem é · POAP prova quem opera agora com o dispositivo

Spec v0.1 — O POAP é um protocolo da Auth21 em que o utilizador demonstra posse de uma chave criptográfica registada num dispositivo. Não substitui /authorize → code → /token nem login Bridge: é uma camada de posse sobre identidade já estabelecida. Esta página explica como funciona, como se comporta em cada modo Auth21 e que nível de segurança oferece — não é um tutorial para implementar o protocolo do zero noutro produto.

Duas camadas: (1) POAP (conceito) — separar identidade de posse, tiers Master/Base/Temp, recovery lenta; (2) POAP @ Auth21 — API /poap/v1/*, UI em oauth-login, consola poap-manage, Session Center e Trust Center.

POAP (Proof of Ownership Authentication Protocol) é o protocolo Auth21 para posse criptográfica de dispositivo após identidade estabelecida. Identidade prova quem é a conta; POAP prova quem opera agora com o dispositivo registado (Ed25519, challenge-response).

POAP is Auth21's Proof of Ownership Authentication Protocol: cryptographic proof of a registered device key after OAuth, OIDC or Bridge identity — a possession layer, not a replacement for login or SSO.

URL canónica: https://poap.auth21.cloud · Spec JSON: poap-spec-v0.1.json · Contexto LLM: llms.txt

Layer

Posse, não identidade

Email, password, social e Bridge provam conta. POAP prova dispositivo.

Hosted

Ciclo completo

Activar Master, enrollment Base, challenge no login, recovery.

Bridge

Step-up opcional

SSO externo primeiro; POAP pode exigir-se antes do consentimento OAuth.

Tiers

Master · Base · Temp

Hierarquia com cooldown de promoção e kit de recovery one-time.

Policy

opt-in → required

off, audit_only, opt_in, required por tenant.

Audit

poap.* events

Revogação, recovery, verificação — correlacionável com trace_id.

Overview

POAP (Proof of Ownership Authentication Protocol) addresses a gap left by passwords, magic links and social IdPs: even with a valid email, an attacker still needs a registered device key to complete login when POAP is active.

Em português: depois que a Auth21 (ou o cliente Bridge) já sabe quem é o sujeito, o POAP pergunta este pedido foi assinado pelo telemóvel/tablet que o utilizador registou? A resposta é um desafio–resposta Ed25519/P-256 com anti-replay (nonce + sign_count).

O golden path OAuth mantém-se. POAP reforça a identity_session com claims poap_device_id, poap_tier antes de emitir code.

Protocolo vs implementação Auth21

Camada	Âmbito	Exemplo
POAP (conceito)	Regras de posse aplicáveis a qualquer IdP que queira device binding	Um Master por utilizador; recovery com delay; nunca enviar chave privada no QR
POAP @ Auth21	Hosted UI, API v1, consola, audit	`oauth-login`, `poap-devices`, `/poap/v1/verify`
Fora de scope v0.1	Reimplementar POAP noutro stack sem Auth21	Este site não documenta SDK genérico nem bootstrap greenfield

Analogia: OAuth padroniza autorização · Auth21 implementa OAuth. POAP padroniza posse de dispositivo na Auth21 · a implementação de referência está no produto Hosted.

Objectivos

Reduzir impacto de email comprometido ou password vazada quando POAP está activo.
Dar ao utilizador lista e revogação de dispositivos (Session Center + UI hosted).
Oferecer recovery visível e lenta — não bypass silencioso por suporte.
Encaixar em QR handoff, audit (OAuthFlowLog) e Trust Center sem novo modo de identidade.
Permitir step-up em apps Bridge sensíveis sem substituir HMAC do cliente.

O que POAP não é

Não é um quarto identity_mode (Hosted / Bridge / Embed / QR solo continuam iguais).
Não é login social — Google/Apple são IdPs externos; POAP é posse local Auth21.
Não elimina MFA TOTP ou magic link — complementa ou substitui o step de “algo que tens” conforme política.
Não substitui WebAuthn/FIDO2 genérico — pode convergir no futuro; v0.1 usa chaves Ed25519 no dispositivo/browser.
Não protege contra malware no próprio dispositivo Master (keylogger local).

Credenciais (tiers)

Tier	Quantidade	Onde vive a chave privada	Poder típico
master	1 activa	Telemóvel principal / browser de confiança	Activar POAP, enrollment Base, revogar, temporárias, recovery
base	N (limite tenant)	Tablet, segundo telemóvel, desktop	Login e assinatura; não revoga Master
temp	N simultâneas	Kiosk / convidado	Login limitado por TTL e scope; não promove nem emite temp
recovery	1 kit / activação	Papel / cofre	Último recurso; fluxo dedicado com delay (ex.: 24h)

Hierarquia e permissões

Apenas Master revoga outros dispositivos (excepto fluxo recovery). Promoção Base → Master exige cooldown (24h na implementação Auth21) e revoga o Master anterior. Duas Masters activas nunca coexistem sem transição auditada.

Acção	Master	Base	Temp	Recovery
Login POAP	Sim	Sim	Sim (janela)	Não (fluxo à parte)
Enrollment Base (QR)	Sim	Não	Não	Não
Revogar Base	Sim	Não	Não	Não
Promover Base → Master	—	Após cooldown	Não	Não
Reset total POAP	Sim (recovery UI)	Não	Não	Sim (código + delay)

Primitivos criptográficos

Par Ed25519 ou P-256 por dispositivo; servidor guarda só chave pública + device_public_id (32 hex).
Chave privada permanece no dispositivo (Keystore, secure enclave ou localStorage do browser no cliente de referência).
Nunca transportar chave privada ou seed em QR — o QR leva token de enrollment ou payload de challenge assinado pelo servidor.

Desafio–resposta (login)

Servidor cria challenge_id, nonce e mensagem canónica ligada ao pending_id OAuth.
Dispositivo assina com chave privada; envia signature + sign_count incrementado.
Servidor verifica assinatura, anti-replay e estado do dispositivo (não revogado, não expirado se temp).
UI desktop pode mostrar QR ou botão “Assinar neste dispositivo” (poap-client.js).
Após verificação, fluxo OAuth continua (consent → code).

Isto descreve o comportamento do protocolo na Auth21 — não inclui código de integração greenfield.

Modo Hosted — comportamento POAP

É o único modo com ciclo de vida POAP completo: activação Master, enrollment Base por QR, challenge no oauth-login, gestão em poap-devices, política poap_mode na consola.

Utilizador = auth21_hosted_user no tenant.
Após password/social/magic link, se política exigir: step POAP antes de authorize.
Claims poap_* entram na identity_session e podem aparecer em userinfo conforme app.
Default de produto: opt-in — tenant activa poap_mode ≠ off e utilizador activa Master.

Bridge / Enterprise — comportamento POAP

Identidade vem do sistema do cliente (POST HMAC para bridge/callback). POAP não substitui esse login externo.

Flag opcional poap_step_up_bridge na app OAuth: após callback válido, redirect para poap-bridge-stepup.
Utilizador deve ter POAP activo no mesmo tenant hosted ligado à sessão Bridge.
Objetivo: apps sensíveis exigem posse de dispositivo antes do consentimento OAuth, sem mudar o SSO do cliente.

Regra: POAP em Bridge é step-up Auth21, não login primário no domínio do cliente.

Client Embed e QR solo

Client embed — identidade via JWT/backend do cliente; POAP não actua no login embed. Se o tenant tiver utilizadores hosted paralelos, políticas POAP aplicam-se só onde existir sessão hosted + dispositivo registado (cenário híbrido raro).

QR solo / Handoff — foco em handoff móvel rápido; POAP não é o mecanismo principal. QR POAP reutiliza transporte visual (enrollment/login) com contrato JSON distinto (auth21_poap_enrollment vs auth21_poap_login), não o mesmo payload OAuth pending.

Matriz POAP × modo Auth21

Modo	Login POAP primário	Activar Master	Step-up POAP	Notas
Hosted	Sim	Sim	Sim	Referência v0.1
Bridge / Enterprise	Não	Sim*	Sim (flag app)	*Se existir utilizador hosted no tenant
Client embed	Não	N/A	Opcional	Identidade no cliente
QR solo	Não	N/A	Não	Handoff ≠ POAP

Políticas `poap_mode` (tenant)

Valor	Comportamento
`off`	POAP desactivado; fluxo Hosted clássico.
`audit_only`	Infra POAP disponível; eventos auditados; login não obriga challenge.
`opt_in`	Utilizadores podem activar Master; challenge só se `poap_enabled`.
`required`	Utilizadores com POAP activo devem passar challenge; sem dispositivo → bloqueio até activar.

Recomendação operacional: começar em audit_only ou opt_in antes de required em produção.

Fluxos principais (conceito)

Activação

Utilizador autenticado gera par de chaves → regista Master → recebe kit recovery (one-time) → poap_enabled=1.

Login

OAuth pending → credencial (password/social) → challenge POAP → sessão com claims → consent.

Enrollment Base

Master emite QR TTL curto → novo dispositivo completa enrollment → tier Base.

Perda de dispositivo

Base promove com cooldown; ou recovery code com delay 24h revoga tudo e obriga novo Master.

Detalhe de API e erros A21-POAP-*: documentação operacional interna docs/POAP_API.md (clientes Auth21 com POAP já activo).

Níveis de segurança

Nível	Política típica	Garantia	Trade-off
Baseline	`opt_in`, recovery padrão	Password/social + POAP para quem activou	Adopção gradual; utilizadores sem POAP ainda logam
Assurance	`required` para utilizadores POAP	Conta com POAP não loga só com email comprometido	Onboarding exige activar Master cedo
High assurance	`required` + step-up Bridge + TOTP social policy	SSO externo + posse + MFA em apps sensíveis	Mais fricção; suporte precisa Session Center

Comparativo honesto: POAP eleva barreira acima de password/email, mas não atinge hardware FIDO2 certificado nem proteção contra dispositivo já comprometido.

Modelo de ameaças

Cenário	Sem POAP	Com POAP activo
Email comprometido	Magic link / reset possível	Login exige dispositivo ou recovery explícita
Password vazada	Acesso se sessão criada	Password sozinha insuficiente se POAP required
Roubo de telemóvel (desbloqueado)	N/A	Atacante pode assinar — mitigar com bloqueio OS + revogação remota
Replay de assinatura	N/A	Bloqueado por `nonce` + `sign_count`
QR enrollment capturado	N/A	Token uso único, TTL ≤ 3 min

Anti-gargalos (engenharia)

G1 — Reset password com email comprometido → exigir POAP ou recovery para reset.
G3 — Replay → sign_count monotónico por dispositivo.
G4 — Promoção instantânea → cooldown 24h + audit.
G6 — Desktop sem dispositivo → QR claro + cliente poap-sign, sem loop infinito.
G8 — Bridge → documentar step-up; não confundir com HMAC bridge.
G12 — Privacidade → export/apagar dispositivos = apagar chaves associadas (RGPD).

Lista completa: POAP/docs/POAP_ANTI_GARGALOS.md

Limitações conhecidas (v0.1)

Malware no dispositivo Master pode capturar assinaturas.
Recovery manual do tenant ainda necessário em enterprise sem kit guardado.
Apps puramente server-side precisam companion app ou browser com Web Crypto.
Não substitui auditoria SOC2 — complementa com eventos poap.*.

Auditoria e operação

Eventos: poap.activated, poap.device.revoked, poap.session.revoked_link, verificação de challenge.
Session Center — listar/revogar dispositivos e sessões ligadas.
Trust Center — coverage POAP (utilizadores, tiers, recovery não usados).
POAP Console — poap-manage para políticas por app Hosted.

Superfícies Auth21 (mapa)

Superfície	Papel POAP
`oauth-login.php`	Step challenge + links dispositivos
`poap-devices.php`	Activar Master, recovery, promoção (utilizador)
`poap-enrollment-qr.php`	QR Base (Master)
`poap-bridge-stepup.php`	Step-up pós-Bridge
`/poap/v1/*`	API verify, enrollment, revoke
`assets/js/poap-client.js`	Cliente browser de referência

Adoção (tenant Auth21)

Para organizações que já usam Auth21 Hosted — não é guia greenfield:

Aplicar migrations M7–M10 na base de dados.
Em OAuth & Apps → app Hosted → secção POAP: escolher poap_mode.
Comunicar utilizadores: activar Master no primeiro login após opt-in.
Monitorizar Trust Center e Session Center antes de passar a required.
Apps Bridge sensíveis: activar poap_step_up_bridge se aplicável.

Especificação machine-readable

Resumo JSON de tiers, políticas e modos: poap-spec-v0.1.json

Documento fonte longo: POAP/POAP.md · roadmap: POAP/MELHORIAS-AUTH21.md

FAQ

O que é o POAP da Auth21?

POAP, Proof of Ownership Authentication Protocol, é o protocolo Auth21 para provar posse criptográfica de um dispositivo registado após a identidade estar estabelecida — separa quem é a conta de quem opera agora com aquele dispositivo.

What is the Proof of Ownership Authentication Protocol?

The Proof of Ownership Authentication Protocol (POAP) is Auth21's specification for cryptographic device possession using Ed25519 challenge-response, Master/Base/Temp tiers and tenant poap_mode policies — a possession layer, not a replacement for OAuth or Bridge SSO.

Qual a diferença entre POAP e OAuth/OIDC?

OAuth e OIDC estabelecem identidade e emitem tokens de acesso. POAP é uma camada de posse que prova controlo de um dispositivo com chave registada — complementa login Hosted ou step-up em Bridge, não substitui authorize/token.

O que é device possession authentication?

Device possession authentication prova que o utilizador controla agora um dispositivo previamente registado com par de chaves, via desafio-resposta criptográfico. No POAP Auth21 isso usa Ed25519 e tiers Master, Base, Temp e Recovery.

Porque POAP só em Hosted?

Porque POAP gere auth21_hosted_user e UI nativa na Auth21. Em Bridge a identidade é externa; POAP entra como step-up opcional antes do consentimento OAuth, não como login principal no cliente.

POAP substitui TOTP?

Não necessariamente. TOTP pode permanecer no passo MFA; POAP adiciona posse de dispositivo. A política require_totp_for_social é independente de poap_mode.

Onde está a especificação oficial do POAP?

A URL canónica da especificação pública é https://poap.auth21.cloud. O resumo JSON machine-readable está em https://auth21.cloud/poap/schema/poap-spec-v0.1.json e o contexto para LLMs em https://poap.auth21.cloud/llms.txt.

Preciso de app móvel nativa?

Não precisa de app nas lojas: instale o POAP Companion (PWA) — guia passo a passo para Android, iPhone e desktop.

Onde está a API?

docs/POAP_API.md descreve endpoints para operadores com POAP já activo — fora do âmbito desta página de protocolo.