| Índice | ||||
|---|---|---|---|---|
|
Prefácio
The normative version in English
...
Estas partes são destinados a serem usados com RFC6749, RFC6750, RFC7636, OIDC, FAPI-1-Baseline e FAPI-1-Advanced
Introdução
A Financial-grade API do Open Finance Brasil é um perfil OAuth altamente seguro que visa fornecer diretrizes de implementação específicas para segurança e interoperabilidade que podem ser aplicadas a APIs na área de Open Finance do Brasil que requerem um nível de privacidade superior ao fornecido pelo padrão Financial-grade API Security Profile 1.0 - Part 2: Advanced. Entre outras melhorias, esta especificação aborda considerações de privacidade identificadas em FAPI-1-Advanced que são relevantes nas especificações do Open Finance Brasil, mas não foram, até agora, exigidas por outras jurisdições.
Embora seja possível codificar um provedor de OpenID e parte de confiança a partir dos primeiros princípios usando esta especificação, o público principal para esta especificação são as partes que já possuem uma implementação certificada do Financial-grade API Security Profile 1.0 - Part 2: Advanced e deseja obter a certificação para o programa Brasil Open Finance.
Convenções Notacionais
As palavras-chave "deve" (shall), "não deve" (shall not), "deveria" (should), "não deveria" (should not) e "pode" (may) presentes nesse documento devem ser interpretadas conforme as diretrizes descritas em ISO Directive Part 2 observando seguinte equivalência:
...
Estas palavras-chave não são usadas como termos de dicionário, de modo que qualquer ocorrência deles deve ser interpretada como palavras-chave e não devem ser interpretados com seus significados de linguagem natural.
1. Escopo
Este documento especifica o método para os aplicativos
...
Este documento é aplicável a todos os participantes do Open Finance no Brasil.
2. Referências normativas
Os seguintes documentos referenciados são indispensáveis para a adoção das especificações deste documento. Para referências datadas, apenas a edição citada se aplica. Para referências não datadas, deve-se aplicar a última edição do documento referenciado (incluindo quaisquer emendas).
...
RFC4648 - The Base16, Base32, and Base64 Data Encodings
3. Termos e definições
Para efeitos deste documento, os termos definidos em RFC6749, RFC6750, RFC7636, OpenID Connect Core e ISO29100 se aplicam.
4. Símbolos e termos abreviados
API - Application Programming Interface (Interface de programação de aplicativo)
CSRF - Cross Site Request Forgery
DCR - Registro de cliente dinâmico
EIOFB - Estrutura Inicial do Open Finance Brasil
FAPI - Financial-grade API
HTTP - Protocolo de transferência de hipertexto
MFA - Multi-Factor Authentication (Autenticação por Múltiplos Fatores)
OIDF - OpenID Foundation
REST - Representational State Transfer (Transferência de Estado Representacional)
TLS - Transport Layer Security (Segurança da Camada de Transporte)
5. Profile de Segurança para o Open Finance Brasil
5.1. Introdução
O perfil de segurança do Open Finance Brasil especifica requisitos adicionais de segurança e de identificação para o acesso a API's com recursos críticos protegidas pelo OAuth 2.0 Authorization Framework, que consiste em RFC6749, RFC6750, RFC7636, FAPI-1-Baseline, FAPI-1-Advanced e outras especificações.
...
ataques que abordam considerações de privacidade identificadas na cláusula 9.1 de [FAPI-1 Advanced].
o requisito de concessão de acesso granular a recursos, com vistas à minimização de dados;
o requisito de informar sobre o contexto da autenticação do usuário (claim Authentication Context Request - acr) que foi realizada por um Provedor OpenID, com vistas a favorecer o adequado gerenciamento do risco decorrente do acesso do usuário;
5.2. Disposições de segurança do Open Finance Brasil
5.2.1. Introdução
O Open Finance Brasil tem um requisito para endereçar considerações de privacidade que foram identificadas, mas não abordadas na especificação final FAPI-1-Advanced, sem impor requisitos adicionais aos Servidores de Autorização que estão sendo propostos em FAPI-2-Baseline.
...
Como um perfil do OAuth 2.0 Authorization Framework, este documento exige o seguinte para o perfil de segurança do Open Finance Brasil.
5.2.2. Servidor de Autorização
O Servidor de Autorização deve suportar as disposições especificadas na cláusula 5.2.2 de Financial-grade API Security Profile 1.0 - Parte 2: Advanced.
...
deve realizar a autenticação do cliente utilizando private_key_jwt;
deve exigir requisições do tipo "pushed authorization requests" PAR;
deve publicar metadados de descoberta (incluindo a do endpoint de autorização) por meio do documento de metadado especificado em OIDD e [RFC8414] (".well-known");
deve suportar os parâmetros claims como definido no item 5.5 do OpenID Connect Core;
deve suportar o atributo acr "urn:brasil:openbanking:loa2" como definido no item 5.2.2.3;
deveria suportar o atributo acr "urn:brasil:openbanking:loa3" como definido no item 5.2.2.3;
deve implementar o endpoint "userinfo" como definido no item 5.3 do OpenID Connect Core;
deve suportar o escopo parametrizável ("parameterized OAuth 2.0 resource scope") consent como definido no item 6.3.1 de OIDF FAPI WG Lodging Intent Pattern;
pode suportar Financial-grade API: Client Initiated Backchannel Authentication Profile;
(requisito temporariamente retirado);
deve suportar refresh tokens;
deve emitir access tokens com o tempo de expiração entre 300 (mínimo) e 900 (máximo) segundos;
deve sempre incluir a claim acr no id_token;
deve suportar os valores code e id_token para o atributo response_type;
não deve permitir o recurso de rotação de refresh tokens;
deve garantir que em caso de compartilhamento do Servidor de Autorização para outros serviços, além do Open Finance, não divulgue e/ou possibilite o uso de métodos não certificados no ambiente do Open Finance;
deve garantir que as configurações divulgadas aos demais participantes através do OpenID Discovery (indicado pelo arquivo de Well-Known cadastrado no Diretório) sejam restritos aos modos de operação aos quais a instituição se certificou;
deve manter em suas configurações os métodos para os quais ainda haja clientes ativos;
deve atualizar os cadastros que utilizem métodos não certificados, através de tratamento bilateral entre as instituições envolvidas;
deve recusar requisições, para o ambiente do Open Finance, que estejam fora dos modos de operação ao qual a instituição certificou seu Servidor de Autorização;
o tempo mínimo de expiração do request_uri deve ser de 60 segundos;
deve recusar requisições que não apresentem o cabeçalho x-fapi-interaction-id em endpoints de recursos protegidos;
deve exigir a utilização de Proof Key for Code Exchange (PKCE);
deve exigir a utilização do subject_type “public”;
deve exigir a utilização do response_mode “fragment”;
Deve emitir refresh_tokens exclusivamente do tipo opaco e sem prazo de validade associado.
5.2.2.1. Token de ID como assinatura separada
O Servidor de Autorização deve suportar as disposições especificadas na cláusula 5.2.2.1 de Financial-grade API Security Profile 1.0 - Parte 2: Advanced
Deve obrigatoriamente criptografar o id_token nos momentos de call-back e chamada do endpoint de token
Para a criptografia do id_token deve ser utilizada chave disponível no JWKS informado no parâmetro jwks_uri, com o atributo “use”:”enc”, durante o registro do cliente, indicada através do cabeçalho kid do documento JWT;
O uso de outros cabeçalhos para indicação da chave utilizada, como x5u, x5c, jku ou jkw é vetado conforme definido na cláusula 2 OIDC.
5.2.2.2. Clarificações sobre a "sub" Claim
Este perfil usa a definição oficial encontrada em: Analise requisitos de criptografia ID_TOKEN. Isso significa que o sub é um identificador nunca transferido ou alterado para o usuário final dentro da emissora (detentora/transmissora).
5.2.2.3. Solicitando o "urn:brasil:openbanking:loa2" ou "urn:brasil:openbanking:loa3" Solicitação de contexto de autenticação
Esse perfil define "urn:brasil:openbanking:loa2" e "urn:brasil:openbanking:loa3" como novas classes de "Authentication Context Request" (ACR)
...
Para realizar autenticação por múltiplos fatores (MFA) é necessário que o usuário apresente, ao menos, dois diferentes fatores dos listados acima. Um mesmo fator usado mais de uma vez - por exemplo, a apresentação de suas senhas que ele conhece - não pode ser aceito como MFA.
5.2.2.4 Escopos obrigatórios no endpoint de descoberta (well-known)
O servidor de autorização deve obrigatoriamente declarar os escopos abaixo em seu endpoint de descoberta (well-known), independentemente se a instituição forneça ou não os produtos referentes aos escopos abaixo listados:
...
Os escopos não listados acima devem ser declarados caso a instituição forneça produtos referentes aos mesmos (ex: accounts, payments).
5.2.3. Cliente confidencial
Um cliente confidencial deve apoiar as disposições especificadas na cláusula 5.2.3 de Financial-grade API Security Profile 1.0 - Part 2: Advanced,
...
deve suportar objetos de solicitação encrypted;
deve suportar solicitações de autorização push (pushed authorization requests) PAR;
deve suportar o escopo de recurso OAuth 2.0 parametrizado consent conforme definido na cláusula 6.3.1 OIDF FAPI WG Lodging Intent Pattern;
deve suportar refresh tokens;
não deve incluir um valor específico na claim acr;
deve definir a claim acrcomo essential;
deve suportar todos os métodos de autenticação especificados no item 14 da seção 5.2.2 da Financial-grade API Security Profile 1.0 - Part 2: Advanced incluindo as diferentes combinações de métodos de encaminhamento dos Requests Objects (usando ou não PAR - item 11);
não deve permitir o recurso de rotação de refresh tokens;
deve enviar o cabeçalho x-fapi-interaction-id em endpoints FAP
6. Considerações de segurança
Os participantes devem apoiar todas as considerações de segurança especificadas na cláusula 8 Financial-grade API Security Profile 1.0 - Parte 2: Advanced e o Manual de Segurança de Banco Central do Brasil. O ICP Brasil emite certificados RSA x509 somente, portanto, para simplificar, a seção remove o suporte para algoritmos EC e exige que apenas algoritmos de criptografia recomendados pela IANA sejam usados.
6.1. Considerações sobre assinatura do conteúdo de mensagens (JWS)
Para garantir a integridade e o não-repúdio das informações tramitadas em API's sensíveis e que indicam essa necessidade na sua documentação, deve ser adotado a estrutura no padrão JWS definida na RFC7515 e que inclui:
...
O receptor deve validar a consistência da assinatura digital da mensagem JWS exclusivamente com base nas informações obtidas do diretório, ou seja, com base nas chaves publicadas no JWKS da instituição no diretório.
As assinaturas devem ser realizadas com uso do certificado digital de assinatura especificado no Padrão de Certificados Open Finance Brasil;
A claim iat deve ser numérica no formato Unix Time GMT+0 com tolerância de +/- 60 segundos;
A claim do jti deve ser única para um clientId dentro de um intervalo de tempo de 86.400 segundos (24h), não podendo ser reutilizada neste período. Em caso de reutilização, deverá ser retornado o código de erro HTTP 403. Demais casos seguir instrução da RFC 6749, item 5.2;
6.1.1. Considerações sobre algoritmos de assinatura
Para JWS, clientes e servidores de autorização
devem usar o algoritmo PS256;
6.1.2. Considerações de algoritmo de criptografia
Para JWE, clientes e servidores de autorização
devem usar RSA-OAEP com A256GCM
6.1.3. Considerações sobre o uso seguro do Transport Layer Security
Para TLS, endpoints do Servidor de Autenticação e endpoints do Servidor de Recursos usados diretamente pelo cliente:
devem suportar TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
devem suportar TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
As funcionalidades "TLS Session Resumption" e "TLS Renegotiation" devem ser desabilitadas
7. Considerações sobre compartilhamento de dados
7.1. Mecanismo de Autorização
7.1.1. Introdução
Os mecanismos existentes para gerenciar adequadamente o acesso aos recursos definidos em RFC6749 são insuficientes para atender aos requisitos de um ecossistema de compartilhamento de dados moderno. Aproveitar strings de escopo estático não fornece aos consumidores controle de granularidade suficiente para compartilhar com terceiros. O Open Finance Brasil optou por implementar uma API de consentimento como um recurso protegido OAuth 2.0 que pode ser usado para gerenciar o acesso granular aos recursos. A referência ao recurso de consentimento será transmitida como parte de um escopo de recurso dinâmico OAuth 2.0.
7.1.2. Definição de Escopo de Consentimento Dinâmico
Este perfil define o escopo dinâmico do OAuth 2.0 "consentimento" da seguinte maneira:
...
Consent Resource Id deve incluir caracteres seguros para url;
Consent Resource Id deve ser "namespaced";
Consent Resource Id deve ter propriedades de um nonce Nonce;
7.1.3. Exemplo de escopo de consentimento dinâmico
consent:urn:bancoex:C1DD33123
7.2. Ciclo de vida da autorização
7.2.1. Introdução
O recurso de consentimento tem um ciclo de vida gerenciado separada e distintamente da estrutura de autorização OAuth 2.0. As transições de estado e comportamentos esperados e condições de erro esperados dos Recursos REST protegidos com este perfil são definidos nas especificações funcionais da API publicadas pelo Open Finance Brasil.
7.2.2. Servidor de autorização
Além dos requisitos descritos nas disposições de segurança do Open Finance Brasil, o Servidor de Autorização
deve apenas emitir refresh_tokens quando vinculados a um consentimento ativo e válido;
Não deve emitir refresh_token quando o consentimento estiver no status “CONSUMED” (para fase 3);
Deve emitir um access_token por meio de um grant_type do tipo client credentials no status “CONSUMED” (para fase 3).
só deve compartilhar o acesso aos recursos quando apresentado access_token vinculado a um consentimento ativo e com o status "AUTHORISED“. Para tokens gerados com o scope: payments, o status do consentimento não será validado.;
No cenário de recebimento de token inválido, deve ser retornado status code 401.
deve revogar os refresh tokens e, quando aplicável, os access tokens quando o Consentimento (Consent Resource) relacionado for apagado;
deve garantir que os access tokens são emitidos com os scopes necessários para permitir acesso aos dados especificados em elemento Permission do Consentimento (Consent Resource Object) relacionado;
não deve rejeitar pedido de autorização com scopes além do necessário para permitir acesso a dados definidos em elemento Permission do Consentimento (Consent Resource Object) relacionado;
pode reduzir o escopo solicitado para um nível que seja suficiente para permitir o acesso aos dados definidos em elemento Permission do Consentimento (Consent Resource Object) relacionado;
deve manter registros sobre o histórico dos consentimento para permitir a adequada formação de trilhas de auditoria em conformidade com a regulação em vigor;
deve retornar falha na autenticação e o código de retorno _accessdenied no parâmetro erro (como especificado na seção 4.1.2.1 da RFC6749) caso o CPF do usuário autenticado não seja o mesmo indicado no elemento loggedUser do Consentimento (Consent Resource Object);
deve retornar falha na autenticação e o código de retorno _accessdenied no parâmetro erro (como especificado na seção 4.1.2.1 da RFC6749) caso o elemento businessEntity não tenha sido preenchido no Consentimento (Consent Resource Object) relacionado e o usuário tenha selecionado ou se autenticado por meio de credencial relacionada à conta do tipo Pessoa Jurídica (PJ);
deve condicionar a autenticação ou seleção de contas do tipo PJ à consistência entre o CNPJ relacionado à(s) conta(s) e o valor presente no elemento businessEntity do Consentimento (Consent Resource Object). Em caso de divergência deve retornar falha na autenticação e o código de retorno _accessdenied no parâmetro erro (como especificado na seção 4.1.2.1 da RFC6749);
deve emitir _refreshtoken com validade não inferior à validade do consentimento ao qual está relacionado, respeitado os demais critérios acima.
7.2.3. Cliente confidencial
Além dos requisitos descritos nas disposições de segurança do Open Finance Brasil, o Cliente Confidencial
deve, sempre que possível, revogar e cessar o uso de refresh e de access tokens vinculados a um consentimento (Consent Resource Object) que foi excluído;
deve excluir consentimentos (Consent Resource Objects) que estão expirados;
8. Reconhecimentos
Agradecemos a todos que estabeleceram as bases para o compartilhamento seguro e seguro de dados por meio da formação do Grupo de Trabalho FAPI da OpenID Foundation, o GT de Segurança do Open Finance Brasil e aos pioneiros que ficarão em seus ombros.
...
Alexandre Siqueira (Mercado Pago)
Joseph Heenan (Authlete)
Marcos Rodrigues (Itaú)
Mário Ginglass (BNDES)
Nic Marcondes (Quanto)
Ralph Bragg (Raidiam)
Appendix A. Avisos
Copyright (c) 2023 Estrutura Inicial do Open Finance Brasil
...
A tecnologia descrita nesta especificação foi disponibilizada a partir de contribuições de várias fontes, incluindo membros da OpenID Foundation, do Grupo de Trabalho de Segurança do Open Finance Brasil e outros. Embora a Estrutura Inicial do Open Finance Brasil tenha tomado medidas para ajudar a garantir que a tecnologia esteja disponível para distribuição, ela não toma posição quanto à validade ou escopo de qualquer propriedade intelectual ou outros direitos que possam ser reivindicados como pertencentes à implementação ou uso do tecnologia descrita nesta especificação ou até que ponto qualquer licença sob tais direitos pode ou não estar disponível; nem representa que fez qualquer esforço independente para identificar tais direitos. A Estrutura Inicial do Open Finance Brasil e os contribuidores desta especificação não oferecem (e por meio deste expressamente se isentam de quaisquer) garantias (expressas, implícitas ou de outra forma), incluindo garantias implícitas de comercialização, não violação, adequação a uma finalidade específica ou título, relacionados a esta especificação, e todo o risco quanto à implementação desta especificação é assumido pelo implementador. A política de Direitos de Propriedade Intelectual do Open Finance Brasil exige que os contribuidores ofereçam uma promessa de patente de não fazer valer certas reivindicações de patentes contra outros contribuidores e implementadores. A Estrutura Inicial do Open Finance Brasil convida qualquer parte interessada a trazer à sua atenção quaisquer direitos autorais, patentes, pedidos de patentes ou outros direitos de propriedade que possam abranger a tecnologia que possa ser necessária para praticar esta especificação.
Author's Address
OFBIS GT Security
Open Finance Brasil Initial Structure
...