Aparência
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,$TOKENe 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
scopedecodificado. - 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
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,branchCodeecheckDigit) e a cobertura de isolamento das rotas de aplicação. Confira a entrada no CHANGELOG do serviço.OFB_RECEIVER_MODEestá ausente ou valerealno serviço bancário. O modoconformancesó serve um laboratório de conformidade, nunca clientes reais:bashkubectl -n <namespace> exec deploy/<serviço bancário> -- printenv OFB_RECEIVER_MODEA saída esperada é vazia ou
real.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:bashcurl -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,basice os opcionais); sem isso, o claimscopetrazprofile emaile a conferência abaixo falha; - o mapeador de público (
oidc-audience-mapper) com o público incluídofinnest-power-banking-application, só no token de acesso. Sem ele, toda rota de aplicação responde401; - numa instalação que também é transmissora do OFB (registro dinâmico de clientes do OFB ligado), o atributo de cliente
finnest.unbound_application_tokencom valortrue, 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 comclient 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)"
doneE 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'
doneEsperado: 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.