• Carol Morais

Notas de um implementador sobre Open Banking Brasil

Atualizado: 16 de Jul de 2021

por Takahiko Kawasaki (Authlete Inc)


Este artigo explica detalhes técnicos do Open Banking Brasil (OBB), especialmente as diferenças entre extensões OBB e especificações de padrão global.


Perfil de segurança de API de nível financeiro OBB


Stack de Especificação


O OBB publicou o “Rascunho 1 dos implementadores do Perfil de Segurança 1.0 de API de Nível Financeiro Open Banking Brasil” (daqui em diante vamos nos referir como “OBB FAPI”) no final de maio de 2021. No momento em que foi este post foi escrito, a especificação estava sendo atualizada desde então por meio de discussões no GitHub (OpenBanking-Brasil / specs-seguranca), em workshops e talvez em algum outro lugar que eu desconheça. Nesse sentido, a especificação ainda não é estável. (Portanto, este artigo será atualizado no futuro.)


A especificação OBB FAPI é construída sobre a versão final do “Perfil de Segurança 1.0 de API de nível financeiro” (daqui em diante refere-se a “FAPI 1.0”), que foi publicada em março de 2021.



Perfil de segurança 1.0 da API de nível financeiro do Open Banking Brasil sobre a especificação FAPI 1.0
Perfil de segurança 1.0 da API de nível financeiro do Open Banking Brasil sobre a especificação FAPI 1.0

A especificação FAPI 1.0 consiste na “Parte 1: Linha de base” e “Parte 2: Avançado”. O Perfil de Segurança Avançado (Parte 1) define requisitos mais rígidos do que o Perfil de Segurança de Linha de Base (Parte 2). A especificação OBB FAPI requer que as implementações estejam em conformidade com o Perfil de Segurança Avançada.


Por favor leia Financial-grade API (FAPI), explained by an implementer para detalhes técnicos da especificação FAPI 1.0. A tradução em português “API de nível financeiro (FAPI), explicada por um implementador” está disponível no site da Fundação OpenID.


Requisitos do servidor de autorização OBB

A especificação OBB FAPI tem uma seção entitulada “5.2.2. Servidor de autorização”. A seção lista requisitos adicionais para servidores de autorização. Ou seja, os requisitos lá são diferenças entre a especificação OBB FAPI e a FAPI 1.0. Vamos lê-los um por um.


OBB FAPI 1.0, 5.2.2. Servidor de autorização, Cláusula 1

Deve suportar um objeto de request JWE assinado e criptografado passado por valor ou deve exigir solicitações de autorização por push (PAR - Push Authorization Request);


Para começar, você precisa saber qual é o request object (requisição). É um JWT (RFC 7519: JSON Web Token) que inclui parâmetros de requisição de uma request de autorização. Se você não está familiarizado com um objeto de request, procure por este termo nas documentações FAPI.




Request Object


No FAPI 1.0 Avançado, os objetos de requisição devem sempre ser assinados, mas não precisam ser criptografados. Por outro lado, OBB FAPI exige que os objetos de requisição sejam sempre criptografados, a menos que a requisição de autorização seja registrada com antecedência usando PAR.


PAR aqui significa “Solicitações de autorização push do OAuth 2.0”. É uma especificação relativamente nova que define a maneira em que um aplicativo do cliente registra um pedido de autorização com antecedência e obtém um “URI de requisição” como retorno e, posteriormente, o aplicativo do cliente faz um pedido de autorização com o URI de requisição emitido. Ao usar esse mecanismo, o aplicativo do cliente pode evitar o envio de parâmetros de requisição de autorização por valor por meio de um navegador da web; “Através de um navegador da web” às vezes é expresso como “através do canal frontal”. Leia “PAR ilustrado: requisições de autorização por push do OAuth 2.0” para obter a visão geral do PAR.



Visão geral das solicitações de autorização push do OAuth 2.0 (PAR)

“OpenID Connect Dynamic Client Registration 1.0” define dois metadados de cliente relacionados à criptografia de objeto de requisição como segue.


request_object_encryption_alg

OPTIONAL. JWE [JWE] alg algoritmo [JWA] o RP está declarando que pode usar para criptografar Objetos de Requisição enviados para o OP. Este parâmetro DEVE ser incluído quando a criptografia simétrica for usada, uma vez que isso sinaliza ao OP que um valor client_secret precisa retornar do qual a chave simétrica será derivada, que de outra forma não poderia retornar. O RP PODE ainda usar outros algoritmos de criptografia suportados ou enviar Objetos de Requisição não criptografados, mesmo quando este parâmetro estiver presente. Se ambas assinatura e criptografia forem solicitadas, o Objeto de Requisição será assinado e, em seguida, criptografado, com o resultado sendo um JWT aninhado, conforme definido em [JWT]. O padrão, se omitido, é que o RP não está declarando se pode criptografar quaisquer Objetos de Requisição.


request_object_encryption_enc

OPTIONAL.JWE enc algoritmo [JWA]. O RP está declarando que pode usar para criptografar Objetos de Requisição enviados para o OP. Se request_object_encryption_alg for especificado, o padrão para este valor é A128CBC-HS256. Quando request_object_encryption_enc está incluído, request_object_encryption_alg DEVE também ser fornecido.


A parte que enfatizei afirma que “O RP PODE ainda usar outros algoritmos de criptografia suportados ou enviar Objetos de Requisição não criptografados, mesmo quando este parâmetro estiver presente”. Isso significa que um servidor de autorização não rejeita objetos de requisição não criptografados, mesmo se os metadados do cliente request_object_encryption_alg do aplicativo cliente estiverem definidos.


Como a especificação é definida dessa forma, um servidor de autorização não pode contar com os metadados padrão do cliente request_object_encryption_alg se o servidor deseja rejeitar objetos de requisição não criptografados passados ​​pelo canal frontal. Como resultado, o provedor de serviços ou o fornecedor da solução do servidor de autorização precisa personalizar sua implementação para o requisito específico do OBB.


Por exemplo, a Authlete implementou o recurso “Encryption in Front Channel” como uma opção de configuração do servidor e do cliente para esse propósito. O recurso está disponível desde o Authlete 2.2.11.



Opção “Encryption in Front Channel” no Authlete

OBB FAPI 1.0, 5.2.2. Servidor de autorização, Cláusula 2


deve distribuir metadados de descoberta (como o endpoint de autorização) através do documento de metadados, conforme especificado no OIDD e [RFC8414]


OIDD aqui é a abreviação de “OpenID Connect Discovery 1.0”. A especificação define um endpoint denominado “discovery endpoint” que retorna metadados do servidor no formato JSON. O JSON é chamado de “discovery document”. O ponto de extremidade de descoberta em si não é específico do OBB.



OBB FAPI 1.0, 5.2.2. Servidor de autorização, cláusula 3


Deve suportar o parâmetro de claims conforme definido na cláusula 5.5 OpenID Connect Core


No “OpenID Connect Core 1.0” (OIDC Core), um servidor de autorização não precisa necessariamente oferecer suporte ao parâmetro de requisição de claims. O servidor pode anunciar se suporta o parâmetro ou não usando os metadados do servidor Claims_parameter_supported no discovery document.


Todos os discovery documents de servidores de autorização no ecossistema Open Banking Brasil incluirão "Claims_parameter_supported": true porque o suporte é obrigatório.



OBB FAPI 1.0, 5.2.2. Servidor de autorização, cláusula 4


Deve suportar a claim padrão da OIDC "cpf", conforme definido na cláusula 5.2.2.2 deste documento


OBB FAPI 1.0, 5.2.2. Servidor de autorização, cláusula 5


Deve apoiar a claim padrão da OIDC "cnpj", conforme definido na cláusula 5.2.2.3 deste documento, se fornecer acesso a recursos onde o proprietário do recurso não é uma pessoa física


As cláusulas 4ª e 5ª exigem que um servidor de autorização suporte a claim cpf e condicionalmente a claim cnpj. Embora a especificação OBB FAPI use a palavra “oidc standard claim”, eles não estão incluídos na lista de claims padrão definidas em “5.1. Standard Claims” do OIDC Core. A claim cpf e a claim cnpj são específicas do OBB.


As claims devem ser incluídas nos metadados do servidor Claims_supported no discovery document. Caso contrário, alguns casos de teste OBB no pacote de conformidade oficial falharão.

É muito provável que a implementação do seu servidor de autorização forneça um mecanismo pelo qual liste as claims com suporte, como a seguir. Caso contrário, seria impossível anunciar as claims específicas do OBB no discovery document.



Claims com suporte (captura de tela do console do proprietário do serviço da Authlete)

OBB FAPI 1.0, 5.2.2. Servidor de autorização, cláusula 6

deve suportar a acr “urn:brasil:openbanking:loa2” conforme definido na cláusula 5.2.2.4 deste documento



OBB FAPI 1.0, 5.2.2. Servidor de autorização, cláusula 7

deve suportar a acr “urn:brasil:openbanking:loa3” conforme definido na cláusula 5.2.2.4 deste documento



As cláusulas 6ª e 7ª requerem que um servidor de autorização suporte o valor ACR urn:brasil:openbanking:loa2 e, opcionalmente, o valor ACR urn:brasil:openbanking:loa3. loa nos valores ACR significa “Nível de garantia”. Você pode encontrar as definições de LoA2 e LoA3 em “X.1254: Estrutura de garantia de autenticação de entidade”.


Os valores ACR devem ser incluídos nos metadados do servidor acr_values_supported no discovery document. Para conseguir isso, é altamente provável que a implementação do servidor de autorização forneça um mecanismo do qual liste os valores ACR com suporte, como abaixo. Caso contrário, seria impossível anunciar os valores ACR específicos do OBB no discovery document.



Valores de ACR com suporte (captura de tela do console do proprietário do serviço da Authlete)

OBB FAPI 1.0, 5.2.2. Servidor de autorização, cláusula 8


deve implementar o endpoint userinfo conforme definido na cláusula 5.3 OpenID Connect Core

O endpoint UserInfo retorna informações sobre o usuário que está associado ao token de acesso apresentado. O formato das respostas do endpoint é JSON simples, a menos que os metadados do cliente userinfo_signed_response_alg e / ou os metadados do cliente userinfo_encrypted_response_alg do aplicativo cliente sejam configurados.



OBB FAPI 1.0, 5.2.2. Servidor de autorização, Cláusula 9


deve suportar consent de escopo de recurso OAuth 2.0 parametrizado, conforme definido na cláusula 6.3.1 OIDF FAPI WG Lodging Intent Pattern


Esta cláusula requer um recurso que é frequentemente referido como “escopo parametrizado” ou “escopo dinâmico”. O recurso permite que os valores de escopo (listados no parâmetro de requisição de scope) tenham valores dinâmicos que são determinados no tempo de execução.


Alguns servidores de autorização oferecem suporte ao recurso, mas basicamente suas implementações não são interoperáveis. A principal razão é que não existe um padrão com relação ao formato dos valores de escopo dinâmico. Algumas variantes podem ser simples como "um prefixo fixo + parte dinâmica" (por exemplo myprefix: 123456), outras podem ser mais complexas: printer:print,manage, *:view, etc.


A partir da experiência do UK Open Banking e de outros ecossistemas, a comunidade OAuth percebeu que deveria desenvolver uma forma padrão que pudesse substituir os recursos de “escopo dinâmico” não interoperáveis. Após uma longa discussão, a comunidade desenvolveu “Solicitações de Autorização OAuth 2.0 Rich” a.k.a. RAR. A nova especificação deve fazer parte da FAPI 2.0 conforme declarado nas FAPI FAQ.


Portanto, quando a comunidade percebeu que o OBB iria adotar seu próprio recurso de “escopo dinâmico”, eles recomendaram o RAR ao OBB. No entanto, apesar de algumas tentativas de persuasão, o OBB não seguiu a recomendação e decidiu ir com o recurso de escopo dinâmico.

Dependendo de cada implementação, os desenvolvedores podem usar o recurso. Uma determinada implementação requer que os desenvolvedores escrevam um script para analisar escopos dinâmicos em troca de flexibilidade máxima. Outros podem ser muito mais fáceis de usar, mas não têm flexibilidade.


No caso da Authlete, os desenvolvedores podem usar o recurso de escopo dinâmico anexando um atributo “regex” a um escopo. O atributo “regex” representa a expressão regular de um escopo dinâmico. Se um valor de escopo incluído no parâmetro de requisição de scope corresponder à expressão regular, o valor de escopo será reconhecido.


Por exemplo, ao anexar um atributo “regex” cujo valor é ^ consent:. + $ ao scope de consentimento, um servidor de autorização pode oferecer suporte ao “Dynamic Consent Scope” definido em “7.1.2. Definição de Escopo de Consentimento Dinâmico” da especificação OBB FAPI. Consulte “Usando escopos parametrizados” na Base de Conhecimento Authlete para obter detalhes.



Um atributo “regex” para apoiar o Escopo de Consentimento Dinâmico

OBB FAPI 1.0, 5.2.2. Servidor de autorização, cláusula 10


pode suportar API de nível financeiro: Perfil de autenticação de backchannel iniciado pelo cliente



OBB FAPI 1.0, 5.2.2. Servidor de autorização, cláusula 11


deve suportar API de nível financeiro: Perfil de Autenticação de Backchannel Iniciado pelo Cliente se suportar payments de escopo



O “API de nível financeiro: Perfil de autenticação de backchannel iniciado pelo cliente” a.k.a. Perfil FAPI-CIBA define requisitos adicionais que os servidores de autorização devem cumprir quando suportam FAPI e CIBA ao mesmo tempo.


A autenticação de backchannel iniciada pelo cliente a.k.a. CIBA define novos fluxos de autorização que são diferentes dos tradicionais definidos em RFC 6749: O OAuth 2.0 Authorization Framework. O ponto mais importante da CIBA é que ela separa o “dispositivo de autenticação” (no qual a autenticação do usuário é realizada) do “dispositivo de consumo” (que obtém um token de acesso e chama APIs da Web). Essa separação permite oferecer suporte a novos casos de uso. Leia “CIBA, explicada por um implementador” para detalhes técnicos da CIBA.



Conceito de CIBA



OBB FAPI 1.0, 5.2.2. Servidor de autorização, Cláusula 12


deve suportar tokens de atualização

No RFC 6749, o suporte a “token de atualização” é opcional. A especificação OBB FAPI torna isso obrigatório.



OBB FAPI 1.0, 5.2.2. Servidor de autorização, Cláusula 13


deve emitir tokens de acesso com uma validade não superior a 900 segundos e não inferior a 300 segundos


A especificação OBB FAPI impõe uma restrição ao tempo de vida dos tokens de acesso.


Depende de cada implementação, como configurar o tempo de vida dos tokens de acesso. As implementações modernas fornecem várias maneiras de configurá-lo. Os padrões típicos são a configuração por servidor e a configuração por cliente. Além disso, a configuração per-scope pode ser fornecida. Consulte “Como Authlete determina a duração do token” se estiver interessado em exemplos de implementações atuais.



Requisitos de algoritmo OBB


“6. Considerações de segurança” das especificações OBB FAPI lista alguns requisitos relacionados a algoritmos.



OBB FAPI 1.0, 6.1. Considerações de algoritmo


Para JWS, clientes e servidores de autorização


1. deve usar o algoritmo PS256;


JWS aqui significa “JSON Web Signature”. Sua especificação é definida no RFC 7515. JWS é um formato para “dados assinados”. Isso implica que o JWS contém uma “assinatura” além dos próprios dados. A seguir está a estrutura do JWS. Consulte “Compreendendo o token de ID” para obter detalhes sobre JWS (e JWE e JWT).


{Header}.{Payload}.{Signature}



Em qualquer caso, para a assinatura, é necessário um algoritmo de assinatura. RFC 7518: JSON Web Algorithms (JWA) lista os seguintes algoritmos de assinatura para JWS.


  • HS256 - HMAC usando SHA-256

  • HS384 - HMAC usando SHA-384

  • HS512 - HMAC usando SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 usando SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 usando SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 usando SHA-512

  • ES256 - ECDSA usando P-256 e SHA-256

  • ES384 - ECDSA usando P-384 e SHA-384

  • ES512 - ECDSA usando P-521 e SHA-512

  • PS256 - RSASSA-PSS usando SHA-256 e MGF1 com SHA-256

  • PS384 - RSASSA-PSS usando SHA-384 e MGF1 com SHA-384

  • PS512 - RSASSA-PSS usando SHA-512 e MGF1 com SHA-512

  • nenhum - nenhuma assinatura digital ou MAC realizado



O FAPI 1.0 Advanced impõe restrições aos algoritmos de assinatura permitidos conforme abaixo.



FAPI 1.0 Advanced, 8.6. Considerações de algoritmo


Para JWS, clientes e servidores de autorização


1. deve usar algoritmos PS256 ou ES256;

2. não deve usar algoritmos que usam RSASSA-PKCS1-v1_5 (por exemplo, RS256); e

3. não deve usar none.



Resumindo, no contexto do FAPI 1.0 Advanced, os algoritmos de assinatura permitidos para JWS são apenas PS256 e ES256.

O requisito da especificação OBB FAPI no algoritmo de assinatura JWS é mais restritivo do que o FAPI 1.0 Advanced. No contexto do OBB, o PS256 é o único algoritmo de assinatura permitido para JWS.



OBB FAPI 1.0, 6.1.1. Considerações de algoritmo de criptografia


Para JWE, clientes e servidores de autorização


1. deve usar RSA-OAEP com A256GCM



JWE aqui significa “JSON Web Encryption”. Sua especificação é definida no RFC 7516. JWE é um formato para “dados criptografados”.

Na maioria dos casos, o JWE usa dois algoritmos para criptografia em duas etapas, conforme ilustrado abaixo (extraído de “Compreendendo o token de ID”).



Criptografia em duas etapas