Índice |
---|
Foreword
Este documento também está disponível em português
...
These parts are intended to be used with RFC6749, RFC6750, RFC7636, OIDC, OIDR, RFC7591, RFC7592, FAPI-1-Baseline and FAPI-1-Advanced
Introduction
The Open Finance Brasil Financial-grade API Dynamic Client Registration Profile is a profile of RFC7591, RFC7592 and OIDR that aims to provide specific implementation guidelines for security and interoperability which can be applied to the identification, registration and management of OAuth Clients operating in the Brasil Open Finance ecosystem.
Although it is possible to code an OpenID Provider and Relying Party from scratch using this specification, the main audience for this specification are parties who already have a certified implementation of OpenID Connect and seek to obtain 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 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.
1. Scope
This document specifies the method of
...
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.
...
OFB-DCR/DCM-Swagger - DCR & DCM Swagger
3. Terms and definitions
For the purpose of this document, the terms defined in RFC6749, RFC6750, RFC7636, OpenID Connect Core and ISO29100 apply.
4. Symbols and Abbreviated terms
API - Application Programming Interface
DCR - Dynamic Client Registration
FAPI - Financial-grade API
HTTP - Hyper Text Transfer Protocol
OIDF - OpenID Foundation
REST - Representational State Transfer
SS - Software Statement
SSA - Software Statement Assertion
TLS - Transport Layer Security
5. Introduction
Brasil Open Finance ecosystem leverages a federation trust provider or directory of participants as the golden source of information on accredited participants and software that are authorized to partake in the Open Finance Brasil ecosystem.
...
It's important to remember that the client registration payload has most of its attributes as non-mandatory, and that assigned values that conflict with those in the software statement assertion will be overridden by the values of the software statement assertion issued by the Directory of Participants. Not all metadata a client wishes to provide may be contained in a software statement, e.g alternative Metadata Languages and Script values. There are some cases where the client metadata are subset of the existing values in the SSA, such as redirect_URIs.
6. Open Finance Brasil OpenID Connect Discovery provisions
6.1. Authorization server
The Authorization Server shall support OpenID Connect Discovery as required by Financial-grade API Security Profile 1.0 - Part 1: Baseline. This support shall be explicit in Participant Directory configurations, and in the declaration of its attributes in the Discovery file (well-known), respecting the authentication mechanisms certified by the institution through the Open Finance Brazil compliance tests.
...
shall advertise its presence in the Open Finance Brasil ecosystem by being listed on the Directory of Participants;
shall advertise all Open Finance Brasil REST API resources protected by the OpenID Provider on the Directory of Participants;
shall advertise support for all signing, encryption, authentication mechanisms and standards required to support Open Finance Brasil Financial API;
shall advertise support for OpenID Dynamic Client Registration;
may advertise
mtls_endpoint_aliases
as per clause 5 RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens thetoken_endpoint
,registration_endpoint
anduserinfo_endpoint
;if supporting OAuth 2.0 Pushed Authorization Requests shall advertise through OIDD
mtls_endpoint_aliases
thepushed_authorization_request_endpoint
;if supporting Financial API - Client Initiated Back Channel Authentication shall advertise through OIDD
mtls_endpoint_aliases
thebackchannel_authentication_endpoint
;
6.2. Client
The Client shall support OpenID Connect Discovery as required by Financial-grade API Security Profile 1.0 - Part 1: Baseline
...
shall rely on ecosystem discovery services provided by Directory of Participants only;
shall derive necessary Authorisation Server metadata by relying on an Authorization Servers OpenID Connect Discovery services only;
where present, shall use endpoints advertised in
mtls_endpoint_aliases
as per clause 5 RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens;
7. Open Finance Brasil OpenID Connect Registration Provisions
7.1. Authorization server
The Authorization Server shall support the RFC RFCs Dynamic Client Registration (DCR) RFC7591, Dynamic Client Management (DCM) RFC7592 and OpenID Registration
...
These provisions apply equally to the processing of RFC7591, RFC7592 and OpenID Registration requests
7.1.1. Applying Server Defaults
Whenever properties of a DCR request are not included nor mandatory in the specification, the Authorisation Server shall apply client defaults in the following manner:
shall select and apply the encryption algorithm and cipher choice from the most recommended of the IANA cipher suites that is supported by the Authorisation Server;
shall populate defaults from values within the
software_statement
assertion where possible;shall grant the client permission to the complete set of potential scopes based on the softwares regulatory permissions included in the
software_statement
;
7.1.2. Certificate Distinguished Name Parsing
Clause 3 of Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names defines the mandatory OIDs whose AttributeType strings (descriptors) must be recognized by implementers. This mandatory list does not include several of the OIDs defined in Open Finance Brasil x.509 Certificate Standards nor is there a defined mechanism for Authorisation Servers to publish information regarding the format that they would expect a Dynamic Client Registration request that includes a tls_client_auth_subject_dn
to be presented in.
...
subject_dn | Issuer |
---|---|
UID=67c57882-043b-11ec-9a03-0242ac130003,2.5.4.97=#0C2A4F464242522D36376335373838322D303433622D313165632D396130332D303234326163313330303033,1.3.6.1.4.1.311.60.2.1.3=#13024252,2.5.4.15=#131450726976617465204f7267616e697a6174696f6e,2.5.4.5=#130e3133333533323336303030313839,CN=mycn.bank.gov.br,OU=497e1ffe-b2a2-4a4e-8ef0-70633fd11b59,O=My Public Bank,L=BRASILIA,ST=DF,C=BR | issuer=CN=AC SERASA SSL EV,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR |
UID=67c57882-043b-11ec-9a03-0242ac130003,1.3.6.1.4.1.311.60.2.1.3=#13024252,2.5.4.15=#131450726976617465204f7267616e697a6174696f6e,CN=mycn.bank.gov.br,2.5.4.5=#130e3133333533323336303030313839,2.5.4.97=#132A4F464242522D36376335373838322D303433622D313165632D396130332D303234326163313330303033,O=My Public Bank,L=BRASILIA,ST=DF,C=BR |
7.2. Regulatory Roles for OpenID and OAuth 2.0 Mappings
To participate in the Open Finance ecosystem, accredited institutions must register themselves in the directory of participants according to their regulatory roles. Those roles reflect the institutions authorization from the Central Bank and, consequently, the APIs they are allowed to use.
...
It is requiread that the active roles in the application's software_statement are validated. The field _software_statement_roles shall be used for validation and currently listed roles shall be active.
7.3. Client Registration
Section 4.2.11 of RFC 4517 (caseIgnoreMatch) must be respected. Upon registering using the tls_client_auth authentication method, the client shall forward the tls_client_auth_subject_dn field with the AttibuteTypes(Descriptors) using the defined format under item Certificate Distinguished Name Parsing. Non adherence to this format shall cause rejection of the registration.
8. Software Statement Assertion
A Software Statement Assertion (software_statement) is a JSON Web Token (JWT) RFC7519 that asserts the metadata values of the client software as a whole. On the Open Finance Brasil structure, this software_statement is signed by the Participants Directory and it's signature MUST be validated by the Authorization Servers using the public keys available on the following session.
8.1. Attributes of the Software Statement Assertion (Claims)
The following example contains all attributes currently included in a software_statement:
|
9. Processing of the Dynamic Client Registration claim
...
The steps of the subject_DN extraction process are described in section Certificate Distinguished Name Parsing
...
|
9.1. Sending a Registration Claim with a Software Statement
This example includes several optional fields, some of those may not be applicable to some implememntations. For a complete guide to attributes and its mandate, consult the DCR Swagger OFB-DCR/DCM-Swagger. Line breaks inside values serve presentation purposes only.
|
9.2. Open Finance Brasil SSA Key Store and Issuer Details
The following links point to public keys of the Participant Directory and must be used to verify the signature validity of the software_statements presented during the client registration process.
...
Open Finance Open Finance Brasil sandbox SSA issuer
9.3. About authentication and authorization mechanisms for DCR and DCM services
As they are auxiliary services to the main flow of Open Finance Brasil, the dynamic registration and maintenance services for clients do not use the same access control mechanisms. For example, it is not possible to require an OAuth 2.0 access_token from a client application that isn't registered yet with the transmitting institution.
To extend RFC7591 and RFC7592, which recommend minimum mechanisms for authentication of their services, institutions that support the registration flows and dynamic maintenance of clients must implement the following controls:
9.3.1. Client registration - POST /register
validate that the certificate presented by the client application is subordinate to the ICP-Brasil chains defined in the Open Finance Brasil Certificates Standard;
As long as there is a need for the coexistence period (mentioned in section 7.1), validation must be implemented for both cases: certificates that have the value org_id in the organizationUnitName field (OU) and certificates that have the value org_id in the organizationIdentifier field.
ensure that the signature of the
software_statement
_ presented by the client application during registration has been made by the Directory of Participants using the public keys described in the previous section;ensure that the
software_statement
presented by the client application during registration corresponds to the same institution as the client certificate presented, validating it through the attributes that bringorganization_id
in the X.509 certificate.Multiple DCR registrations for the same Software Statement should not be allowed, in a way that in case of a new registration attempt for an already registered Software Statement, the Error Response procedure defined on item 3.2.2 of the RFC7591 must be enforced.
issue, on the registry response, a
registration_access_token
to be used as an authentication token on maintaining operations of the registered client application, following specifications described in RFC7592.
9.3.2. Client Maintenance - GET /register - PUT /register - DELETE /register
Removed
Validate the presence and matching of the Bearer header
Authorization
containing the value of theregistration_access_token
attribute returned during registration of the corresponding client.When the invoked method is PUT / register, carry out the validations of sub-items 1, 3, 4, and 6 of item Client registration - POST /register.
When the invoked method is GET /register, carry out the validations of sub-items 1 and 6 of item Client registration - POST /register.
When the invoked method is DELETE /register, carry out the validation of sub-item 1 of item Client registration - POST /register.
Note: RFC7592 provides the possibility of rotating the registration_access_token
issued by the Authorization Server with each use, making it a single-use token. When registering their client applications, institutions should consider this aspect to receive and update the registration_access_token
for the new value received in client maintenance (DCM) operations.
9.4. Signature certificates validation
The directory uses cert rescan function hourly to validation process.
The organization shall ensure that the validation process was completed.
Each organization must have a continuity plan in case of unavailability validation service.
If the signature certificate is not valid because it has a revoked status according to the CA’s OCSP/CRL issuer, or is inactive in the directory register, the set of public keys is moved to the inactive key storage.
The validation process should include:
Resource server (Data Transmitter) message signature validation, to be done by the Client (Data Receiver)
Validate that the message was signed in line with what’s defined on the Message Signature Guidelines, including that the iss is equal to the organisation_id of the server that issued the message.
Fetch the “iss” claim from the JWT and build the directory application JWKS uri for that specific server.
Make sure that the kid present on the message JWT header is present on the directory JWKS.
Validate that the private key for the corresponding kid is able to validate the message signature.
Client (Data Receiver) message signature validation, to be done by the Resource Server
Validate how the message was signed in line with what’s defined on the Message Signature Guidelines.
Obtain the org_jwks_uri which was presented on the SSA by the client on the moment of the registration (DCR)
Make sure that the kid present on the message JWT header is present on the directory JWKS.
Validate that the private key for the corresponding kid is able to validate the message signature.
10. Acknowledgement
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.
...
Alexandre Daniel Dalabrida (Cooperativa Central Ailos)
Alexandre Siqueira (Mercado Pago)
André Borges (Banco Fibra)
Bernardo Vale (Banco Inter)
Caio Zanolla (Belvo)
Danilo Sasaki (Banco Itaú)
João Rodolfo Vieira da Silva (Banco Itaú)
Michelle Bandarra (Chicago)
Nic Marcondes (Quanto)
Rafael Gonzalez Hashimoto (Banco C6)
Ralph Bragg (Raidiam)
Appendix A. Notices
Copyright (c) 2023 Open Finance Brasil Initial Structure.
...
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.
A.1. Appendix A. Example Software Statement Assertion
|
Author's Address
OFBIS GT Security
Open Finance Brasil Initial Structure
...