OFB-FAPI-1-ID3 | March 2023 | |
Security | Standards Track | [Page] |
Este documento também está disponível em português¶
The Open Finance Brasil Initial Structure is responsible for creating standards and specifications necessary to meet the requirements and obligations of the Brasil Open Finance Legislation as originally outlined by the Brasil Central Bank. There is a possibility that some of the elements of this document may be the subject to patent rights. OFBIS shall not be held responsible for identifying any or all such patent rights.¶
Open Finance Brasil Financial-grade API Security Profile 1.0 consists of the following parts:¶
These parts are intended to be used with RFC6749, RFC6750, RFC7636, OIDC, FAPI-1-Baseline and FAPI-1-Advanced¶
The Open Finance Brasil Financial-grade API is a highly secured OAuth profile that aims to provide specific implementation guidelines for security and interoperability which can be applied to APIs in the Brasil Open Finance area that require a higher level of privacy than provided by standard Financial-grade API Security Profile 1.0 - Part 2: Advanced. Among other enhancements, this specification addresses privacy considerations identified in FAPI-1-Advanced that are relevent in the Open Finance Brasil specifications but have not, so far, been required by other jurisdictions.¶
Although it is possible to code an OpenID Provider and Relying Party from first principles using this specification, the main audience for this specification is parties who already have a certified implementation of Financial-grade API Security Profile 1.0 - Part 2: Advanced and want to achieve certification for the Brasil Open Finance programme.¶
The key words "shall", "shall not", "should", "should not", "may", and "can" in this document are to be interpreted as described in ISO Directive Part 2.¶
These key words are not to be used as lexicon terms such that any occurrence of them shall be interpreted as key words and are not to be interpreted with their natural language meanings.¶
This document specifies the method of¶
This document is applicable to all participants engaging in Open Finance in Brasil.¶
The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applied. For undated references, the latest edition of the referenced document (including any amendments) applies.¶
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¶
LIWP - OIDF FAPI WG Lodging Intent Working Paper¶
OFB-FAPI-DCR - Open Banking Brasil Financial-grade API Dynamic Client Registration Profile 1.0¶
For the purpose of this document, the terms defined in RFC6749, RFC6750, RFC7636, OpenID Connect Core and ISO29100 apply.¶
The Brasil Open Finance Security profile specifies additional security and identity requirements for high risk API resources protected by the OAuth 2.0 Authorization Framework that consists of RFC6749, RFC6750, RFC7636, FAPI-1-Baseline, FAPI-1-Advanced and other specifications.¶
This profile describes security and features provisions for a server and client that are necessary for the Brasil Open Finance Programme by defining the measures to mitigate or address:¶
Open Finance Brasil has a requirement to address privacy considerations that were identified but not addressed in the FAPI-1-Advanced final specification without imposing additional requirements on Authorisation Servers being proposed in FAPI-2-Baseline.¶
Participants in this ecosystem have a need for clients to request an openid provider to confirm values of identity claims as part of an authorization request using the mechanism defined in clause 5.5.1 of OIDC.¶
The use of the claims parameter to request explicit claims values requires clients to ensure that they encrypt the request object to avoid information leakage. This risk is identified in clause 7.4.1 of FAPI-1-Baseline.¶
In addition this profile describes the specific scope, acr and client management requirements necessary to support the wider Open Finance Brasil ecosystem.¶
As a profile of the OAuth 2.0 Authorization Framework, this document mandates the following for the Brasil Open Finance Security profile.¶
A confidential client shall support the provisions specified in clause 5.2.3 of Financial-grade API Security Profile 1.0 - Part 2: Advanced,¶
In addition, the confidential client¶
acr
claim with required values;¶
acr
claim as an essential claim;¶
refresh tokens
rotation feature;¶
x-fapi-interaction-id
on FAPI endpoints;¶
Participants shall support all security considerations specified in clause 8 Financial-grade API Security Profile 1.0 - Part 1: Advanced and the Brazilian Central Bank Open Banking Security Manual. The Brazilian ICP issues RSA x509 certificates only therefor section removes for simplicity support for EC algorithms and requires that only IANA recommended encryption algorithms be used.¶
JWS standad defined in RFC7515 shall be adopted to ensure integrity and non-repudiation of information processed in sensitive API's (message sign requirement is indicated at API's documentation/swagger), which includes:¶
Each of elements above must be encoded using the Base64url pattern RFC4648 and the elements must be concatenated with "." (JWS Compact Serialization method as defined in RFC7515).¶
The payload of signed messages (request JWT and response JWT) shall include the following claims as defined at RFC7519:¶
organisationId
listed in the directory;¶
organisationId
of the sender;¶
The HTTP content-type of requests and responses with JWS messages shall be defined as: "application/jwt".¶
The JOSE header must contain the following attributes:¶
Resource Provider
the API provider shall return HTTP error message with status code
400 and the ResponseError
content shall include, in the code
property, the content BAD_SIGNATURE
.¶
Resource Provider
(eg account holding institution) must be notified.¶
The receiver shall validate the consistency of the JWS message's digital signature exclusively based on the information obtained from the directory, that is, based on the keys published in the institution's JWKS in the directory.¶
Signatures must be performed using the digital signature certificate specified in the Open Finance Brazil Certificates Standard;¶
the iat claim must be numeric in Unix Time format GMT+0 with a tolerance of +/- 60 seconds;¶
the jti claim must be unique for a clientId within a time frame of 86,400 seconds (24h), and cannot be reused within this period. In case of reuse, the HTTP error code 403 shall be return. Any other case must follow RFC 6749 instructions in item 5.2.¶
For JWS, both clients and Authorization Servers¶
For JWE, both clients and Authorization Servers¶
For TLS, Authorization Server endpoints and Resource Server endpoints used directly by the Client¶
With thanks to all who have set the foundations for secure and safe data sharing through the formation of the OpenID Foundation FAPI Working Group, the Open Finance Brasil GT Security and to the pioneers who will stand on their shoulders.¶
The following people contributed to this document:¶
Copyright (c) 2023 Open Finance Brasil Initial Structure.¶
The Open Finance Brasil Initial Structure (OFBIS) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty-free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OFBIS as the source of the material, but that such attribution does not indicate an endorsement by the OFBIS.¶
The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation, the Open Finance Brasil GT Security Working Group and others. Although the Open Finance Brasil Initial Structure has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The Open Finance Brasil Initial Structure and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The Open Finance Brasil Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The Open Finance Brasil Initial Structure invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.¶