Skip to content

Roteiro de validação: escopo, isolamento e dados de teste ​

Quem opera a instalação executa este roteiro antes de liberar as APIs de aplicação da receptora e da iniciadora (veja Acesso por aplicação) para uma prova de conceito ou para o sandbox. Ele comprova que um token sem o escopo certo é recusado, que uma aplicação não enxerga o que outra abriu, que o banco só guarda massa sintética e que os logs não trazem documento nem token.

Regras para todo o roteiro:

  • Os comandos usam só marcadores: <domínio>, $CLIENT_ID_T1, $CLIENT_SECRET_T1, $TOKEN e afins. Leia cada segredo do cofre da operação para uma variável de ambiente; nunca o escreva no comando, no registro do roteiro ou num ticket.
  • Nunca cole um token. Do token, registre só o claim scope decodificado.
  • Registre contagens, status e códigos de erro. Um achado é registrado pela tabela e pelo id da linha, ou pelo serviço e pelo horário do log, nunca pelo valor.
  • Toda chamada leva x-fapi-interaction-id; guarde-o para encontrar a chamada nos logs.

1. Release e modo ​

  1. A versão instalada do serviço bancário (@finnest/banking-service) é igual ou posterior à release que traz a redação dos dados da conta (number, branchCode e checkDigit) e a cobertura de isolamento das rotas de aplicação. Confira a entrada no CHANGELOG do serviço.

  2. OFB_RECEIVER_MODE está ausente ou vale real no serviço bancário. O modo conformance só serve um laboratório de conformidade, nunca clientes reais:

    bash
    kubectl -n <namespace> exec deploy/<serviço bancário> -- printenv OFB_RECEIVER_MODE

    A saída esperada é vazia ou real.

  3. O plano de controle de conformidade não existe na instalação. Faça esta conferência depois do passo 2, com o token da credencial principal: a leitura abaixo não pode responder 2xx:

    bash
    curl -sS -o /dev/null -w '%{http_code}\n' \
      https://api.<domínio>/internal/conformance/state \
      -H "Authorization: Bearer $TOKEN" -H "x-fapi-interaction-id: $(uuidgen)"

Registre: a versão instalada, o valor de OFB_RECEIVER_MODE e o status da leitura.

2. Credencial com escopo mínimo ​

A credencial principal é um cliente client_credentials do realm finnest-ofb com exatamente os escopos que a prova de conceito usa: ofb:receiver:consents, os escopos das famílias de dados lidas (ofb:receiver:customers, ofb:receiver:accounts e, se ler cartões, ofb:receiver:credit-cards) e ofb:initiator:payments. A aplicação embutida finnest-power-ofb-application traz todos os escopos de aplicação; para o escopo mínimo, crie no console do Keycloak (finnest kc console) um cliente com a mesma forma dela:

  • confidencial, com Service accounts ligado, sem fluxo padrão nem acesso direto, e autenticação por segredo (client_secret);
  • token de acesso assinado com PS256 e sem vínculo a certificado;
  • como escopos padrão, só roles (como na aplicação embutida) e os escopos de aplicação listados acima. Remova do cliente novo os escopos padrão e opcionais que o Keycloak associa a todo cliente criado no console (profile, email, web-origins, acr, basic e os opcionais); sem isso, o claim scope traz profile email e a conferência abaixo falha;
  • o mapeador de público (oidc-audience-mapper) com o público incluído finnest-power-banking-application, só no token de acesso. Sem ele, toda rota de aplicação responde 401;
  • numa instalação que também é transmissora do OFB (registro dinâmico de clientes do OFB ligado), o atributo de cliente finnest.unbound_application_token com valor true, gravado como em Gravar o atributo da aplicação. Lá o endpoint de token passa pelo gateway de registro, que só admite sem vínculo de certificado um cliente com esse atributo; sem ele, o pedido de token é recusado com client certificate binding required. Nas demais instalações o token não passa pelo gateway e o atributo é inofensivo.

Gravar o atributo da aplicação ​

A API de administração do Keycloak grava atributos de cliente: GET /admin/realms/{realm}/clients?clientId=<id> devolve a representação do cliente (ClientRepresentation), cujo campo attributes é um mapa de texto para texto, e PUT /admin/realms/{realm}/clients/{id} grava a representação alterada ({id} é o id interno do cliente, não o clientId). Com o túnel de finnest kc console aberto, leia em $KC_ADMIN_URL o endereço de administração que o comando mostra e, nas variáveis $KC_ADMIN_USER e $KC_ADMIN_PASSWORD, as credenciais de administrador que ele indica. O token de administrador vem do cliente admin-cli do realm master, que o Keycloak já cria com o escopo kc-admin-api exigido pela API de administração:

bash
ADMIN_TOKEN=$(curl -sS "$KC_ADMIN_URL/realms/master/protocol/openid-connect/token" \
  -d grant_type=password -d client_id=admin-cli \
  --data-urlencode username="$KC_ADMIN_USER" \
  --data-urlencode password="$KC_ADMIN_PASSWORD" | jq -r .access_token)

CLIENT=$(curl -sS "$KC_ADMIN_URL/admin/realms/finnest-ofb/clients?clientId=$CLIENT_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  | jq -c --arg id "$CLIENT_ID" '.[] | select(.clientId == $id)')

jq -c '.attributes["finnest.unbound_application_token"] = "true"' <<<"$CLIENT" \
  | curl -sS -o /dev/null -w '%{http_code}\n' -X PUT \
    "$KC_ADMIN_URL/admin/realms/finnest-ofb/clients/$(jq -r .id <<<"$CLIENT")" \
    -H "Authorization: Bearer $ADMIN_TOKEN" -H 'content-type: application/json' --data-binary @-

Esperado: 204. Confira lendo o cliente de novo, sem imprimir a representação, que traz o segredo:

bash
curl -sS "$KC_ADMIN_URL/admin/realms/finnest-ofb/clients?clientId=$CLIENT_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  | jq -r --arg id "$CLIENT_ID" '.[] | select(.clientId == $id)
      | .attributes["finnest.unbound_application_token"]'

Esperado: true. O valor tem de ser exatamente true; qualquer outro texto não marca o cliente. A atualização do realm não apaga o atributo de um cliente criado no console.

Conferir o token ​

Peça o token pelo endpoint da instalação (veja Obter o token). Troque <host do endpoint de token> pelo host que o Admin mostra: auth.<domínio> sem a superfície mTLS regulada; com ela, matls-auth.<domínio>, e acrescente --cert transporte.crt --key transporte.key à chamada. Decodifique o claim scope localmente, sem imprimir o token:

bash
TOKEN=$(curl -sS https://<host do endpoint de token>/realms/finnest-ofb/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" | jq -r .access_token)

jq -rR 'split(".")[1] | gsub("-"; "+") | gsub("_"; "/")
  | . + ("=" * ((4 - length % 4) % 4)) | @base64d | fromjson | .scope' <<<"$TOKEN"

Registre só a saída do jq: os escopos da credencial, nenhum a mais e nenhum a menos.

3. Teste negativo de escopo ​

Crie uma credencial temporária T1, com a mesma forma da principal (numa instalação transmissora do OFB, inclusive o atributo finnest.unbound_application_token), mas só com os escopos de dados (sem ofb:receiver:consents). Peça o token no endpoint da instalação, como no passo 2, em $TOKEN_T1, e confira o scope. A criação de um consentimento com esse token é recusada:

bash
curl -sS https://api.<domínio>/banking-receiver/consents/v1/consents \
  -H "Authorization: Bearer $TOKEN_T1" \
  -H "x-fapi-interaction-id: $(uuidgen)" \
  -H "x-idempotency-key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{
    "data": {
      "authorisationServerId": "<id do servidor de autorização do Mock Bank>",
      "redirectUri": "https://api.<domínio>/banking-receiver/consents/v1/callback/fragment",
      "loggedUser": { "document": { "identification": "<CPF>", "rel": "CPF" } },
      "permissions": ["RESOURCES_READ", "CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ"]
    }
  }' \
  -w '\n%{http_code}\n'

Esperado: status 403 e errors[0].code igual a AUTH_INSUFFICIENT_SCOPE. A listagem GET /banking-receiver/consents/v1/consents com T1 é recusada da mesma forma, porque T1 não tem o escopo de consentimento. O <CPF> é o documento de um usuário de teste do Mock Bank (Dados de teste).

4. Teste negativo de isolamento ​

Com a credencial principal, rode a jornada da receptora e a da iniciadora (consentimento, coleta, leitura das agregações e consentimento de pagamento) e anote o connectionId, um id de agregação (aggregationId) e o consentId do pagamento.

Crie uma credencial temporária T2: outro cliente, com a mesma forma e os mesmos escopos da principal (numa instalação transmissora do OFB, inclusive o atributo finnest.unbound_application_token). Peça o token no endpoint da instalação, como no passo 2, em $TOKEN_T2. Cada leitura por id do que a principal abriu responde 404:

bash
for path in \
  banking-receiver/consents/v1/consents/<connectionId> \
  banking-receiver/v1/aggregations/<aggregationId> \
  banking-initiator/payments/v1/consents/<consentId>
do
  curl -sS -o /dev/null -w "%{http_code} $path\n" "https://api.<domínio>/$path" \
    -H "Authorization: Bearer $TOKEN_T2" -H "x-fapi-interaction-id: $(uuidgen)"
done

E cada listagem responde 200 com a lista vazia:

bash
for path in \
  banking-receiver/consents/v1/consents \
  banking-receiver/v1/aggregations \
  banking-initiator/payments/v1/consents
do
  printf '%s ' "$path"
  curl -sS "https://api.<domínio>/$path" \
    -H "Authorization: Bearer $TOKEN_T2" -H "x-fapi-interaction-id: $(uuidgen)" \
    | jq '.data | length'
done

Esperado: 404 nas três leituras e 0 nas três listagens. Repita as leituras por id com o token da principal: elas respondem 200, então o 404 de T2 é isolamento, não ausência.

Ao terminar, desative T1 e T2 no console do Keycloak (em Clients, abra o cliente e desligue Enabled) e confirme que o endpoint de token da instalação os recusa (com a superfície mTLS regulada, matls-auth.<domínio> com --cert e --key, como no passo 2):

bash
curl -sS https://<host do endpoint de token>/realms/finnest-ofb/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID_T1" \
  -d client_secret="$CLIENT_SECRET_T1" | jq '{error, has_token: has("access_token")}'

Esperado: um error OAuth e has_token igual a false, para T1 e para T2. Depois apague os dois clientes e descarte os segredos deles do cofre.

5. Só massa sintética ​

Os dados que a receptora coletou e os pagamentos que a iniciadora criou ficam em banking.receiver_data_aggregations (coluna payload), banking.initiator_payment_consents (coluna payload), banking.initiator_pix_payments (coluna request_payload), banking.initiator_enrollments (coluna payload) e banking.initiator_commands (coluna response_body, a resposta da detentora a cada comando, que repete o documento do usuário e do recebedor). Se a prova de conceito usar pagamentos recorrentes, acrescente banking.initiator_recurring_consents (payload) e banking.initiator_recurring_payments (request_payload) da mesma forma. A consulta abaixo roda numa transação só de leitura e conta cada sequência isolada de 11 ou 14 dígitos (a forma de um CPF ou de um CNPJ) por tabela:

sql
BEGIN;
SET TRANSACTION READ ONLY;
SELECT t, d, count(*) FROM (
  SELECT 'agg' t, m[1] d FROM banking.receiver_data_aggregations,
    regexp_matches(payload::text, '(?<![0-9])([0-9]{11}|[0-9]{14})(?![0-9])', 'g') m
  UNION ALL SELECT 'pay', m[1] FROM banking.initiator_payment_consents,
    regexp_matches(payload::text, '(?<![0-9])([0-9]{11}|[0-9]{14})(?![0-9])', 'g') m
  UNION ALL SELECT 'pix', m[1] FROM banking.initiator_pix_payments,
    regexp_matches(request_payload::text, '(?<![0-9])([0-9]{11}|[0-9]{14})(?![0-9])', 'g') m
  UNION ALL SELECT 'enr', m[1] FROM banking.initiator_enrollments,
    regexp_matches(payload::text, '(?<![0-9])([0-9]{11}|[0-9]{14})(?![0-9])', 'g') m
  UNION ALL SELECT 'cmd', m[1] FROM banking.initiator_commands,
    regexp_matches(response_body::text, '(?<![0-9])([0-9]{11}|[0-9]{14})(?![0-9])', 'g') m
) x GROUP BY 1, 2;
ROLLBACK;

As expressões regulares do PostgreSQL aceitam as restrições de lookbehind ((?<!…)) e lookahead ((?!…)) usadas acima. Compare cada documento encontrado com a lista dos usuários de teste do Mock Bank, sem copiar o valor para fora da sessão do banco.

Esperado: nenhum documento fora da lista do Mock Bank. Registre só a contagem por tabela, nunca os valores; um achado é registrado pela tabela e pelo id da linha. Confirme também com a equipe que opera a instalação que o bun seed:ofb nunca rodou contra ela.

6. Logs sem PII nem tokens ​

Depois de uma rodada completa (consentimento, coleta, leitura de contas, consentimento de pagamento e Pix), procure na janela exata da rodada nos logs do serviço bancário, do gateway (o log de acesso do Kong) e nos eventos do Keycloak. Com o Loki:

logql
sum(count_over_time({<seletor da instalação>} |~ `(?i)bearer [A-Za-z0-9._-]{10,}|eyJ[A-Za-z0-9_-]{10,}|\b[0-9]{11}\b|\b[0-9]{14}\b|[0-9]{3}\.[0-9]{3}\.[0-9]{3}-[0-9]{2}|"(number|branchCode|checkDigit|cpf|cnpj|cpfCnpj)"\s*:\s*"[^"\[*]|"issuer"\s*:\s*"[0-9]{1,4}"` [<janela>]))

O padrão procura um token Bearer ou um JWT, um CPF ou CNPJ só com dígitos, um CPF pontuado, os campos de documento e de conta com um valor que não seja o [REDACTED] da redação nem uma máscara com * e a agência da conta (issuer de 1 a 4 dígitos) sem redação. Rode a consulta uma vez por serviço, trocando o seletor.

Sem o Loki, leia os logs de cada serviço na mesma janela e conte as linhas com o mesmo padrão (grep -i no lugar do (?i)):

bash
PATTERN='bearer [A-Za-z0-9._-]{10,}|eyJ[A-Za-z0-9_-]{10,}|\b[0-9]{11}\b|\b[0-9]{14}\b|[0-9]{3}\.[0-9]{3}\.[0-9]{3}-[0-9]{2}|"(number|branchCode|checkDigit|cpf|cnpj|cpfCnpj)"\s*:\s*"[^"\[*]|"issuer"\s*:\s*"[0-9]{1,4}"'

kubectl -n <namespace> logs deploy/<serviço> --since=<janela> | grep -E -i -c "$PATTERN"
# ou, numa instalação com Docker:
docker logs --since <janela> <contêiner> 2>&1 | grep -E -i -c "$PATTERN"

Esperado: 0 em cada serviço. Um documento sintético do Mock Bank em claro também conta como falha de redação, porque a redação não distingue massa de teste de dado real. Registre a consulta, a janela, a fonte (Loki ou logs do contêiner), a retenção dos logs e a contagem por serviço; um achado é registrado pelo serviço e pelo horário, com o valor mascarado.

Finnest Power — plataforma Open Finance Brasil e Open Insurance Brasil. Contato: oi@finnest.com.br