Guia de integração: entrada sem senha no Placarsoft

Para sistemas parceiros (por exemplo, o app de um município) que já autenticam o cidadão e querem levá-lo ao Placarsoft sem pedir login e senha de novo.

Há dois caminhos, que podem ser usados juntos:

• Link de acesso — o seu servidor pede ao Placarsoft um link de uso único para uma pessoa, e você a leva até ele.
• Botão "Entrar com o parceiro" — se você tem um provedor OpenID Connect, a tela de entrada do Placarsoft mostra um botão que leva a pessoa a ele e a traz de volta autenticada.

Esta aplicação é uma demonstração dos dois: ela faz o papel do sistema parceiro.

O que você recebe do Placarsoft

O administrador do sistema do cliente cadastra o seu sistema como parceiro e entrega a você:

• o endereço do backend do cliente (a seguir, {backend});
• um client_id e um client_secret para pedir links. O segredo é mostrado uma única vez; se for trocado, o anterior deixa de valer na hora.

No cadastro também ficam definidos o identificador principal da pessoa (CPF, um identificador personalizado — como um cartão cidadão — ou o e-mail), a claim que o traz, os destinos permitidos e, se combinado, a lista de IPs de onde os pedidos podem vir.

1. Link de acesso

Quando a pessoa pede para ir ao Placarsoft, o seu servidor pede o link. Nunca faça esse pedido pelo navegador ou pelo app da pessoa: o client_secret não pode sair do servidor.

POST {backend}/api/v1/auth/partner/link, autenticado por HTTP Basic com o client_id e o client_secret (Authorization: Basic base64(client_id:client_secret)).

O corpo é JSON, com os nomes das claims do OpenID Connect:

Campo	Quando enviar	Descrição
sub	sempre	Identificação estável da pessoa no seu sistema (até 255 caracteres). Depois do primeiro acesso, é por ela que a conta é achada.
cpf	conforme o cadastro	CPF, com ou sem máscara.
custom_id	conforme o cadastro	Identificador personalizado, até 50 caracteres.
email	conforme o cadastro	E-mail.
email_verified	se a pessoa for identificada pelo e-mail	Precisa ser true.
name	no primeiro acesso	Nome completo.
phone_number	opcional	Celular, de preferência no formato internacional (+5511912345678).
birthdate	opcional	Data de nascimento, AAAA-MM-DD.
gender	opcional	female ou male.
destination	opcional	Onde a pessoa entra. Sem ele, admin.

Destinos:

• admin — Sistema
• schools — App de professores

Cada destino precisa estar entre os permitidos ao seu sistema.

Exemplo de pedido:

{
  "sub": "8f14e45f",
  "name": "Maria da Silva",
  "cpf": "000.000.000-00",
  "email": "maria@example.com",
  "email_verified": true,
  "destination": "admin"
}

Resposta de sucesso (200):

{
  "status": 1,
  "link": "https://…",
  "expires_in": 300
}

Leve a pessoa ao link. Ele é de uso único e vale 5 minutos: peça um novo a cada ida, no momento do clique.

Recusas

A recusa volta com status: 0, um código em error e o motivo em message. Nenhuma conta é criada ou alterada numa recusa.

HTTP	error	Quando
401	invalid_client	client_id ou client_secret errados, ou parceiro desativado.
403	ip_not_allowed	O IP de origem não está na lista cadastrada para o parceiro.
403	invalid_destination	Destino desconhecido ou não permitido ao parceiro.
422	invalid_request	Falta o sub ou o identificador principal, um documento é inválido, ou falta o name de quem ainda não tem conta.
422	email_not_verified	Identificação por e-mail sem email_verified igual a true.
422	document_mismatch	O CPF ou o identificador personalizado pertence a outra conta, ou a conta encontrada já tem outro valor.
422	privileged_account	A conta encontrada tem acesso de administrador: essa pessoa entra só por senha.
422	inactive_account	A conta encontrada está inativa.
404	unavailable	O recurso não está ligado nesta instalação.
429	—	Muitos pedidos em pouco tempo a partir do mesmo IP. Tente de novo em instantes.

O que acontece com a conta

• Nada muda na emissão: a conta só é criada ou preenchida quando a pessoa abre o link.
• Primeiro acesso: sem ninguém com o identificador principal, a conta é criada com os dados recebidos, sem nenhuma permissão administrativa. Se o cliente exigir algum dado que você não mandou, a pessoa entra direto na tela de completar o cadastro.
• Acessos seguintes: a conta é achada pelo seu sub, mesmo que o e-mail ou outro dado tenha mudado no seu sistema.
• Os dados só preenchem campos vazios; nada que já está no cadastro é sobrescrito.
• E-mail e celular que já pertencem a outra conta são descartados, e a entrada segue sem eles.
• Se a pessoa já tinha conta, ela pode vinculá-la pela opção "Já tenho conta", na tela de completar o cadastro.

2. Botão "Entrar com o parceiro" (OpenID Connect)

Opcional, para quem tem um provedor OpenID Connect (como Keycloak ou um provedor próprio). Entregue ao administrador do cliente:

• o endereço do emissor (issuer) — o Placarsoft lê endpoints e chaves em {issuer}/.well-known/openid-configuration;
• um client_id e um client_secret de cliente confidencial, criados no seu provedor para o Placarsoft. É um par diferente do usado no link.

Cadastre no seu provedor o endereço de retorno que a tela do parceiro mostra no Placarsoft, em geral {backend}/api/v1/auth/partner/callback.

O que o seu provedor precisa suportar:

• fluxo de código de autorização com PKCE (S256), escopo openid profile email, state e nonce;
• autenticação do cliente no endpoint de token por client_secret_basic (ou client_secret_post);
• token de identidade assinado em RS256, RS384 ou RS512, com iss, aud, exp, iat, nonce e sub;
• as mesmas claims do link (cpf, custom_id, email, email_verified, name, phone_number…), no token ou no userinfo.

As regras de conta são as mesmas do link. Quando a entrada é recusada, a pessoa volta à tela de entrada do Placarsoft com o motivo.

Identificar pela claim sub

Alguns provedores entregam o CPF no próprio sub, como o gov.br. Nesse caso, combine com o administrador do cliente que o identificador principal é o CPF lido da claim sub. Nesta demonstração, a tela de Conexão alterna entre "sub = id interno" e "sub = CPF" para mostrar os dois jeitos.

Escolha um jeito e mantenha: o vínculo entre a pessoa e a conta no Placarsoft é feito pelo sub, e trocar o formato depois faz a próxima entrada procurar a conta de novo pelo identificador principal.

Boas práticas

• Guarde o client_secret só no servidor, fora do código-fonte.
• Peça o link no momento em que a pessoa toca em "Ir ao Placarsoft", nunca antes.
• Use um sub que não muda e não é reaproveitado para outra pessoa.
• Mande email_verified: true só quando o seu sistema de fato conferiu o e-mail.
• Trate as recusas mostrando à pessoa uma mensagem clara, e registre o error para o suporte.