Notas de um implementador sobre Open Banking Brasil

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

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.

CN — 2.5.4.3 (commonName)
L — 2.5.4.7 (localityName)
ST — 2.5.4.8 (stateOrProvinceName)
O — 2.5.4.10 (organizationName)
OU — 2.5.4.11 (organizationalUnitName)
C — 2.5.4.6 (countryName)
STREET — 2.5.4.9 (streetAddress)
DC — 0.9.2342.19200300.100.1.25 (domainComponent)
UID — 0.9.2342.19200300.100.1.1 (userId)

Portanto, é altamente provável que seu analisador de “Distinguished Name” reconheça esses descritores.

Entre os descritores mencionados em “5.2.2. Certificado de Cliente” do “Open Banking Brasil Certificate Standards 1.0”, os seguintes não estão incluídos no RFC 4514, mas podem ser encontrados em “RFC 4519: Lightweight Directory Access Protocol (LDAP): Schema for User Applications”.

serialNumber — 2.5.4.5
businessCategory — 2.5.4.15

Por outro lado, o descritor abaixo não é encontrado em nenhuma das RFCs.

jurisdictionCountryName — 1.3.6.1.4.1.311.60.2.1.3

Seu analisador de nome distinto pode não reconhecer alguns dos descritores acima. Por exemplo, a classe X500Principal em meu ambiente Java não reconhece businessCategory e jurisdiçãoCountryName.

Mesmo se os descritores não forem reconhecidos, o analisador do “certificado X.509” não falhará. É porque os certificados X.509 usam OIDs internamente em vez de descritores. Mas, se você estiver escrevendo um programa que analisa um Nome Distinto (não um certificado X.509) diretamente, os descritores não reconhecidos causarão um problema.

Na camada de implementações OAuth / OIDC, esse tipo de problema pode ocorrer em torno do processamento dos metadados do cliente tls_client_auth_subject_dn que é definido no RFC 8705.

Quando o método de autenticação do cliente de um aplicativo cliente é tls_client_auth e os metadados do cliente tls_client_auth_subject_dn são registrados, o servidor de autorização verifica se (a) o Distinguished Name do assunto do certificado X.509 apresentado pelo aplicativo cliente corresponde (b) o pré -valor registrado dos metadados do cliente tls_client_auth_subject_dn.

Para fazer essa comparação, o servidor de autorização converte a string pré-registrada em um formato adequado para a comparação. Por exemplo, uma implementação escrita em Java pode convertê-la em uma instância X500Principal como abaixo.

Nesse momento, se o valor pré-registrado contiver descritores não reconhecidos, como jurisdictionCountryName = BR, o construtor de X500Principal lança uma exceção.

Uma maneira simples de resolver esse problema é evitar o uso de descritores não reconhecidos no valor dos metadados do cliente tls_client_auth_subject_dn e, em vez disso, usar os OIDs como 1.3.6.1.4.1.311.60.2.1.3 = BR.

Mas, para obedecer estritamente a uma frase em “2.4. Convertendo um AttributeValue de ASN.1 para uma String” de RFC 4514,

Se o AttributeType é da forma decimal com pontos, o AttributeValue é representado por um sinal numérico (‘#’ U + 0023) seguido pela codificação hexadecimal de cada um dos octetos da codificação BER do AttributeValue X.500.

seu analisador de Nome distinto pode exigir que a parte do valor seja codificada no formato de “# + hexadecimais” como #13024252.

Outra maneira é fornecer informações sobre mapeamentos do descritor para o OID para o analisador de nomes distintos. No caso do X500Principal, isso pode ser obtido escrevendo um código como o abaixo.

Em ambos os casos, a comparação deve ser realizada comparando OIDs, não descritores.

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

se for compatível com o mecanismo de autenticação do cliente tls_client_auth, conforme definido em RFC8705, deve aceitar apenas tls_client_auth_subject_dn como uma indicação do valor do assunto do certificado, conforme definido na cláusula 2.1.2 RFC8705;

O RFC 8705 requer que um e apenas um dos metadados de cliente a seguir seja registrado para o método de autenticação de cliente tls_client_auth.

tls_client_auth_subject_dn
tls_client_auth_san_dns
tls_client_auth_san_uri
tls_client_auth_san_ip
tls_client_auth_san_email

No contexto do OBB DCR, os metadados do cliente tls_client_auth_san_ * devem ser rejeitados.

Metadados de cliente personalizados

A amostra de requisição DCR mostrada na especificação OBB DCR inclui alguns metadados de cliente não padrão, como org_name e software_roles.

Depende de cada implementação se os metadados do cliente personalizado são registrados ou descartados. No caso da Authlete, os metadados do cliente personalizado são registrados apenas quando são explicitamente listados como metadados do cliente personalizado com suporte, como a seguir.

Metadados de cliente personalizados com suporte

Os metadados de cliente personalizados registrados são acessíveis como o valor da propriedade customMetadata de Client. Consulte o JavaDoc de Client.getCustomMetadata () para obter detalhes.

Propriedades de cliente específicas do fornecedor

Depende de cada implementação como definir a estrutura de dados de um aplicativo cliente. É muito provável que a estrutura de dados tenha propriedades que correspondem aos metadados do cliente padrão, mas ao mesmo tempo pode ter outras propriedades que não têm padrões correspondentes.

Para configurar as propriedades do cliente que não possuem metadados de cliente padrão correspondentes no momento do DCR, os fornecedores de soluções podem fornecer mecanismos personalizados.

No caso do Authlete, alguns metadados do cliente que possuem o prefixo authlete: são reconhecidos. Por exemplo, quando uma requisição DCR contém metadados de um cliente como abaixo,

o cliente está configurado de acordo (código de amostra → OBBDCRProcessor.java).

Além disso, o Authlete fornece um conjunto de APIs de gerenciamento de cliente (/ api / client / *) desde o início. Consulte o documento Authlete API ou o JavaDoc da biblioteca authlete-java-comon para obter detalhes. O JavaDoc está sempre atualizado; às vezes, ele contém até mesmo informações sobre novos recursos que ainda não foram implementados.

Implementação para Requisitos OBB DCR

Como os requisitos da especificação OBB DCR são muito específicos para OBB, nenhuma solução do fornecedor pode atender aos requisitos da prateleira, a menos que os fornecedores desembolsem seus produtos para desenvolver uma variante dedicada ao OBB.

Portanto, algumas ou todas as partes do Client Registration Endpoint devem ser implementadas pelos clientes. Uma das abordagens possíveis é a seguinte.

[cliente] Implemente um ponto de extremidade de Client Registration Endpoint frontal que aceite solicitações DCR de fora.
[cliente] Extraia uma declaração de software de uma requisição DCR e execute a validação específica de OBB.
[cliente] Construa uma requisição DCR mesclando os metadados do cliente dentro da instrução do software e outros externos.
[cliente] Envie a requisição DCR recém-construída (que não inclui software_statement) para o ponto de extremidade de registro do cliente do servidor de autorização (por exemplo, uma solução do fornecedor) sentado atrás.
[solução do fornecedor] Processe a requisição simplificada de DCR conforme exigido pelos padrões globais.
[cliente] Obtenha uma resposta do servidor de autorização de back-end e transmita a resposta ao chamador da API original.

O diagrama abaixo ilustra essa abordagem.

Endpoint de registro de cliente para requisitos específicos de OBB

No caso da Authlete, “Authorization Server” no diagrama é Authlete e o seu “Client Registration Endpoint” é /api/client/registration. “Frontend do cliente” é o que os clientes da Authlete devem implementar.

ClientRegistrationEndpoint.java em java-oauth-server é um código de amostra de “Client Registration Endpoint (front)”. As etapas para “realizar validação específica de OBB” e “construir uma requisição DCR incluindo nenhuma declaração de software” são implementadas em OBBDCRProcessor.java.

Implementação de amostra

java-oauth-server é uma implementação de amostra de código aberto de um servidor de autorização que usa Authlete como serviço de back-end. Inclui códigos de amostra de algumas APIs específicas de OBB.

API de contas (→ / api / obb / accounts; AccountsEndpoint.java)

API de consentimento (→ / api / obb / consents; ConsentsEndpoint.java)

API de recursos (→ / api / obb / resources; ResourcesEndpoint.java)

Além disso, o exemplo de implementação do Client Registration Endpoint (→ / api / register; ClientRegistrationEndpoint.java) faz validação específica de OBB quando uma requisição de DCR inclui uma declaração de software emitida pelo OBB Directory. A parte mais interessante está em OBBDCRProcessor.java. O código-fonte mostra como a especificação OBB DCR deve ser interpretada e implementada.

Observe que os códigos de amostra para OBB não funcionam se a versão do servidor Authlete backend for anterior a Authlete 2.2.11. Como a versão atual do Authlete no servidor compartilhado (api.authlete.com) é 2.1.x (porém, será atualizado em um futuro próximo), você não pode tentar os códigos de amostra OBB com o servidor compartilhado. Entre em contato com Authlete, Inc. (através do formulário de contato ou e-mail para sales@authlete.com) para acessar a Authlete mais recente.

Finalmente

Obrigado por ler até o fim. A Authlete já foi adotada por alguns bancos no Brasil. Por exemplo, pelo maior banco digital do mundo e pelo maior banco de investimento da América Latina. Por favor, considere o Authlete para o seu Open Banking Brasil! 🇧🇷

Autor

Takahiko Kawasaki (Authlete Inc)

Tradução e Revisão

Carol Morais (Skalena LTDA)

Customer Success

Artigo Original