Comparação de Páginas

...

Este documento também está disponível em português

The Open Banking Finance Brasil Initial Structure is responsible for creating standards and specifications necessary to meet the requirements and obligations of the Brasil Open Banking 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. OBBIS OFBIS shall not be held responsible for identifying any or all such patent rights.

Open Banking Finance Brasil Financial-grade API Security Profile 1.0 consists of the following parts:

...

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 Banking Finance programme.

Notational Conventions

...

• 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 Banking 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 Banking Finance in Brasil.

2. Normative references

...

LIWP - OIDF FAPI WG Lodging Intent Working Paper

OBB-FAPI-DCR - Open Banking Finance Brasil Financial-grade API Dynamic Client Registration Profile 1.0

...

API - Application Programming Interface

OBBIS OFBIS - Open Banking Finance Brasil Initial Structure

CSRF - Cross Site Request Forgery

...

5.1. Introduction

The Brasil Open Banking 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 Banking 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 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 CIBA flow.

5.2. Open Banking Brasil CIBA Security provisions

5.2.1. Introduction

Open Banking 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 Banking Finance Brasil ecosystem.

As a profile of the OAuth 2.0 Authorization Framework, this document mandates the following for the Brasil Open Banking Finance Security profile.

5.2.2. Authorization server

...

1. shall distribute discovery metadata (such as the authorization endpoint) via the metadata document as specified in OIDD and [RFC8414]

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

3. shall support the oidc standard claim "cpf" as defined in clause 5.2.2.2 of [FAPI-BR]

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

5. shall support the acr "urn:brasil:openbanking:loa2" as defined in clause 5.2.2.4 of FAPI-BR

6. should support the acr "urn:brasil:openbanking:loa3" as defined in clause 5.2.2.4 of [FAPI-BR]]

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. shall support refresh tokens

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

11. shall always include an acr claim in the id_token

12. shall require the Signed Authentication Request to contain nbf and exp claims that limit the lifetime of the request to no more than 10 minutes

13. shall issue ciba auth request acknowledgements with a minimum expiry of 6 minutes;

5.2.3. Confidential client

In addition, the confidential client

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

2. shall support refresh tokens

5.2.4. Resource Owner identity hint mechanisms

5.2.4.1. Introduction

As described in FAPI-CIBA, there are many mechanisms that can be used to convey a Resource Owners identity from the Consumption Device to the Authorization Server however in call cases this identity attestation must be treated as a hint only. There are naturally limitations on the types of id hints that can be captured by the consumption device based on the input and output contraints of the device being used. In addition to input and output challenges, there are several key privacy and security conerns that must be evaluated when defining id conveyance processes. This profile defines several login hint types that must be supported by authorisation servers.

FAPI-CIBA requires requests to be signed, there is no requirement in Brazil to additionally sign these hints as they are all asserted by the Client.

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

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

• aud the Authorization Servers advertised issuer as per OIDD;

• iss the receiver of the message shall validate if the value of the iss field matches the clientId of the sender;

• jti the value of the jti field shall be filled with the UUID defined by the institution according to [RFC4122] version 4;

• iat the iat field shall be filled with the message generation time and according to the standard established in RFC7519 to the NumericDate format.

• *exp the exp field shall be filled with the message expiry time and according to the standard established in RFC7519 to the NumericDate format with an maximum value not greater than 5 minutes;

• auth_request_id the authentication request id returned from the Authorisation Server CIBA requst.

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 listed on the software statement keystore on the Open Banking Brasil Directory of Participants;

   • typ - shall be filled with the value cibabr+jwt.

JWE Creation

1. The JOSE header must contain the following attributes:

2. alg - shall be filled with the value RSA-OAEP";

3. enc - shall be filled with the value A256GCM";

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

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;

5. The id_token shall have a minimum expiration of 180 days;

6. The id_token shall be used in the authorization call through the "id_token_hint" parameter

7. The "poll mode" shall be the only mode used to obtain a token for the payment sending via the bc-authorize endpoint.

8. The cancellation of the id_token shall be carried out by the account holder institution in cases of fraud or for security reasons.

9. Error table “HTTP 400 Bad Request”:

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

2. invalid_scope: The requested scope is invalid, unknown, or malformed.

3. expired_id_token_hint: The id_token hint provided in the authentication request is not valid because it has expired.

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

5. unauthorized_client: The Client is not authorized to use this authentication flow.

6. invalid_id_token_hint: The id_token is invalid and can’t be used in the flow

20. shall issue ciba auth request acknowledgements with a maximum expiry of 5 minutes;

21. Payload validation

22. Parameters for signature validation

All parameters must be present in the JWT header.

5.2.3. Confidential client

In addition, the confidential client

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

2. shall support refresh tokens

5.2.4. Resource Owner identity hint mechanisms

5.2.4.1. Introduction

As described in FAPI-CIBA, there are many mechanisms that can be used to convey a Resource Owners identity from the Consumption Device to the Authorization Server however in call cases this identity attestation must be treated as a hint only. There are naturally limitations on the types of id hints that can be captured by the consumption device based on the input and output contraints of the device being used. In addition to input and output challenges, there are several key privacy and security conerns that must be evaluated when defining id conveyance processes. This profile defines several login hint types that must be supported by authorisation servers.

FAPI-CIBA requires requests to be signed, there is no requirement in Brazil to additionally sign these hints as they are all asserted by the Client.

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

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

• aud the Authorization Servers advertised issuer as per OIDD;

• iss the receiver of the message shall validate if the value of the iss field matches the clientId of the sender;

• jti the value of the jti field shall be filled with the UUID defined by the institution according to [RFC4122] version 4;

• iat the iat field shall be filled with the message generation time and according to the standard established in RFC7519 to the NumericDate format.

• *exp the exp field shall be filled with the message expiry time and according to the standard established in RFC7519 to the NumericDate format with an maximum value not greater than 5 minutes;

• auth_request_id the authentication request id returned from the Authorisation Server CIBA requst.

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

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

...

• backchannel_endpoint_login_hint_token_types_supported: REQUIRED. 

  • JSON array containing one or more of the following values:

    • 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. 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 Banking Finance Brasil GT Security and to the pioneers who will stand on their shoulders.

...

Appendix A. Notices

Copyright (c) 2023 Open Banking Finance Brasil Initial Structure.

The Open Banking Finance Brasil Initial Structure (OBBISOFBIS) 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 OBBIS OFBIS as the source of the material, but that such attribution does not indicate an endorsement by the OBBISOFBIS.

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation, the Open Banking Finance Brasil GT Security Working Group and others. Although the Open Banking 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 Banking 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 Banking 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 Banking 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

OBBIS OFBIS GT Security

Open Banking Finance Brasil Initial Structure

Email: gt-seguranca@openfinancebrasil.org.br

URI: https://openfinancebrasil.org.br