• Carol Morais

Notas de um implementador sobre Open Banking Brasil

Atualizado: Jul 16

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



A criptografia em duas etapas é o motivo pelo qual os metadados relacionados ao JWE são definidos como um par de * _alg e * _enc. Por exemplo, o OpenID Connect Dynamic Client Registration 1.0 define os metadados do cliente request_object_encryption_alg e request_object_encryption_enc para a criptografia do objeto de requisição.



RSA-OAEP na seção 6.1.1 de OBB FAPI é um identificador que representa “RSAES OAEP usando parâmetros padrão”. O identificador é definido em “4.1. Valores de parâmetro de cabeçalho “alg” (Algoritmo) para JWE” do RFC 7518. Como o próprio título da seção afirma, o identificador é usado como um valor para o parâmetro alg no cabeçalho JWE. Os metadados do cliente relacionados à criptografia que terminam com _alg podem receber um identificador definido na seção. Por exemplo, os metadados do cliente id_token_encrypted_response_alg podem ser RSA-OAEP.



Da mesma forma, A256GCM na seção 6.1.1 de OBB FAPI é um identificador definido em “5.1. Valores de parâmetro de cabeçalho “enc” (algoritmo de criptografia) para JWE” de RFC 7518. Como o próprio título da seção afirma, o identificador é usado como um valor para o parâmetro enc no cabeçalho JWE. Os metadados do cliente relacionados à criptografia que terminam com _enc podem receber um identificador definido na seção. Por exemplo, os metadados do cliente userinfo_encrypted_response_enc podem ser A256GCM.



Deve-se observar que configurar metadados de cliente * _alg para criptografia não necessariamente força o aplicativo cliente a usar o algoritmo. Como mencionei anteriormente, por exemplo, mesmo se RSA-OAEP estiver definido para os metadados do cliente request_object_encryption_alg, o servidor de autorização não rejeita objetos de requisição criptografados com um algoritmo diferente. Além disso, o servidor de autorização não rejeita objetos de requisição, mesmo se eles não estiverem criptografados.



Se um servidor de autorização deseja rejeitar objetos de requisição criptografados com um algoritmo diferente do RSA-OAEP para estar em conformidade com o requisito específico do OBB estritamente, ele não pode confiar nos metadados do cliente padrão. Isso significa que o desenvolvimento personalizado ou um mecanismo dependente do fornecedor é necessário para atender ao requisito de OBB.



No caso da Authlete, o mecanismo para forçar algoritmos de criptografia para objetos de requisição é fornecido como opções “Encryption Algorithm Match” e “Encryption Encoding Algorithm Match” na seção “Request Object”, conforme mostrado abaixo.



Opções para algoritmos de criptografia de objeto de requisição



Observe que opções semelhantes para outros metadados do cliente (por exemplo, id_token_encrypted_response_alg, userinfo_encrypted_response_alg e authorization_encrypted_response_alg) não são necessários porque outros JWTs além dos objetos de requisição são criptografados por um servidor de autorização, não por um aplicativo do cliente.



Âmbito de consentimento dinâmico

Para seguir o padrão de “Lodging Intent” do UK Open Banking, o OBB definiu um fluxo específico de OBB em que um aplicativo cliente obtém um “Consent ID” da “Consent API” com antecedência e, em seguida, faz uma requisição de autorização com o Consent ID. Ou seja, uma etapa extra é necessária antes de iniciar o fluxo tradicional do OAuth 2.0. O diagrama abaixo mostra o fluxo.



Chamada de API de consentimento + requisição de autorização



Se PAR for usado, mais uma etapa extra é inserida conforme o diagrama abaixo ilustra.


Chamada de API de consentimento + Requisição de PAR + Requisição de autorização



Em ambos os casos, o ID de consentimento emitido é incorporado ao parâmetro de requisição de scope da chamada de API subsequente. Quando está incorporado, o prefixo consent: é acrescentado. Por exemplo, quando o ID de consentimento emitido é urn: bancoex: C1DD33123, consent: urn: bancoex: C1DD33123 é incluído no parâmetro de requisição de escopo como um valor de scope.


Os servidores de autorização para OBB devem ser capazes de reconhecer o Dynamic Consent Scope, que tem o formato de consent: {ConsentID}. Consulte “7.1. Mecanismo de autorização” da especificação OBB FAPI para obter detalhes.



Registro de cliente dinâmico OBB

Stack de Especificação

O OBB publicou o “Open Banking Brasil Financial-grade API Dynamic Client Registration 1.0 Implementers Draft 1” (denominado “OBB DCR”) no final de maio de 2021. No momento em que este documento foi escrito, a especificação foi atualizada desde então, conforme as especificações OBB FAPI.

Existem três padrões relacionados ao “Dynamic Client Registration” (denominado “DCR”), conforme listado abaixo.




A especificação OBB DCR é construída sobre essas especificações padrão.



Cadastro de clientes dinâmicos do Open Banking Brasil no topo dos padrões



Noções básicas de registro de cliente dinâmico

Um servidor de autorização que oferece suporte a DCR fornece uma API da Web chamada “Client Registration Endpoint”. O endpoint aceita JSON incluindo metadados do cliente, registra os metadados em seu banco de dados e emite um client ID que corresponde aos metadados registrados. O ID do cliente emitido pode ser usado como um valor para o parâmetro de requisição client_id de solicitações de autorização, solicitações de token e assim por diante.




Terminal de registro de cliente



“2. Client Metadata do OIDR define muitos metadados de cliente padrão, como client_name e redirect_uris. O RFC 7591 também possui uma seção intitulada “2. Client Metadata”. E várias outras especificações definem os metadados do cliente conforme necessário.



Um mecanismo interessante, mas complexo, que a RFC 7591 introduziu, é a “software statement”. É um JWT cuja carga útil lista os metadados do cliente. Uma requisição de registro de cliente pode incluir uma declaração de software com outros metadados de cliente. Os metadados do cliente dentro da declaração do software e os externos são mesclados quando registrados. Se os metadados do cliente com o mesmo nome existirem dentro e fora da instrução do software, o interno terá precedência.



Requisição de registro do cliente usando uma declaração de software



Requisitos de descoberta de OBB


“6.1. Authorization server” da especificação OBB DCR lista os requisitos para o endpoint de descoberta. Entre eles, um ponto que chama a atenção dos implementadores é que os metadados do servidor mtls_endpoint_aliases são obrigatórios.


Os metadados do servidor mtls_endpoint_aliases são definidos em “RFC 8705: OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens”. Seu valor é um objeto JSON que contém pares de um nome de terminal e sua localização. A seguir está o exemplo mostrado em “5. Metadados para Mutual-TLS Endpoint Aliases” do RFC 8705.



Exemplo de metadados de servidor mtls_endpoint_aliases



Quando um servidor de autorização deseja oferecer suporte (a) métodos de autenticação de cliente que utilizam um certificado de cliente (tls_client_auth e self_signed_tls_client_auth) e / ou (b) tokens de acesso vinculados a certificado, as conexões entre os aplicativos cliente e os terminais do servidor devem ser "mutual TLS". Isso significa que o administrador do servidor configura os terminais para que eles solicitem um certificado de cliente durante um handshake TLS. Nesse caso, o discovery document do servidor de autorização pode listar os nomes e locais dos endpoints nos metadados do servidor mtls_endpoint_aliases.



No RFC 8705, o uso dos metadados do servidor mtls_endpoint_aliases é opcional, mesmo se os terminais exigirem um certificado de cliente durante um handshake TLS. Por outro lado, os metadados do servidor são obrigatórios na especificação OBB DCR.



Depende de cada implementação, como incluir os metadados do servidor mtls_endpoint_aliases no documento de descoberta. A implementação mais simples permitirá que o administrador edite um arquivo estático que é o próprio discovery document do servidor de autorização. Outros podem fornecer outros meios. No caso da Authlete, a GUI para edição de entradas dos metadados do servidor mtls_endpoint_aliases é fornecida como abaixo.



Configuração de aliases de endpoint MTLS




Requisitos de registro de cliente dinâmico OBB


“7.1. Servidor de autorização” da especificação OBB DCR lista os requisitos para DCR. Vamos lê-los um por um.



OBB DCR 1.0, 7.1. Servidor de autorização, Cláusula 1


deve rejeitar solicitações de registro de cliente dinâmico não realizadas em uma conexão protegida com tls mútuos usando certificados emitidos pelo Brasil ICP (produção) ou o Diretório de Participantes (sandbox);



Em uma conexão TLS mútua, o servidor e o cliente enviam seus certificados X.509 um para o outro. No ecossistema OBB, tais certificados devem ser emitidos por um emissor específico (Brasil ICP ou Sandbox). Leia “Certificado X.509 ilustrado” se não estiver familiarizado com os certificados X.509.



OBB DCR 1.0, 7.1. Servidor de autorização, Cláusula 2


deve validar que a requisição contém software_statement JWT assinado usando o algoritmo PS256 emitido pela lista de participantes do Open Banking Brasil;



As solicitações de DCR no OBB devem conter uma declaração de software emitida pelo Open Banking Brasil Directory. Isso significa que o chamador da API deve obter uma declaração de software com antecedência antes de fazer uma requisição DCR.



As implementações do Endpoint de registro do cliente devem validar a declaração do software incluída em uma requisição DCR. A parte mais importante da validação é confirmar que a declaração do software foi assinada pelo Diretório OBB.



Para verificar a assinatura da declaração do software, o verificador (a implementação do Client Registration Endpoint neste contexto) deve obter a chave pública que corresponde à chave pública que foi usada para gerar a assinatura.



A chave pública está incluída no JWK Set Document (RFC 7517: JSON Web Key (JWK) exposto por meio do ponto final de conjunto JWK do diretório.

O diagrama abaixo ilustra as etapas desde a emissão de uma declaração de software até a verificação da assinatura da declaração de software.



Verificação da Assinatura da Declaração de Software



OBB DCR 1.0, 7.1. Servidor de autorização, cláusula 3


deve validar que o software_statement foi emitido (iat) não mais do que 5 minutos antes do pedido ser recebido;


Por definição, o formato da parte da carga útil de um JWT é JSON. As entradas na parte da carga útil são chamadas de “claims”. A especificação JWT (RFC 7519: JSON Web Token) define algumas claims padrão. A claim iat é uma delas e representa a época em que o JWT foi emitido. O valor é o número de segundos decorridos desde a época do Unix (1º de janeiro de 1970). O snippet a seguir mostra a aparência da claim iat.





A especificação OBB DCR requer que um servidor de autorização confirme se o valor da claim iat na declaração do software está no intervalo entre 5 minutos atrás e a hora atual.



OBB DCR 1.0, 7.1. Servidor de autorização, cláusula 4


deve validar que um jwks (chave definida por valor) não foi incluído;


Os metadados do cliente jwks não devem ser incluídos em uma requisição DCR. O medata do cliente jwks é um padrão definido no OIDR e RFC 7591. Essas especificações afirmam que jwks e jwks_uri não devem estar presentes na mesma requisição DCR.




OBB DCR 1.0, 7.1. Servidor de autorização, cláusula 5


deve exigir e validar que o jwks_uri corresponda ao software_jwks_uri fornecido na declaração do software;


Embora os metadados do cliente jwks_uri sejam padrão, software_jwks_uri é um parâmetro personalizado para OBB que está incluído em uma claim de software emitida pelo Diretório OBB.



OBB DCR 1.0, 7.1. Servidor de autorização, cláusula 6


deve exigir e validar que redirect_uris corresponda ou contenha um subconjunto de software_redirect_uris fornecido na declaração de software;


Em outras palavras, os metadados do cliente redirect_uris não devem incluir valores que não estejam listados na claim software_redirect_uris.




OBB DCR 1.0, 7.1. Servidor de autorização, cláusula 7


deve exigir e validar que todos os mecanismos de autenticação do cliente cumpram os requisitos definidos no Financial-grade API Security Profile 1.0 - Parte 2: Avançada;


No contexto do FAPI 1.0 Advanced, os métodos de autenticação de cliente permitidos são três, conforme listado abaixo.

  • private_key_jwt (definido em RFC 7523)

  • tls_client_auth (definido em RFC 8705)

  • self_signed_tls_client_auth (definido em RFC 8705)



A sétima cláusula requer que o valor dos metadados do cliente cujo valor é um método de autenticação do cliente seja um de private_key_jwt, tls_client_auth e self_signed_tls_client_auth. Entre os metadados de cliente padrão conhecidos, token_endpoint_auth_method é o único que atende à condição.



Em resumo, o que um servidor de autorização deve fazer para a 7ª cláusula é confirmar se o valor dos metadados do cliente token_endpoint_auth_method é private_key_jwt, tls_client_auth ou self_signed_tls_client_auth.



No entanto, praticamente falando, self_signed_tls_client_auth não funcionará porque um certificado autoassinado não é permitido no OBB.



Se você quiser saber mais detalhes sobre autenticação de cliente, leia “Autenticação de cliente OAuth 2.0”.



OBB DCR 1.0, 7.1. Servidor de autorização, cláusula 8


exigirá objetos de requisição criptografados conforme exigido pelo Perfil de Segurança do Brasil Open Banking;


No contexto do DCR, “deve exigir objetos de requisição criptografados” significa que os metadados do cliente request_object_encryption_alg e os metadados do cliente request_object_encryption_enc devem ser configurados corretamente.


Se uma requisição DCR contiver esses metadados de cliente, seus valores devem ser RSA-OAEP e A256GCM, respectivamente, conforme exigido pela especificação OBB FAPI.


Por outro lado, se uma requisição DCR não os contiver, a implementação do Terminal de Registro do Cliente deve complementar a requisição DCR com "request_object_encryption_alg": "RSA-OAEP" e "request_object_encryption_enc":"A256GCM"



OBB DCR 1.0, 7.1. Servidor de autorização, Cláusula 9


deve validar se os escopos solicitados são apropriados para as funções regulatórias autorizadas do software;


Uma declaração de software emitida pelo OBB Directory contém a claim software_roles como abaixo.




“7.2. Funções regulatórias para mapeamentos OpenID e OAuth 2.0” tem uma tabela que mostra quais escopos são permitidos para cada função regulatória que pode aparecer na claim software_roles.


Os valores listados nos metadados do cliente de scope devem ser verificados com a tabela. No entanto, a lógica de validação não é clara, especialmente em casos onde várias funções são listadas e onde os valores de escopo não listados na tabela estão incluídos.



OBB DCR 1.0, 7.1. Servidor de autorização, cláusula 10


deve, sempre que possível, validar os metadados declarados pelo cliente em relação aos metadados fornecidos no software_statement;


Provavelmente, isso significa que deve ser verificado se os valores correspondem quando os metadados do cliente com o mesmo nome existem dentro e fora da instrução do software.


Em qualquer caso, a RFC 7519 requer “os valores de metadados do cliente transmitidos na declaração do software DEVEM prevalecer sobre aqueles transmitidos usando elementos JSON simples”.



OBB DCR 1.0, 7.1. Servidor de autorização, cláusula 11


deve aceitar todas as strings de nomes de AttributeType x.500 definidas no Nome Distinto dos Perfis de Certificados x.509 definidos nos Padrões de Certificados Open Banking Brasil x.509;


“Strings de nomes de AttributeType”, também chamados de “descriptors”, são apelidos de OIDs (Identificadores de Objeto). Por exemplo, a string de nome de AttributeType “CN” é um apelido do OID “2.5.4.3”.



“3. Analisando uma string de volta a um nome distinto” de “RFC 4514: Protocolo de acesso a diretórios leve (LDAP): Representação de string de nomes distintos” (que foi publicado em junho de 2006) requer que os seguintes descritores sejam reconhecidos.


  • CN2.5.4.3 (commonName)

  • L2.5.4.7 (localityName)

  • ST2.5.4.8 (stateOrProvinceName)

  • O2.5.4.10 (organizationName)

  • OU2.5.4.11 (organizationalUnitName)