Ir para o conteúdo

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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  1. Q1

    É você voltando?

    Escopo openid. O sub pareado e o acr da sessão.

  2. Q2

    Em que nível?

    Escopo ushield:garantia. ushield_garantia no id_token, com o nível mínimo pedido nos claims.

  3. 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.

  4. Q4

    Um atributo registrado

    Só pelo redirecionamento, com a finalidade registrada; a pessoa marca o que permite.

  5. 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.

Ver o guia da API de documentos

Quer o código de registro?

Peça uma demonstração: saímos dela com a sua organização pré-registrada.