Prefácio
Este documento também está disponível em inglês
A Estrutura Inicial do Open Finance Brasil é responsável por criar padrões e especificações necessários para atender aos requisitos e obrigações da Legislação do Brasil Open Finance originalmente delineada pelo Banco Central do Brasil. Existe a possibilidade de que alguns dos elementos deste documento possam estar sujeitos a direitos de patente. A OFBIS não será responsável pela identificação de qualquer ou todos esses direitos de patente.
O Open Finance Brasil Financial-grade API Security Profile 1.0 consiste nas seguintes partes:
Perfil de segurança da API de nível financeiro do Open Banking Brasil 1.0
Perfil de Cadastro Dinâmico de Clientes do Open Banking Brasil 1.0
Estas partes destinam-se a ser usadas com RFC6749, RFC6750 , RFC7636, OIDC , FAPI-1-Baseline e FAPI-1-Advanced
Introdução
O padrão de API de nível financeiro fornece um perfil para OAuth 2.0 adequado para uso em serviços financeiros. O método OAuth é um padrão utilizado pelo cliente para validar o dono do recurso em um servidor de autorização usando um redirecionamento HTTP. As partes 1 e 2 desta especificação oferecem suporte a esse modelo de interação e são adequadas para casos de uso em que o proprietário do recurso está interagindo com o cliente em um dispositivo que ele controla que tem um navegador da Web. No entanto, há muitos casos de uso para iniciar pagamentos em que o proprietário do recurso não está interagindo com o cliente dessa maneira. Por exemplo, o proprietário do recurso pode querer autorizar um pagamento em um terminal de "ponto de venda" em uma loja ou posto de combustível.
Este documento aborda o perfil CIBA (Client Initiated Backchannel Authentication) ou Fluxo de Autenticação de Backchannel Iniciado pelo Cliente OpenID Connect que oferece suporte a esse método de interação desacoplada. A especificação CIBA permite que um cliente que obtenha conhecimento de um identificador para o usuário obtenha tokens do servidor de autorização. O consentimento do usuário é dado no Dispositivo de Autenticação do usuário mediado pelo servidor de autorização. Este documento traça o perfil da especificação CIBA para alinhá-lo com as outras partes do FAPI e fornecer recomendações de segurança para seu uso com APIs que exigem segurança de nível financeiro.
Embora seja possível codificar um OpenID Provider e um Relying Party a partir dos primeiros princípios usando essa especificação, o principal público dessa especificação são as partes que já possuem uma implementação certificada de API de nível financeiro: Client Initiated Backchannel Authentication Profile e desejam obter a certificação para o programa Brasil Open Finance.
Convenções Notacionais
As palavras-chave "deve", "não deve", "não deve", "não deve", "pode" e "pode" neste documento devem ser interpretadas como descrito na Parte 2 da Diretiva ISO. Essas palavras-chave não são usadas como termos do dicionário, de modo que qualquer ocorrência delas deve ser interpretada como palavras-chave e não deve ser interpretada com seus significados de linguagem natural.
1. Escopo
Este documento especifica o método de
aplicações para obter tokens OAuth por meio de um fluxo de autenticação backchannel de forma apropriadamente segura para acesso de maior risco aos dados de uma maneira que atenda aos requisitos do Open Finance Brasil;
aplicativos que usam o OpenID Connect CIBA para sugerir a identidade do cliente;
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 aplicação deste documento. Para referências datadas, aplica-se apenas a edição citada. Para referências não datadas, aplica-se a última edição do documento referenciado (incluindo quaisquer alterações).
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
RFC7515 - JSON Web Signature (JWS)
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
FAPI-2-Advanced - Financial-grade API Security Profile 2.0 - Part 2: Advanced
FAPI-CIBA - Financial-grade API: Client Initiated Backchannel Authentication Profile
CIBA - OpenID Connect Client Initiated Backchannel Authentication Core
LIWP - OIDF FAPI WG Lodging Intent Working Paper
OBB-FAPI-DCR - Open Finance Brasil Financial-grade API Dynamic Client Registration Profile 1.0
RFC4648 - The Base16, Base32, and Base64 Data Encodings
3. Termos e definições
Para os fins deste documento, os termos definidos em RFC6749, RFC6750, RFC7636, OpenID Connect Core, CIBA e ISO29100 se aplicam.
4. Símbolos e termos abreviados
API - Application Programming Interface
OFBIS - Open Finance Brasil Initial Structure
CSRF - Cross Site Request Forgery
DCR - Dynamic Client Registration
FAPI - Financial-grade API
HTTP - Hyper Text Transfer Protocol
OIDF - OpenID Foundation
REST - Representational State Transfer
TLS - Transport Layer Security
MFA - Multi-Factor Authentication
5. Perfil de Segurança do Brasil Open Banking
5.1. Introdução
O perfil de segurança Open Finance Brasil especifica requisitos adicionais de segurança e identidade para recursos de API de alto risco protegidos pelo OAuth 2.0 Authorization Framework que consiste em RFC6749, RFC6750, RFC7636, FAPI-1-Baseline, FAPI-1-Advanced, FAPI-CIBA e outras especificações.
Este perfil descreve as provisões de segurança e recursos para um servidor e cliente que são necessárias para o programa Open Finance Brasil, definindo as medidas a serem abordadas:
o requisito de transmitir a Solicitação de Contexto de Autenticação que foi executada por um OpenID Provider a um Cliente para permitir o gerenciamento apropriado do risco de conduta do usuário pelo client.
a exigência de que os clientes afirmem um relacionamento de cliente pré-existente afirmando uma declaração de identidade do cliente como parte do fluxo CIBA.
5.2. Open Banking Brasil CIBA Provisões de segurança
5.2.1. Introdução
Open Finance Brasil tem requisito para adotar Cliente Initiated Back Channel Authentication como um meio de habilitar fluxos de trabalho de autenticação desacoplada. Além disso, esse perfil descreve o escopo específico, os requisitos de gerenciamento de clientes necessários para apoiar o ecossistema mais amplo do Open Finance Brasil.
Como um perfil do OAuth 2.0 Authorization Framework, este documento exige o seguinte para o perfil do Brasil Open Finance Security.
5.2.2. Servidor de autorização
O Servidor de Autorização deverá suportar as disposições especificadas na cláusula 5.2.2 do Financial-grade API CIBA Security Profile 1.0
Além disso, o Servidor de Autorização
distribuirá metadados de descoberta (como o ponto de extremidade de autorização) por meio do documento de metadados, conforme especificado em OIDD e [RFC8414]
deve apoiar o parâmetro de sinistros conforme definido na cláusula 5.5 OpenID Connect Core
deve apoiará o acr "urn:brasil:openbanking:loa2" conforme definido na cláusula 5.2.2.4 do FAPI-BR
deve suportar o acr "urn:brasil:openbanking:loa3" conforme definido na cláusula 5.2.2.4 do [FAPI-BR]]
deve implementar o ponto de extremidade UserInfo, conforme definido na cláusula 5.3 OpenID Connect Core
deve oferecer suporte ao consentimento de escopo de recurso OAuth 2.0 parametrizado, conforme definido na cláusula 6.3.1 OIDF FAPI WG Lodging Intent Pattern
deve suportar tokens de atualização
O tempo de aceitação do consentimento na solicitação de Autorização recebida via CIBA permanecerá o mesmo definido para o fluxo via Fluxo Híbrido, de 5 minutos
O id_token terá prazo mínimo de 180 dias
O id_token deve ser utilizado no pedido de autorização através do parâmetro “id_token_hint"
O "modo de votação" será o único modo usado para obter um token para o envio de pagamento através do endpoint bc-author.
O cancelamento do id_token será realizado pela instituição titular da conta em casos de fraude ou por razões de segurança.
Tabela de erro "HTTP 400 Bad Request":
invalid_request: A solicitação indica que está faltando um parâmetro necessário, foi incluído um valor de parâmetro inválido, foi inclui um parâmetro mais de uma vez, contém mais de um parâmetro invalido ou está malformada.
invalid_scope: O escopo solicitado é inválido, desconhecido ou malformado.
expired_id_token_hint: O “hint” do id_token fornecido na solicitação de autenticação não é válido porque já expirou.
unknown_user_id: O OpenID Provider não é capaz de identificar qual usuário final o Cliente deseja ser autenticado por meio do “hint” fornecido na solicitação (id_token_hint).
unauthorized_client: O Cliente não está autorizado a usar esse fluxo de autenticação.
invalid_id_token_hint: O id_token é inválido e não pode ser usado no fluxo
emitir avisos de recepção do pedido de autenticação da CIBA (resposta da consulta de auth_req_id) com um prazo máximo de 5 minutos
Validação Payload
Parameters | Validation |
iss | O Servidor de Autorização deve estabelecer um identificador, ou conjunto de identificadores "iss" padrão para uso em transações CIBA. - O Servidor de Autorização não deve aceitar "iss" diferente de seu próprio identificador, ou conjunto de identificadores, padrão. |
sub | O Servidor de Autorização deve verificar se o identificador "sub" em questão já foi emitido para um cliente/conta, e se é válido dentro de seus requisitos. |
aud | O Servidor de Autorização não deve aceitar "aud" diferente do client_id de onde se origina a solicitação de autorização para o fluxo CIBA. |
exp | "exp" deve ser estabelecido de acordo com as políticas de risco da instituição Titular da Conta. O Servidor de Autorização não deve aceitar solicitações de autorização cuja data/hora seja maior que "exp". |
iat | Sem validações específicas |
auth_time | Sem validações específicas |
nonce | Sem validações específicas no Servidor de Autorização (AS) |
acr | Se presente, o AS só deverá aceitar valores iguais ou superiores aos requisitos de autenticação do Titular para autorizar operações de pagamento. |
amr | Se presente, o AS só deverá aceitar valores iguais ou superiores aos requisitos de autenticação do Titular para autorizar operações de pagamento. |
azp | O Servidor de Autorização não deve aceitar "azp" diferente do client_id de onde se origina a solicitação de autorização para o fluxo CIBA. |
Parâmetros para validação de assinatura
Todos os parâmetros devem estar presentes no cabeçalho JWT.
Parâmetros | Descrição | Valores recomendados |
alg | O parâmetro "alg" (algoritmo) identifica o algoritmo criptográfico usado para proteger o JWS/JWE. O valor de Assinatura JWS será inválido se o valor "alg" não representar um algoritmo suportado ou se não houver nenhuma chave compatível para o uso do algoritmo associado à entidade que assinou digitalmente o conteúdo. | PS256 ou PS512 |
jku | O parâmetro "jku" (JWK Set URL) é um URI (RFC3986) que se refere a um recurso para um conjunto de chaves públicas codificadas em JSON, uma das quais corresponde à chave usada para assinar digitalmente o JWS. As chaves DEVEM ser codificadas como um conjunto JWK. O protocolo usado para adquirir o recurso DEVE fornecer proteção de integridade; uma solicitação HTTP GET para recuperar o conjunto JWK DEVE usar TLS (Transport Layer Security); e a identidade do servidor DEVE ser validada, de acordo com a Seção 6 do RFC6125. (OPCIONAL) | |
jwk | O parâmetro "jwk" (JSON Web Key) é a chave pública que corresponde à chave usada para assinar digitalmente o JWS. Essa chave é representada como um JWK. (OPCIONAL) | |
kid | O parâmetro "kid" (Key ID) indica qual chave foi usada para proteger o JWS/JWE. Esse parâmetro permite que os remetentes sinalizem explicitamente uma alteração de chave para os destinatários. O valor "kid" DEVE ser uma cadeia de caracteres que diferencia maiúsculas de minúsculas. Quando usado com um JWK, o valor "kid" é usado para corresponder a um valor de parâmetro "kid" do JWK. (OPCIONAL) | |
x5u | O parâmetro "x5u" (X.509 URL) é um URI (RFC3986) que se refere a um recurso para o certificado de chave pública X.509 ou cadeia de certificados (RFC5280) correspondente à chave usada para assinar digitalmente o JWS. (OPCIONAL) | |
x5c | O parâmetro "x5c" (X.509 Certificate Chain) contém o certificado de chave pública X.509 ou a cadeia de certificados (RFC5280) correspondente à chave usada para assinar digitalmente o JWS. (OPCIONAL) | |
x5t | O parâmetro "x5t" (X.509 Certificate SHA-1 Thumbprint) é uma impressão digital SHA-1 codificada em base64url (hash) da codificação DER do certificado X.509 (RFC5280) correspondente à chave usada para assinar digitalmente o JWS. (OPCIONAL) | |
x5t#S256 | O parâmetro "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) é uma impressão digital SHA-256 codificada em base64url (hash) da codificação DER do certificado X.509 (RFC5280) correspondente à chave usada para assinar digitalmente o JWS. Pode ser usado como uma alternativa ao "x5t" (OPCIONAL) | |
typ | O parâmetro "typ" (Type) é usado por aplicativos JWS para declarar o tipo de mídia (IANA. MediaTypes) deste JWS completo. Destina-se ao uso pelo aplicativo quando mais de um tipo de objeto pode estar presente em uma estrutura de dados de aplicativo que pode conter um JWS; O aplicativo pode usar esse valor para eliminar a ambiguidade entre os diferentes tipos de objetos que podem estar presentes. (OPCIONAL) | JWT |
cty | O parâmetro "cty" (Content Type) é usado por aplicativos JWS para declarar o tipo de mídia (IANA. MediaTypes) do conteúdo protegido (carga útil). Destina-se ao uso pelo aplicativo quando mais de um tipo de objeto pode estar presente na carga útil do JWS; O aplicativo pode usar esse valor para eliminar a ambiguidade entre os diferentes tipos de objetos que podem estar presentes. | em vez de usar “application/example” use “example” |
crit | O parâmetro "crit" (Crítico) indica que as extensões para esta especificação e/ou [JWA] estão sendo usadas e DEVEM ser compreendidas e processadas. Seu valor é uma matriz com os nomes dos parâmetros de cabeçalho presentes no cabeçalho JOSE que usam essas extensões. |
5.2.3. Cliente confidencial
Além disso, o cliente confidencial
deve suportar o consentimento parametrizado do escopo de recursos do OAuth 2.0, conforme definido na cláusula 6.3.1 OIDF FAPI WG Lodging Intent Pattern
deve suportar tokens de atualização
5.2.4. Mecanismos de hint de identidade do proprietário do recurso
5.2.4.1. Introdução
Conforme descrito em FAPI-CIBA, há muitos mecanismos que podem ser usados para transmitir uma identidade de Proprietários de Recursos do Dispositivo de Consumo para o Servidor de Autorização, no entanto, em casos de chamada, esse atestado de identidade deve ser tratado apenas como um hint . Há naturalmente limitações nos tipos de dicas de identificação que podem ser capturadas pelo dispositivo de consumo com base nos contratos de entrada e saída do dispositivo que está sendo usado. Além dos desafios de entrada e saída, existem vários aspectos importantes de privacidade e segurança que devem ser avaliados ao definir os processos de transporte de id. Este perfil define vários login hint tipos que devem ser suportados por servidores de autorização.
FAPI-CIBA exige que os pedidos sejam assinados, não há nenhuma exigência no Brasil para assinar adicionalmente esses hint, pois todos eles são afirmados pelo Cliente.
6. Considerações de segurança
Os participantes devem apoiar todas as considerações de segurança especificadas em todas as cláusulas e subcláusulas do [FAPI-BR] e FAPI-CIBA
7. Considerações sobre compartilhamento de dados
Os participantes devem apoiar todas as considerações de compartilhamento de dados especificadas em [FAPI-BR]
8. Metadados de registro e descoberta
Metadados do provedor OpenID
Os seguintes parâmetros de metadados do servidor de autorização são introduzidos por esta especificação para OPs que publicam seu suporte ao fluxo CIBA Brasil e seus detalhes.
backchannel_endpoint_login_hint_token_types_supported: OBRIGATÓRIO.
Matriz JSON contendo um ou mais dos seguintes valores:
urn:brasil:openbanking:ciba:login-hint-token-type:cpf,
urn:brasil:openbanking:ciba:login-hint-token-type:ephemeral or urn:brasil:openbanking:ciba:login-hint-token-type:credit-proposition.
urn:brasil:openbanking:ciba:login-hint-token-type:id-token.
9. Agradecimentos
Com agradecimento a todos que estabeleceram as bases para o compartilhamento seguro e seguro de dados através da formação do Grupo de Trabalho FAPI da Fundação OpenID, do Open Finance Brasil GT Segurança e aos pioneiros que estarão sobre seus ombros.
As seguintes pessoas contribuíram para este documento:
Gustavo Cunha (Banco do Brasil)
Karina Cabral (Mercado Pago)
Nic Marcondes (Quanto)
Ralph Bragg (Raidiam)
Apêndice A. Comunicações
Copyright (c) 2023 Open Finance Brasil Estrutura Inicial.
A Estrutura Inicial do Open Finance Brasil (EIPFB) concede a qualquer Colaborador, desenvolvedor, implementador ou outra parte interessada uma licença de direitos autorais mundial não exclusiva, isenta de royalties para reproduzir, preparar trabalhos derivados, distribuir, executar e exibir, este Rascunho ou Especificação Final dos Implementadores 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 seja feita atribuição ao EIPFB como fonte do material, mas que tal atribuição não indique um endosso do EIPFB.
A tecnologia descrita nesta especificação foi disponibilizada a partir de contribuições de várias fontes, incluindo membros da OpenID Foundation, do Open Finance Brasil GT Security Working Group 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 nenhuma posição em relação à validade ou escopo de qualquer propriedade intelectual ou outros direitos que possam ser reivindicados como pertencentes à implementação ou uso da tecnologia descrita nesta especificação ou até que ponto qualquer licença sob tais direitos pode ou não estar disponível; tampouco declara que fez qualquer esforço independente para identificar tais direitos. A Estrutura Inicial do Open Finance Brasil e os colaboradores desta especificação não oferecem (e renunciam expressamente a quaisquer garantias) (expressas, implícitas ou outras), 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 colaboradores ofereçam uma promessa de patente de não reivindicar certas reivindicações de patente contra outros colaboradores e contra implementadores. A Estrutura Inicial do Open Finance Brasil convida qualquer interessado a levar ao seu conhecimento quaisquer direitos autorais, patentes, pedidos de patente ou outros direitos de propriedade que possam abranger tecnologia que possa ser necessária para a prática desta especificação.
Author's Address
OFBIS GT Security
Open Finance Brasil Initial Structure