Versões comparadas

Versão antiga 12

changes.mady.by.user Renan Amorim Costa

Gravado em

comparado com

Nova versão Atual

changes.mady.by.user Renan Amorim Costa

Gravado em

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

...

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.

...

  • attacks that address privacy considerations identified in clause 9.1 of [FAPI1 Advanced]

  • the requirement to support fine-grained access to resources for data minimisation purposes

  • the requirement to convey the Authentication Context Request that was performed by an OpenID Provider to a Client to enable a 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 authorization flow.

5.2. Open Finance Brasil security provisions

...

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.

5.2.2. Authorization server

The Authorization Server shall support the provisions specified in clause 5.2.2 of Financial-grade API Security Profile 1.0 - Part 2: Advanced

In addition, the Authorization Server

  1. shall support a signed and encrypted JWE request object passed by value or shall require pushed authorization requests PAR;

  2. shall distribute discovery metadata (such as the authorization endpoint) via the metadata document as specified in OIDD and [RFC8414] (".well-known");

  3. shall support the claims parameter as defined in clause 5.5 OpenID Connect Core;

  4. shall support the oidc standard claim "cpf" as defined in clause "sub" Claim clarifications of this document;

  5. shall support the oidc standard claim "cnpj" as defined in clause Requesting the "cpf" Claim of this document if the institution provides accounts for legal person;

  6. shall support the acr "urn:brasil:openbanking:loa2" as defined in clause Requesting the "cnpj" Claim of this document;

  7. should support the acr "urn:brasil:openbanking:loa3" as defined in clause Requesting the "cnpj" Claim of this document;

  8. shall implement the userinfo endpoint as defined in clause 5.3 OpenID Connect Core;

  9. shall support parameterized OAuth 2.0 resource scope consent as defined in clause 6.3.1 OIDF FAPI WG Lodging Intent Pattern;

  10. may support Financial-grade API: Client Initiated Backchannel Authentication Profile;

  11. (withdrawn temporarily);

  12. shall support refresh tokens;

  13. shall issue access tokens with an expiry no greater than 900 seconds and no less than 300 seconds;

  14. shall always include an acr claim in the id_token;

  15. shall support the response_type value code id_token;

  16. may support response_type value code in conjunction with the response_mode value jwt;

  17. should offer the possibility to disable the rotation of refresh token;

  18. shall ensure that, in case of sharing the Authorization Server for other services, in addition to Open Finance, it does not disclose and/or allow the use of non-certified methods in the Open Finance environment;

  19. shall ensure that the settings disclosed to other participants through OpenID Discovery (indicated by the Well-Known file registered in the Directory) are restricted to the operating modes to which the institution has certified;

    1. shall keep in your settings the methods for which there are still active clients;

    2. shall update the records that use non-certified methods, through bilateral treatment between the institutions involved;

  20. shall refuse requests, for the Open Finance environment, that are outside the modes of operation to which the institution has certified its Authorization Server;

  21. must refuse authentication requests that include an id_token_hint, as the id_token held by the requester may contain Personally Identifiable Information, which could be sent unencrypted by the public client;

  22. the minimum expiration time of request_uri must be 60 seconds;

  23. shall deny all requests without header x-fapi-interaction-id on FAPI endpoints;

5.2.2.1. ID Token as detached signature

The Authorization Server shall support the provisions specified in clause 5.2.2.1 of Financial-grade API Security Profile 1.0 - Part 2: Advanced

In addition, if the response_type value code id_token is used, the Authorization Server:

...

should not return sensitive PII in the ID Token in the authorization response, but if it needs to, then it shall encrypt the ID Token;

...

Personally Identifiable Information may include, but is not limited to,:

  1. Claim sub if you use information that makes it possible to identify the natural person;

  2. The default Claims defined in clause 5.1 OIDC, which may contain data such as date of birth, address or telephone;

  3. The new Claim CPF, defined in the next section.

If a Claim containing Personally Identifiable Information is requested:

...

If this is marked as essential, if there is no encryption key registered for the Customer, the request must fail if requested at the Authorization Endpoint. There are no impediments if the request is made by the Confidential Client through the Token Endpoint;

...

For the encryption of the id_token, a key available in the JWKS informed in the jwks_uri parameter during the client registration must be used, indicated through the kid header of the JWT document;

...

The use of other headers to indicate the key used, such as x5u, x5c, jku or jkw is prohibited as defined in clause 2 OIDC.

...

This profile uses the official openId definition found at: Analise requisitos de criptografia ID_TOKEN. This means the sub is a never reassigned identifier for the end user. The value for a given user should never change within an institution, even across diferents consents.

5.2.2.3. Requesting the "cpf" Claim

This profile defines "cpf" as a new standard claim as per clause 5.1 OIDC

The CPF number (Cadastro de Pessoas Físicas, [sepeˈɛfi]; Portuguese for "Natural Persons Register") is the Brazilian individual taxpayer registry identification. This number is attributed by the Brazilian Federal Revenue to Brazilians and resident aliens who, directly or indirectly, pay taxes in Brazil.

In the Brasil Open Finance identity model, the cpf is a string consisting of numbers that is 11 characters long and may start with a 0.

If the cpf Claim is requested as an Essential Claim for the ID Token or UserInfo response with a values parameter requesting a specific cpf value, the Authorization Server MUST return a cpf Claim Value that matches the requested value.

...

If this is an Essential Claim and the requirement cannot be met or is not compatible with the one requested, then the Authorization Server shall treat that outcome as a failed authentication attempt.

Name: cpf, Type: String, Regex: 'd{11}$'

5.2.2.4. Requesting the "cnpj" Claim

This profile defines "cnpj" as a new standard claim as per clause 5.1OIDC

CNPJ, short for Cadastro Nacional de Pessoas Jurídicas, is an identification number of Brazilian companies issued by the Brazilian Ministry of Revenue, in Portuguese "Secretaria da Receita Federal" or "Ministério da Fazenda". In the Brasil Open Finance identity model, individuals can associated with 0 or more CNPJs. A CNPJ is a string consisting of numbers that is 14 digits long and may start with a 0, the first eight digits identify the company, the four digits after the slash identify the branch or subsidiary ("0001" defaults to the headquarters), and the last two are checksum digits. For this profile, the cnpj claim must be requested and supplied as the 14 digit number.

If the cnpj Claim is requested as an Essential Claim for the ID Token or UserInfo response with a values parameter requesting a specific cnpj value, the Authorization Server SHALL return a cnpj Claim Value that contains a set of CNPJs one of which must match the requested value.

If the cnpj Claim is requested as an Essential Claim for the ID Token or UserInfo the Authorization Server MUST return a cnpj Claim Value that contains a set of CNPJs one of which must match a CNPJ belonging to the authenticated user's account.

If this is an Essential Claim and the requirement cannot be met, then the Authorization Server shall treat that outcome as a failed authentication attempt.

Name: cnpj, Type: Array of Strings, Array Element Regex: 'd{14}$'

5.2.2.5. Requesting the "urn:brasil:openbanking:loa2" or "urn:brasil:openbanking:loa3" Authentication Context Request

This profile defines "urn:brasil:openbanking:loa2" and "urn:brasil:openbanking:loa3" as new Authentication Context Request (ACR) classes.

  • LoA2: Authentication performed using single factor;

  • LoA3: Authentication performed using multi factor (MFA)

The following rules are applicable to the authentication mechanism of Open Finance Brazil API's:

  • In accordance to Art. 17 of Joint Resolution nº 01 - Open Banking Brasil, institutions must adopt procedures and controls for client authentication compatible with those applicable in their electronic service channels.

  • In accorcdance with the regulation, it is suggested that:

    • For Read-Only APIs (Phase 2): the Authorization Servers should adopt, at least, an authentication method compatible with LoA2; and

    • For Read-Write API's (subsequent phases): the Authorization Servers should adopt an authentication method compatible with LoA3 or higher.

In all cases, the adoption of a more rigorous authentication mechanism (LoA3 or higher) is at the discretion of the Bank (ASPSP), according to its risk assessment and in a manner compatible with the mechanisms usually employed.

Authentication factors clarification

The authentication methods are:

  • Something you know, such as password or phrase

  • Something you have, such as token, smartcard or device

  • Something you are, meaning an authentication that makes use of physical characteristics, such as biometric validation.

To performe a MFA authentication is necessary that the end user presents at least two different methods as listed above. A unique method used more than once - ie. presenting passwords - is not accepted as MFA.This profile outlines the client management requirements needed to support the broader 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 Security Profile 1.0 - Part 2: Advanced

In addition, the Authorization Server

  1. shall perform client authentication using private_key_jwt;

  2. shall require requests of the type "pushed authorization requests" PAR;

  3. shall distribute discovery metadata (such as the authorization endpoint) via the metadata document as specified in OIDD and [RFC8414] (".well-known");

  4. shall support the claims parameter as defined in clause 5.5 OpenID Connect Core;

  5. shall support the acr "urn:brasil:openbanking:loa2" as defined in section 5.2.2.3;

  6. should support the acr "urn:brasil:openbanking:loa3" as defined in section 5.2.2.3;

  7. shall implement the userinfo endpoint as defined in clause 5.3 OpenID Connect Core;

  8. shall support parameterized OAuth 2.0 resource scope consent as defined in clause 6.3.1 OIDF FAPI WG Lodging Intent Pattern;

  9. may support Financial-grade API: Client Initiated Backchannel Authentication Profile;

  10. (withdrawn temporarily);

  11. shall support refresh tokens;

  12. shall issue access tokens with an expiry no greater than 900 seconds and no less than 300 seconds;

  13. shall always include an acr claim in the id_token;

  14. shall support the response_type value code id_token;

  15. shall not allow refresh token rotation;

  16. shall ensure that, in case of sharing the Authorization Server for other services, in addition to Open Finance, it does not disclose and/or allow the use of non-certified methods in the Open Finance environment;

  17. shall ensure that the settings disclosed to other participants through OpenID Discovery (indicated by the Well-Known file registered in the Directory) are restricted to the operating modes to which the institution has certified;

    1. shall keep in your settings the methods for which there are still active clients;

    2. shall update the records that use non-certified methods, through bilateral treatment between the institutions involved;

  18. shall refuse requests, for the Open Finance environment, that are outside the modes of operation to which the institution has certified its Authorization Server;

  19. the minimum expiration time of request_uri must be 60 seconds;

  20. shall deny all requests without header x-fapi-interaction-id on protected resources endpoints;

  21. must require the use of Proof Key for Code Exchange (PKCE);

  22. must require the use of subject_type “public”;

  23. must require the use of response_mode “fragment”;

  24. shall issue exclusively opaque refresh_tokens with no associated expiration date;

5.2.2.1. ID Token as detached signature

The Authorization Server shall support the provisions specified in clause 5.2.2.1 of Financial-grade API Security Profile 1.0 - Part 2: Advanced

  1. Shall encrypt the id_token in callback and token endpoint calls;

  2. For the encryption of the id_token, a key available in the JWKS informed in the jwks_uri parameter, with the attribute “use”:”enc”, during the client registration must be used, indicated through the kid header of the JWT document;

  3. The use of other headers to indicate the key used, such as x5u, x5c, jku or jkw is prohibited as defined in clause 2 OIDC.

5.2.2.2. "sub" Claim clarifications

This profile uses the official definition found at: Analise requisitos de criptografia ID_TOKEN. This means that the sub is an identifier that is never transferred or changed to the end user within the Account Servicing Payment Service Provider (ASPSP).

5.2.2.3. Requesting the "urn:brasil:openbanking:loa2" or "urn:brasil:openbanking:loa3" Authentication Context Request

This profile defines "urn:brasil:openbanking:loa2" and "urn:brasil:openbanking:loa3" as new Authentication Context Request (ACR) classes.

  • LoA2: Authentication performed using single factor;

  • LoA3: Authentication performed using multi factor (MFA)

The following rules are applicable to the authentication mechanism of Open Finance Brazil API's:

  • In accordance to Art. 17 of Joint Resolution nº 01 - Open Banking Brasil, institutions must adopt procedures and controls for client authentication compatible with those applicable in their electronic service channels.

  • In accordance with the regulation, it is suggested that:

    • For Read-Only APIs (Phase 2): the Authorization Servers should adopt, at least, an authentication method compatible with LoA2; and

    • For Read-Write API's (subsequent phases): the Authorization Servers should adopt an authentication method compatible with LoA3 or higher.

In all cases, the adoption of a more rigorous authentication mechanism (LoA3 or higher) is at the discretion of the Bank (ASPSP), according to its risk assessment and in a manner compatible with the mechanisms usually employed.

Authentication factors clarification

The authentication methods are:

  • Something you know, such as password or phrase

  • Something you have, such as token, smartcard or device

  • Something you are, meaning an authentication that makes use of physical characteristics, such as biometric validation.

To performe a MFA authentication is necessary that the end user presents at least two different methods as listed above. A unique method used more than once - ie. presenting passwords - is not accepted as MFA.

5.2.2.4 Mandatory scopes on the well-known endpoint

The authorization server must declare the scopes below in its well-known endpoint, regardless of whether the institution provides the products related to the scopes listed below:

  • invoice-financings

  • financings

  • loans

  • unarranged-accounts-overdraft

  • bank-fixed-incomes

  • credit-fixed-incomes

  • variable-incomes

  • treasure-titles

  • funds

  • exchanges

The scopes not listed above must be declared if the institution provides products related to them
(i.e.: accounts, payments)

5.2.3. Confidential client

...

In addition, the confidential client

...

client

  1. shall support Pushed Authorisation Requests PAR;

  2. shall use encrypted request objects if not using PAR;shall support parameterized OAuth 2.0 resource scope consent as defined in clause 6.3.1 OIDF FAPI WG Lodging Intent Pattern;

  3. shall support refresh tokens;

  4. shall not populate the acr claim with required values;

  5. shall require the acr claim as an essential claim;

  6. shall support all authentication methods specified in clause 5.2.2-14 of Financial-grade API Security Profile 1.0 - Part 2: Advanced including diferent combinations of the methods to send requests (using PAR or not - item 11);

  7. shall not allow refresh tokens rotation feature;

  8. should not request authentication requests that include an id_token_hint, as the id_token to be used may contain Personally Identifiable Information, which could be sent unencrypted through the public client.1 OIDF FAPI WG Lodging Intent Pattern;

  9. shall support refresh tokens;

  10. shall not populate the acr claim with required values;

  11. shall require the acr claim as an essential claim;

  12. shall not allow refresh tokens rotation feature;

  13. shall send header x-fapi-interaction-id on FAPI endpoints;

6. Security considerations

...

6.1. Message Content Signing Considerations (JWS)

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:

  • Header (JSON Object Signing and Encryption - JOSE Header), which defines the algorithm used and includes information about the public key or certificate that can be used to validate the signature;

  • Payload (JWS Payload): content itself as detailed in the API specification;

  • Digital signature (JWS Signature): digital signature, performed according to header parameters.

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

  2. The payload of signed messages (request JWT and response JWT) shall include the following claims as defined at RFC7519:

  • aud (in the JWT request): the Resource Provider (eg the institution holding the account) must validate if the value of the aud field matches the endpoint being triggered;

  • aud (in JWT response): the API client (eg initiating institution) shall validate if the value of the aud field matches its own organisationId listed in the directory;

  • iss (in the JWT request and in the JWT response): the receiver of the message shall validate if the value of the iss field matches the organisationId of the sender;

  • jti (in the JWT request and in the JWT response): the value of the jti field shall be filled with the UUID defined by the institution according to [RFC4122] version 4;

  • iat (in the JWT request and in the JWT response): the iat field shall be filled with the message generation time and according to the standard established in RFC7519 to the NumericDate format.

  • cty (in the JWT request and in the JWT response): the cty field shall be filled in the normal case in which nested signing or encryption operations are not employed, the use of this Header Parameter is not recommended. In the case that nested signing or encryption is employed, this Header Parameter must be present; in this case, the value must be "JWT", to indicate that a Nested JWT is carried in this JWT. While media type names are not case sensitive, it is recommended that "JWT" always be spelled using uppercase characters for compatibility with legacy implementations.

  1. The HTTP content-type of requests and responses with JWS messages shall be defined as: "application/jwt".

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

  • typ - shall be filled with the value JWT.

  • In case of error in signature validation by 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.

  • Errors in validating the signed messages received by the client application (eg payment initiator) must be logged and the Resource Provider (eg account holding institution) must be notified.

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

  2. Signatures must be performed using the digital signature certificate specified in the Open Finance Brazil Certificates Standard;

  3. the iat claim must be numeric in Unix Time format GMT+0 with a tolerance of +/- 60 seconds;

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

shall use PS256 algorithm;

6.1.2. Encryption algorithm considerations

For JWE, both clients and Authorization Servers

shall use RSA-OAEP with A256GCM

6.1.3. Secure Use of Transport Layer Security considerations

For TLS, Authorization Server endpoints and Resource Server endpoints used directly by the Client

  1. shall support TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

  2. shall support TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

  3. The "TLS Session Resumption" e "TLS Renegotiation" features shall be disabled

...

  • string 'consent'; and

  • delimiter of a colon ":"; and

  • Consent API REST Resource Id as returned by a successful creation of Open Finance Consent Resource;

In addition:

  • the Consent Resource Id must include url safe characters only;

  • the Consent Resource Id must be namespaced;

  • the Consent Resource Id must have the properties of a nonce Nonce;

7.1.3. Dynamic Consent Scope Example

...

In addition to the requirements outlined in Open Finance Brasil security provisions the Authorization Server

  1. shall only issue refresh_accesstokens on presentation of a _refreshtoken when the consent resource the refresh token is bound to is active and with "AUTHORIZED" status;tokens when linked to an active and valid consent;

    1. Must not issue refresh_token when consent status is "CONSUMED" (for phase 3);

    2. Must issue an access_token through the grant_type client credentials when consent status is "CONSUMED"(for phase 3).

  2. shall only share access to resources when presented with an access_accesstoken linked to an active and valid consent; 2.1. In the Invalid Token Receive scenarioconsent and with the status "AUTHORISED“. For tokens generated with the scope: payments, the status of the consent will not be validated.

    1. In the scenario of receiving an invalid token, status code 401 should be returned.

  3. shall revoke refresh tokens and, access tokens where aplicable, when the linked Consent Resource is deleted;

  4. shall ensure access tokens are issued with sufficient scope necessary for access to data specified in the Permission element of a linked Consent Resource object;

  5. shall not reject an authorisation request requesting scopes broader than those necessary to access data specified in the Permissions element of a linked Consent Resource object;

  6. may reduce requested scope to a level sufficient to enable access to data resources specified in the Permissions element of a linked Consent Resource object;

  7. shall retain a complete audit history of the consent resource in accordance with current Central Bank brazilian regulation;

  8. shall return authentication failure and return code _accessdenied accessdenied in the error parameter (as specified in section 4.1.2.1 of RFC6749) if the CPF of the authenticated user is not the same as indicated in the loggedUser element of the Consent Resource Object;

  9. shall return authentication failure and return code _accessdenied accessdenied in the error parameter (as specified in section 4.1.2.1 of RFC6749) if the businessEntity element has not been populated in the related Consent Resource Object and the user has selected or authenticated by using a credential related to a business account;

  10. an autenticated or selected business account's CNPJ must match the value present in the businessEntity element of the Consent Resource Object. In case of divergence authorization server shall return authentication failure and return code _accessdenied accessdenied in the error parameter (as specified in section 4.1.2.1 of RFC6749);

  11. shall ensure _refreshtokens refreshtokens expiration time is at least equal to the linked consent resource expiration time.

...

  1. shall revoke where possible and cease usage of refresh and access tokens that are bound to a Consent Resource that has been deleted;

  2. shall delete Consent Resource that are expired;

...

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

...