OBB-FAPI-1-ID1 June 2021
Bragg & Security Standards Track [Page]
Workgroup:
Open Banking Brasil GT Security
Internet-Draft:
open-banking-brasil-financial-api-1_ID1-ptbr
Published:
Intended Status:
Standards Track
Authors:
R. Bragg
Raidiam
GT. Security
OBBIS

Open Banking Brasil Financial-grade API Security Profile 1.0 Implementers Draft 1

Prefácio

The normative version in English.

A Estrutura Inicial do Open Banking Brasil (EIOBB) é responsável por criar padrões e especificações necessárias para atender aos requisitos e obrigações da Legislação do Open Banking do Brasil, conforme originalmente delineado pelo Banco Central do Brasil. É possível que alguns dos elementos deste documento estejam sujeitos a direitos autorais ou patenteados. O EIOBB não se responsabiliza pela identificação de qualquer ou todos esses direitos.

O Financial-grade API 1.0 do Open Banking Brasil consiste nas seguintes partes:

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 Banking 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 Banking 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 Banking 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 Banking.

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.

Table of Contents

1. Escopo

Este documento especifica o método para os aplicativos

Este documento é aplicável a todos os participantes do Open Banking 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).

ISODIR2 - ISO/IEC Directives Part 2

RFC6749 - The OAuth 2.0 Authorization Framework

RFC6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage

RFC7636 - Proof Key for Code Exchange by OAuth Public Clients

RFC6819 - OAuth 2.0 Threat Model and Security Considerations

RFC7519 - JSON Web Token (JWT)

RFC7591 - OAuth 2.0 Dynamic Client Registration Protocol

RFC7592 - OAuth 2.0 Dynamic Client Registration Management Protocol

BCP195 - Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)

OIDC - OpenID Connect Core 1.0 incorporating errata set 1

FAPI-CIBA - Financial-grade API: Client Initiated Backchannel Authentication Profile

OIDD - OpenID Connect Discovery 1.0 incorporating errata set 1

OIDR - OpenID Connect Registration 1.0 incorporating errata set 1

RFC8705 - OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens

JARM - Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)

PAR - OAuth 2.0 Pushed Authorization Requests

JAR - OAuth 2.0 JWT Secured Authorization Request

FAPI-1-Baseline - Financial-grade API Security Profile 1.0 - Part 1: Baseline

FAPI-1-Advanced - Financial-grade API Security Profile 1.0 - Part 2: Advanced

FAPI-2-Baseline - Financial-grade API Security Profile 2.0 - Part 1: Baseline

LIWP - OIDF FAPI WG Lodging Intent Working Paper

OBB-FAPI-DCR - Open Banking Brasil Financial-grade API Dynamic Client Registration Profile 1.0

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)

EIOBB - Estrutura Inicial do Open Banking Brasil

CSRF - Cross Site Request Forgery

DCR - Registro de cliente dinâmico

FAPI - Financial-grade API

HTTP - Protocolo de transferência de hipertexto

OIDF - OpenID Foundation

REST - Representational State Transfer (Transferência de Estado Representacional)

TLS - Transport Layer Security (Segurança da Camada de Transporte)

MFA - Multi-Factor Authentication (Autenticação por Múltiplos Fatores)

5. Profile de Segurança para o Open Banking Brasil

5.1. Introdução

O perfil de segurança do Open Banking 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.

Este perfil descreve as capacidades e os recursos de segurança que devem ser oferecidos por servidores e clientes que são necessários para o Programa do Open Banking Brasil, definindo as medidas para mitigar ou endereçar:

  • 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;

  • o requisito para que os clientes de API declarem um relacionamento prévio com o usuário, afirmando em uma claim de identificação do usuário como parte do fluxo de autorização.

5.2. Disposições de segurança do Open Banking Brasil

5.2.1. Introdução

O Open Banking 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.

Os participantes desse ecossistema precisam que os clientes de API solicitem a um provedor openid a confirmação dos valores das claims de identificação do usuário como parte de uma solicitação de autorização usando o mecanismo definido na cláusula 5.5.1 de OIDC.

O uso do parâmetro claims para solicitar a validação de valores de identificação explícitos requer que os clientes de API protejam com criptografia o Request Object para evitar vazamento de informações. Este risco é identificado na cláusula 7.4.1 do FAPI-1-Advanced.

Além disso, este perfil descreve o escopo específico, valores de acr e requisitos de gerenciamento de clientes necessários para dar suporte ao ecossistema Open Banking Brasil mais amplo.

Como um perfil do OAuth 2.0 Authorization Framework, este documento exige o seguinte para o perfil de segurança do Open Banking 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.

Além disso, ele deve:

  1. deve suportar Request Objects JWE assinados e criptografados passados por valor ou deve exigir requisições do tipo "pushed authorization requests" PAR

  2. 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")

  3. deve suportar os parâmetros claims como definido no item 5.5 do OpenID Connect Core

  4. deve suportar o atributo claim padrão oidc "cpf" conforme definido no item 5.2.2.2 deste documento

  5. deve suportar o atributo claim padrão oidc "cnpj" conforme definido no item 5.2.2.3 deste documento, se a instituição for detentora de conta para pessoas jurídicas

  6. deve suportar o atributo acr "urn:brasil:openbanking:loa2" como definido no item 5.2.2.4 deste documento

  7. deveria suportar o atributo acr "urn:brasil:openbanking:loa3" como definido no item 5.2.2.4 deste documento

  8. deve implementar o endpoint "userinfo" como definido no item 5.3 do OpenID Connect Core

  9. 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

  10. pode suportar Financial-grade API: Client Initiated Backchannel Authentication Profile

  11. deve suportar Financial-grade API: Client Initiated Backchannel Authentication Profile se suportar o scope payments

  12. deve suportar refresh tokens

  13. deve emitir access tokens com o tempo de expiração entre 300 (mínimo) e 900 (máximo) segundos.

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

Além disso, se o valor response_type code id_token for usado, o servidor de autorização:

  1. não deveria retornar Informação de Identificação Pessoal (PII) confidenciais no token de ID na resposta de autorização, mas se for necessário, então ele deve criptografar o token de ID.

5.2.2.2. Solicitando uma "claim" cpf

Este perfil define "cpf" como uma nova claim padrão de acordo com cláusula 5.1 OIDC

O número do CPF (Cadastro de Pessoas Físicas, [sepeˈɛfi]; português para "Registro de Pessoas Físicas") é o cadastro de pessoa física brasileira. Este número é atribuído pela Receita Federal Brasileira para brasileiros e estrangeiros residentes que, direta ou indiretamente, pagar impostos no Brasil.

No modelo de identidade do Open Banking Brasil, o cpf é uma string composta por números 11 caracteres de comprimento e podem começar com 0.

Se a Claim cpf for solicitada como essencial para constar no ID token ou na resposta ao endpoint de UserInfo e na solicitação constar no parâmetro value com determinado CPF exigido, o Authorization Server DEVE retornar no atributo cpf o valor que corresponda ao da solicitação.

Se a Claim cpf for solicitada como essencial para constar no ID Token ou na resposta no endpoint de UserInfo, o Authorization Server deve retornar no atributo cpf o valor com o CPF do usuário autenticado.

Se a Claim cpf indicada como essencial não puder ser preenchida ou não for compatível com o requisito, o Authorization Server deve tratar a solicitação como uma tentativa de autenticação com falha.

Nome: cpf, Tipo: String, Regex: 'd{11}$'

5.2.2.3. Solicitando a "claim" cnpj

Este perfil define "cnpj" como uma nova reivindicação padrão de acordo com cláusula 5.1 OIDC

CNPJ, abreviação de Cadastro Nacional de Pessoas Jurídicas, é um número de identificação de empresas brasileiras emitidas pelo Ministério da Fazenda brasileira, na "Secretaria da Receita Federal" ou "Ministério da Fazenda" do Brasil. No modelo de identidade do Open Banking Brasil, pessoas físicas podem se associar a 0 ou mais CNPJs. Um CNPJ é uma string que consiste em números de 14 dígitos e pode começar com 0, os primeiros oito dígitos identificam a empresa, os quatro dígitos após a barra identificam a filial ou subsidiária ("0001" padrão para a sede), e os dois últimos são dígitos de soma de verificação. Para este perfil, o pedido de cnpj deve ser solicitado e fornecido como o número de 14 dígitos.

Se a Claim cnpj for solicitada como essencial para constar no ID Token ou na resposta ao endpoint UserInfo e na solicitação constar, no parâmetro value, determinado CNPJ exigido, o Authorization Server DEVE retornar no atributo cnpj um conjunto de CNPJs relacionado com o usuário, um dos quais deve incluir valor que corresponda ao da solicitação.

Se a Claim cnpj for solicitada como essencial para constar no ID Token ou na resposta ao endpoint UserInfo, o Authorization Server deve incluir no ID Token ou na resposta ao endpoint UserInfo um conjunto que inclua um elemento com o número do CNPJ relacionado à conta utilizada na autenticação do usuário.

Se a Claim cnpj indicada como essencial não puder ser preenchida ou validada, o Authorization Server deve tratar a solicitação como uma tentativa de autenticação com falha.

Nome: cnpj, Tipo: Array of Strings, Array Element Regex: 'd{14}$'

5.2.2.4. Solicitando o "urn:brasil:openbanking:loa2" ou "urn:brasil:openbanking:loa3" Solicitação de contexto de autenticação
  • LoA2: mecanismo de autenticação com a adoção de um único fator

  • LoA3: mecanismo de autenticação com múltiplos fatores de autenticação

A seguinte regra deve ser adotada para o mecanismo de autenticação:

  • Para controle de acesso às API's definidas na FASE 2 (leitura de dados): os Authorization Servers das instituições transmissoras de dados devem condicionar a autenticação do usuário proprietário do dado, no mínimo, a adoção de método compatível com LoA2. A adoção de mecanismo de autenticação mais rigoroso (LoA3) fica a critério da instituição transmissora de acordo com sua avaliação de riscos.

  • Para acesso às API's das fases subsequentes (em especial pagamento): o acesso deve ser condicionado à método de autenticação compatível com LoA3 ou superior.

Esclarecimentos adicionais sobre fatores de autenticação

São fatores de autenticação: * Aquilo que você conhece, como uma senha ou frase secreta * Aquilo que você tem, como um token, smartcard ou dispositivo * Aquilo que "você é", ou seja, autenticação condicionada a apresentação de uma característica física exclusivamente sua, como a validação por biometria

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.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,

Além disso, o cliente confidencial

  1. deve suportar objetos de solicitação encrypted

  2. deve suportar solicitações de autorização push (pushed authorization requests) PAR

  3. deve usar objetos de solicitação encrypted se não usar PAR

  4. 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

  5. deve suportar refresh tokens

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 brasileiro 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 de algoritmo

Para JWS, clientes e servidores de autorização

  1. devem usar o algoritmo PS256;

6.1.1. Considerações de algoritmo de criptografia

Para JWE, clientes e servidores de autorização

  1. devem usar RSA-OAEP com A256GCM

6.1.2. 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:

  1. devem suportar TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

  2. devem suportar TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

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 Banking 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.

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 Banking Brasil.

7.2.2. Servidor de autorização

Além dos requisitos descritos nas disposições de segurança do Open Banking Brasil, o Servidor de Autorização

  1. deve apenas emitir refreshtokens_ quando vinculados a um consentimento ativo e válido;

  2. só deve compartilhar o acesso aos recursos quando apresentado accesstoken_ vinculado a um consentimento ativo e válido;

  3. deve revogar os refresh tokens e, quando aplicável, os access tokens quando o Consentimento (Consent Resource) relacionado for apagado;

  4. 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;

  5. 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;

  6. 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;

  7. 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.

7.2.3. Cliente confidencial

Além dos requisitos descritos nas disposições de segurança do Open Banking Brasil, o Cliente Confidencial

  1. 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;

  2. 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 Banking Brasil e aos pioneiros que ficarão em seus ombros.

As seguintes pessoas contribuíram para este documento:

Appendix A. Avisos

Copyright (c) 2021 Estrutura Inicial do Open Banking Brasil

A Estrutura Inicial do Open Banking Brasil (EIOBB) concede a qualquer Colaborador, desenvolvedor, implementador ou outra parte interessada uma licença de direitos autorais mundial não exclusiva, livre de royalties para reproduzir, preparar trabalhos derivados, distribuir, executar e exibir, estes Implementadores Rascunho ou Especificação Final exclusivamente para fins de (i) desenvolver especificações e (ii) implementar Rascunhos de Implementadores e Especificações Finais com base em tais documentos, desde que a atribuição seja feita ao EIOBB como a fonte do material, mas que tal atribuição o faça não indica endosso do EIOBB.

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 Banking Brasil e outros. Embora a Estrutura Inicial do Open Banking 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 Banking 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 Banking 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 Banking 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.

Authors' Addresses

Ralph Bragg
Raidiam
OBBIS GT Security
Open Banking Brasil Initial Structure