Guia de integração
É OpenID Connect. Você já sabe fazer isto.
Um provedor pareado com PAR e private_key_jwt, registro dinâmico, um webhook e uma API de cliente. Sem biblioteca própria, sem SDK.
Visão geral
Do código de registro ao id_token, em quatro passos.
O operador do uShield pré-registra a sua organização e emite um código de registro; o resto é o seu sistema falando OIDC.
Registre-se com o código de registro
POST /oidc/reg com as suas redirect_uris, o seu jwks_uri e as perguntas que vai fazer. Volta o client_id e o token de gestão.
Peça a autorização por PAR
private_key_jwt com a sua chave, o escopo ushield:garantia e o nível mínimo nos claims. A pessoa consente na tela do uShield.
Troque o código pelo id_token
O sub é pareado (só vale para você), e ushield_garantia traz o nível, a categoria do método e as datas.
Ouça o webhook e releia quando precisar
nivel.alterado, acesso.revogado e pessoa.eliminada chegam assinados; a API de cliente relê o nível de quem já o permitiu à sua organização.
Os contratos
O que vai no fio.
Os trechos abaixo são os do contrato do provedor, resumidos ao que você precisa para a primeira integração.
Discovery
O provedor é pareado, exige PAR e autentica o cliente por private_key_jwt.
GET https://ushield.app/.well-known/openid-configuration
{
"issuer": "https://ushield.app",
"subject_types_supported": ["pairwise"],
"require_pushed_authorization_requests": true,
"token_endpoint_auth_methods_supported": ["private_key_jwt"],
"grant_types_supported": ["authorization_code", "client_credentials",
"urn:ietf:params:oauth:grant-type:device_code"],
"scopes_supported": ["openid", "ushield:garantia", "ushield:ato"]
}Registro dinâmico
Uma vez, com o código de registro, que é o token de acesso inicial do RFC 7591 (uso único, 7 dias). O segredo do webhook vem UMA vez, na resposta.
POST https://ushield.app/oidc/reg
Authorization: Bearer <código de registro emitido pelo operador>
{
"client_name": "Clínica Exemplo",
"redirect_uris": ["https://exemplo.com.br/api/ushield/callback"],
"jwks_uri": "https://exemplo.com.br/.well-known/jwks.json",
"token_endpoint_auth_method": "private_key_jwt",
"subject_type": "pairwise",
"ushield_finalidades": [{ "codigo": "cadastro", "descricao": "Confirmar quem é você no cadastro" }],
"ushield_perguntas_permitidas": ["q1", "q2", "q3"],
"ushield_atributos_permitidos": ["cpf"],
"ushield_pepper_confirmacao": "<pepper da confirmação de CPF>",
"ushield_webhook_url": "https://exemplo.com.br/api/webhooks/ushield"
}
201 { "client_id": "rp_...", "registration_access_token": "...", "ushield_webhook_segredo": "..." }Autorização (PAR)
O nível mínimo vai nos claims, sempre no id_token: verified_claims pedido só no userinfo é recusado. A confirmação do CPF (Q3) vai em authorization_details. Sem PAR, o /oidc/auth recusa. O escopo tem de estar no registro.
POST https://ushield.app/oidc/request
client_id=rp_...
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<JWT assinado com a sua chave>
&response_type=code
&scope=openid ushield:garantia
&redirect_uri=https://exemplo.com.br/api/ushield/callback
&code_challenge=<S256>&code_challenge_method=S256
&claims={"id_token":{"verified_claims":{"verification":{"trust_framework":{"value":"br_ushield"},"assurance_level":{"values":["n2","n3"]}},"claims":{}}}}
&authorization_details=[{"type":"urn:ushield:confirmacao","atributo":"cpf","hash":"<HMAC-SHA256 do CPF com o seu pepper, em hex>"}]
201 { "request_uri": "urn:ietf:params:oauth:request_uri:...", "expires_in": 60 }
GET https://ushield.app/oidc/auth?client_id=rp_...&request_uri=urn:...O id_token
O sub é pareado. amr é swk, ou hwk quando o acr é urn:ushield:a3. ushield_garantia é o nível e a categoria. verificadoEm, validoAte, created_at e time são DIAS do calendário de Brasília, escritos como o meio-dia em UTC: compare pela data, nunca pela hora. No último dia de validade, validoAte pode ser anterior à hora da resposta, e quem decide é o nivel. A evidence só vem quando a prova é o certificado; verified_claims repete a verificação no vocabulário do OIDC4IDA; ushield_confirmacoes é a resposta da Q3, e atributos.cpf é o nível do CPF confirmado.
{
"iss": "https://ushield.app",
"sub": "<identificador pareado: só vale para a sua organização>",
"acr": "urn:ushield:a2",
"amr": ["swk"],
"ushield_garantia": {
"nivel": "n3", "metodoCategoria": "certificado",
"verificadoEm": "2026-09-18T12:00:00.000Z", "validoAte": "2027-09-18T12:00:00.000Z",
"evidence": [{ "type": "electronic_signature", "signature_type": "icp_brasil", "issuer": "<autoridade certificadora>", "serial_number": "<número de série>", "created_at": "2026-09-18T12:00:00.000Z" }],
"atributos": { "cpf": { "nivel": "n3", "metodoCategoria": "certificado" } }
},
"verified_claims": {
"verification": { "trust_framework": "br_ushield", "assurance_level": "n3", "time": "2026-09-18T12:00:00.000Z", "ushield_metodo_categoria": "certificado", "evidence": "<a mesma lista de ushield_garantia>" },
"claims": {}
},
"ushield_confirmacoes": { "cpf": "confere" },
"ushield_apresentacao": "<id desta resposta>"
}Webhook
HMAC-SHA256 sobre "<t>.<corpo>" com o segredo do registro; janela de 5 minutos; o id da entrega é idempotente. O aviso não traz o nível: releia-o pela API. O campo em é o instante do fato. nivel.alterado só chega à organização que já recebeu o nível daquela pessoa.
POST https://exemplo.com.br/api/webhooks/ushield
X-Ushield-Signature: t=1758400000,v1=<HMAC-SHA256 de "<t>.<corpo>" com o segredo>
X-Ushield-Delivery: <id da entrega>
{ "id": "<id da entrega>", "client_id": "rp_...", "evento": "nivel.alterado", "sub": "<sub pareado>", "motivo": "verificacao-vencida", "em": "2026-09-21T14:03:27.512Z" }API de cliente
client_credentials amarrado por DPoP. Bearer é recusado; prova repetida também. A consulta de nível só responde sobre quem já permitiu a pergunta do nível (Q2) à sua organização: para os demais, 404, também para quem só entregou um atributo (Q4) ou só assinou um documento.
POST https://ushield.app/oidc/token
grant_type=client_credentials&scope=rp:nivel
&resource=https://ushield.app/api/rp
&client_assertion=<JWT> (mais o cabeçalho DPoP: a prova assinada)
GET https://ushield.app/api/rp/nivel/<sub>
Authorization: DPoP <access_token>
DPoP: <prova nova, com htm, htu, iat, jti e ath>As perguntas
Cinco perguntas, e cada uma tem o seu escopo.
O registro declara as que a sua organização pode fazer; a tela de consentimento diz cada uma em linguagem clara.
- Q1
É você voltando?
Escopo openid. O sub pareado e o acr da sessão.
- Q2
Em que nível?
Escopo ushield:garantia. ushield_garantia no id_token, com o nível mínimo pedido nos claims.
- Q3
Este CPF ou e-mail é seu?
authorization_details com o HMAC do valor que você já tem. Volta confere ou nao-confere, nunca o valor.
- Q4
Um atributo registrado
Só pelo redirecionamento, com a finalidade registrada; a pessoa marca o que permite.
- Q5
Vou pedir a sua assinatura
Escopo ushield:ato: um aviso, nunca uma claim. O pedido de ato nasce pela API de cliente.
Assinatura
Para pedir a assinatura de um documento, a API de documentos.
Pedido novo de documento usa a API de documentos: o PDF, as pessoas por e-mail, o webhook e a reconciliação. A API de ato abaixo é legada: segue no ar para quem já a usa, na assinatura dentro de uma sessão aberta pelo login, em que a organização manda o hash e o título e o ato volta pela API.
- POST /api/rp/assinaturas (legada)Abre o pedido de ato para um sub pareado, com o hash SHA-256 do documento, o título, o nível mínimo e o regime. Responde com o cabeçalho Deprecation, que aponta o guia da API de documentos.
- AvançadaA passkey assina o desafio ushield-ato-v1:sha256:<hash>; a prova WebAuthn volta com a chave pública, e o selo da organização sela o PDF.
- QualificadaO certificado ICP-Brasil da pessoa assina os atributos que a organização preparou; o uShield confere que carregam o hash da tela antes de gravar.
- No balcãoDevice Flow com a Q3 e o escopo ushield:ato: o QR leva o pedido ao celular, e a tela da organização fecha sozinha.
Quer o código de registro?
Peça uma demonstração: saímos dela com a sua organização pré-registrada.