Foreword
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
Introduction
The Financial-grade API Standard provides a profile for OAuth 2.0 suitable for use in financial services. The standard OAuth method for the client to send the resource owner to the authorization server is to use an HTTP redirect. Parts 1 and 2 of this specification support this interaction model and are suitable for use cases where the resource owner is interacting with the client on a device they control that has a web browser. There are however many use-cases for initiating payments where the resource owner is not interacting with the client in such a manner. For example, the resource owner may want to authorize a payment at a "point of sale" terminal at a shop or fuel station.
This document is a profile of the OpenID Connect Client Initiated Backchannel Authentication Flow CIBA that supports this decoupled interaction method. The CIBA spec allows a client that gains knowledge of an identifier for the user to obtain tokens from the authorization server. The user consent is given at the user's Authentication Device mediated by the authorization server. This document profiles the CIBA specification to bring it in line with the other FAPI parts and provides security recommendations for its use with APIs that require financial-grade security.
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: Client Initiated Backchannel Authentication Profile and want to achieve certification for the Brasil Open Finance programme.
Notational Conventions
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 used as dictionary terms such that any occurrence of them shall be interpreted as key words and are not to be interpreted with their natural language meanings.
1. Scope
This document specifies the method of
applications to obtain OAuth tokens via a backchannel authentication flow in an appropriately secure manner for higher risk access to data in a manner that meets the requirements of Open Finance Brasil;
applications to use OpenID Connect CIBA to suggest the identity of the customer;
This document is applicable to all participants engaging in Open Finance in Brasil.
2. Normative references
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
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. Terms and definitions
For the purpose of this document, the terms defined in RFC6749, RFC6750, RFC7636, OpenID Connect Core, CIBA and ISO29100 apply.
4. Symbols and Abbreviated terms
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. Brasil Open Banking Security Profile
5.1. Introduction
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, FAPI-CIBA 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 address:
the requirement to convey the Authentication Context Request that was performed by an OpenID Provider to a Client to enable appropriate client management of customer conduct risk.
the requirement for clients to assert a pre-existing customer relationship by asserting a customer identity claim as part of the CIBA flow.
5.2. Open Banking Brasil CIBA Security provisions
5.2.1. Introduction
Open Finance Brasil has a requirement to adopt Client Initiated Back Channel Authentication as a means of enabling decoupled authentication work flows. 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.
5.2.2. Authorization server
The Authorization Server shall support the provisions specified in clause 5.2.2 of Financial-grade API CIBA Security Profile 1.0
In addition, the Authorization Server
shall distribute discovery metadata (such as the authorization endpoint) via the metadata document as specified in OIDD and [RFC8414]
shall support the claims parameter as defined in clause 5.5 OpenID Connect Core
shall support the oidc standard claim "cpf" as defined in clause 5.2.2.2 of [FAPI-BR]shall support the oidc standard claim "cnpj" as defined in clause 5.2.2.3 of [FAPI-BR] if providing access to resources where the resource owner is not a natural personshall support the acr "urn:brasil:openbanking:loa2" as defined in clause 5.2.2.4 of FAPI-BR
should support the acr "urn:brasil:openbanking:loa3" as defined in clause 5.2.2.4 of [FAPI-BR]]
shall implement the userinfo endpoint as defined in clause 5.3 OpenID Connect Core
shall support parameterized OAuth 2.0 resource scope consent as defined in clause 6.3.1 OIDF FAPI WG Lodging Intent Pattern
shall support refresh tokens
shall issue access tokens with an expiry no greater than 900 seconds and no less than 300 secondsshall always include an acr claim in the id_tokenshall require the Signed Authentication Request to contain nbf and exp claims that limit the lifetime of the request to no more than 10 minutesshall issue ciba auth request acknowledgements with a minimum expiry of 6 minutes;The acceptance time of consent on the Authorization request received via CIBA shall remain the same as defined for the flow via Hybrid Flow, of 5 minutes;
shall ensure that ‘exp’ in all issued id_tokens is at least 180 days from the time of issue;
The id_token shall be used in the authorization call through the "id_token_hint" parameter
shall support CIBA poll mode;
shall not support CIBA push mode;
shall not support CIBA ping mode;
The cancellation of the id_token shall be carried out by the account holder institution in cases of fraud or for security reasons.
is going to be added – The routine rotation of signing keys of id tokens SHALL NOT BE a reason to reject a non-expired id token signed with the older key. The authorization server should be prepared to use signing keys with similar validity periods to the ones of the id token.
Error table “HTTP 400 Bad Request”:
invalid_request: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, contains more than one of the hints, or is otherwise malformed.
invalid_scope: The requested scope is invalid, unknown, or malformed.
expired_id_token_hint: The id_token hint provided in the authentication request is not valid because it has expired.
unknown_user_id: The OpenID Provider is not able to identify which end-user the Client wishes to be authenticated by means of the hint provided in the request (id_token_hint).
unauthorized_client: The Client is not authorized to use this authentication flow.
invalid_id_token_hint: The id_token is invalid and can’t be used in the flow
Shall issue ciba auth request acknowledgements (response of the consultation of auth_req_id) with a maximum expiry of 5 minutes, as defined for the flow via Hybrid Flow;
Payload validation
Parameters | Validation |
iss | - The Authorization Server must establish an identifier, or set of standard "iss" identifiers for use in CIBA transactions. - The Authorization Server should not accept "iss" different from its own identifier, or set of identifiers, standard. |
sub | - The Authorization Server should check if the "sub" identifier in question has already been issued to a client/account, and if it is valid within its requirements. |
aud | - The Authorization Server should not accept "aud" different from the client_id from where the authorization request for the CIBA flow originates. |
exp | - "exp" should be established according to the risk policies of the Account Holder institution, provided that requirement 5.2.2.15 is respected (minimum of 180 days) - The Authorization Server should not accept authorization requests whose date/time is greater than "exp". |
iat | - No specific validations |
auth_time | - No specific validations |
nonce | - No specific AS validations |
acr | - If present, the AS should only accept values equal to or above the Holder's authentication requirements to authorize payment transactions. |
amr | - If present, the AS should only accept values equal to or better than the Holder's authentication requirements to authorize payment transactions. |
azp | - The Authorization Server should not accept "azp" different from the client_id from where the authorization request for the CIBA flow originates. |
Parameters for signature validation
All parameters must be present in the JWT header.
Parameters | Description | Recommended values |
alg | The "alg" (algorithm) parameter identifies the cryptographic algorithm used to protect the JWS/JWE. The JWS Signature value is invalid if the "alg" value does not represent a supported algorithm or if there is no compatible key for the use of the algorithm associated with the entity that digitally signed the content. | PS256 ou PS512 |
kid | The "kid" (Key ID) parameter indicates which key was used to protect the JWS/JWE. This parameter allows senders to explicitly signal a key change to recipients. The "kid" value MUST be a case-sensitive string. When used with a JWK, the "kid" value is used to match a "kid" parameter value of the JWK. (OPTIONAL) | |
x5t | The "x5t" (X.509 Certificate SHA-1 Thumbprint) parameter is a base64url encoded SHA-1 thumbprint (hash) of the DER encoding of the X.509 certificate (RFC5280) corresponding to the key used to digitally sign the JWS. (OPTIONAL) | |
x5t#S256 | The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) parameter is a base64url encoded SHA-256 thumbprint (hash) of the DER encoding of the X.509 certificate (RFC5280) corresponding to the key used to digitally sign the JWS. It can be used as an alternative to "x5t" (OPTIONAL) | |
typ | The "typ" (Type) parameter is used by JWS applications to declare the media type (IANA.MediaTypes) of this complete JWS. It is intended for use by the application when more than one type of object may be present in an application data structure that can contain a JWS; the application can use this value to eliminate ambiguity between the different types of objects that may be present. (OPTIONAL) | JWT |
5.2.3. Confidential client
In addition, the confidential client
shall support parameterized OAuth 2.0 resource scope consent as defined in clause 6.3.1 OIDF FAPI WG Lodging Intent Pattern
shall support refresh tokens
5.2.3.1.1. Authorisation Server Generated - Login Hint Token
This login hint can be used where it is not possible for the Resource Owner to provide a Login Hint to the Consumption Device or where the Resource Owner wishes to claim the authentication request by independently reaching out to the Authorisation Server out of band to claim this authentication request.
urn:brasil:openbanking:ciba:login-hint-token-type:as-generated
The use of a binding message is mandatory if this token type is to be leveraged.
5.2.3.1.1.1. Authorisation Server Generated - Login Hint Presentation
Presentation of the Authorisation Server Generated Token must be in the format of a JWE displayed as a QR Code with the following properties in the following way.
JWS Creation
The payload of signed messages (requestJWT) shall include the following claims as defined atRFC7519:
audthe Authorization Servers advertised issuer as perOIDD;issthe receiver of the message shall validate if the value of theissfield matches the clientId of the sender;jtithe value of thejtifield shall be filled with the UUID defined by the institution according to [RFC4122] version 4;iattheiatfield shall be filled with the message generation time and according to the standard established inRFC7519to theNumericDateformat.*
exptheexpfield shall be filled with the message expiry time and according to the standard established inRFC7519to theNumericDateformat with an maximum value not greater than 5 minutes;auth_request_idthe authentication request id returned from the Authorisation Server CIBA requst.
The JOSE header must contain the following attributes:alg- shall be filled with the value PS256";kid- shall be filled with the key identifier value used for the signature listed on the software statement keystore on the Open Finance Brasil Directory of Participants;typ- shall be filled with the value cibabr+jwt.
JWE Creation
The JOSE header must contain the following attributes:alg- shall be filled with the value RSA-OAEP";enc- shall be filled with the value A256GCM";kid- shall be filled with the encryption key identifier kid value used to encrypt the JWE with the encryption key advertised on the authorisation servers jwks endpoint;cty- shall be filled with the value JWT.
5.2.4.1.2. Authentication Device Generated - Login Hint Token
This login hint token should be used when Client has requested a unique identifier be provided by the Resource Owner to the Consumption Device. It is recommended that this identifier be dynamic, time based, have sufficient entropy and short lived to prevent replay attacks.
{ "format": "urn:brasil:openbanking:ciba:login-hint-token-type:ad-generated", "id": "11112222333344445555" }
The use of a binding message is mandatory if this token type is to be leveraged.
5.2.4.1.2. Authentication Device Generated - Login Hint Token
This login hint token should be used when Client has requested a unique identifier be provided by the Resource Owner to the Consumption Device. It is recommended that this identifier be dynamic, time based, have sufficient entropy and short lived to prevent replay attacks.
{ "format": "urn:brasil:openbanking:ciba:login-hint-token-type:ad-generated", "id": "11112222333344445555" }
The use of a binding message is mandatory if this token type is to be leveraged.
6. Security considerations
Participants shall support all security considerations specified in all clauses and sub clauses of [FAPI-BR] and FAPI-CIBA
7. Data Sharing Considerations
Participants shall support all data sharing considerations specified in [FAPI-BR]
8. Acknowledgements
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:
Gustavo Cunha (Banco do Brasil)
Karina Cabral (Mercado Pago)
Nic Marcondes (Quanto)
Ralph Bragg (Raidiam)
Appendix A. Notices
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.
Author's Address
OFBIS GT Security
Open Finance Brasil Initial Structure
Email: gt-seguranca@openfinancebrasil.org.br