Implementer’s note about Open Banking Brasil

OBB Financial-grade API Security Profile

Open Banking Brasil Financial-grade API Security Profile 1.0 on top of the FAPI 1.0 specification

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 1
shall support a signed and encrypted JWE request object passed by value or shall require pushed authorization requests PAR;

Passing a Request Object by Value
Overview of OAuth 2.0 Pushed Authorization Requests (PAR)

request_object_encryption_alg

OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used, since this signals to the OP that a client_secret value needs to be returned from which the symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present. If both signing and encryption are requested, the Request Object will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted, is that the RP is not declaring whether it might encrypt any Request Objects.

request_object_encryption_enc

OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. If request_object_encryption_alg is specified, the default for this value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg MUST also be provided.

“Encryption in Front Channel” Option in Authlete

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 2
shall distribute discovery metadata (such as the authorization endpoint) via the metadata document as specified in OIDD and [RFC8414]

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 3
shall support the claims parameter as defined in clause 5.5 OpenID Connect Core

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 4
shall support the oidc standard claim “cpf” as defined in clause 5.2.2.2 of this document

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 5
shall support the oidc standard claim “cnpj” as defined in clause 5.2.2.3 of this document if providing access to resources where the resource owner is not a natural person

Supported Claims (Screenshot of Authlete’s Service Owner Console)

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 6
shall support the acr “urn:brasil:openbanking:loa2” as defined in clause 5.2.2.4 of this document

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 7
should support the acr “urn:brasil:openbanking:loa3” as defined in clause 5.2.2.4 of this document

Supported ACR Values (Screenshot of Authlete’s Service Owner Console)

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 8
shall implement the userinfo endpoint as defined in clause 5.3 OpenID Connect Core

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 9
shall support parameterized OAuth 2.0 resource scope consent as defined in clause 6.3.1 OIDF FAPI WG Lodging Intent Pattern

A “regex” attribute to support the Dynamic Consent Scope

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 10
may support Financial-grade API: Client Initiated Backchannel Authentication Profile

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 11
shall support Financial-grade API: Client Initiated Backchannel Authentication Profile if supporting scope payments

Concept of CIBA

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 12
shall support refresh tokens

OBB FAPI 1.0, 5.2.2. Authorization server, Clause 13
shall issue access tokens with an expiry no greater than 900 seconds and no less than 300 seconds

OBB FAPI 1.0, 6.1. Algorithm considerations

For JWS, both clients and Authorization Servers

1. shall use PS256 algorithm;

{Header}.{Payload}.{Signature}

FAPI 1.0 Advanced, 8.6. Algorithm considerations

For JWS, both clients and authorization servers

1. shall use PS256 or ES256 algorithms;

2. should not use algorithms that use RSASSA-PKCS1-v1_5 (e.g. RS256); and

3. shall not use none.

OBB FAPI 1.0, 6.1.1. Encryption algorithm considerations

For JWE, both clients and Authorization Servers

1. shall use RSA-OAEP with A256GCM

Two-Step Encryption
Options for Request Object Encryption Algorithms
Consent API Call + Authorization Request
Consent API Call + PAR Request + Authorization Request

OBB Dynamic Client Registration

Open Banking Brasil Dynamic Client Registration on top of standards
Client Registration Endpoint
Client Registration Request Using a Software Statement
Example of the mtls_endpoint_aliases Server Metadata
Configuration of MTLS Endpoint Aliases

OBB DCR 1.0, 7.1. Authorization server, Clause 1

shall reject dynamic client registration requests not performed over a connection secured with mutual tls using certificates issued by Brazil ICP (production) or the Directory of Participants (sandbox);

OBB DCR 1.0, 7.1. Authorization server, Clause 2

shall validate that the request contains software_statement JWT signed using the PS256 algorithim issued by the Open Banking Brasil directory of participants;

Verification of Signature of Software Statement

OBB DCR 1.0, 7.1. Authorization server, Clause 3

shall validate that the software_statement was issued (iat) not more than 5 minutes prior to the request being received;

{
"iat": 1620060821,
......
}

OBB DCR 1.0, 7.1. Authorization server, Clause 4

shall validate that a jwks (key set by value) was not included;

OBB DCR 1.0, 7.1. Authorization server, Clause 5

shall require and validate that the jwks_uri matches the software_jwks_uri provided in the software statement;

OBB DCR 1.0, 7.1. Authorization server, Clause 6

shall require and validate that redirect_uris match or contain a sub set of software_redirect_uris provided in the software statement;

OBB DCR 1.0, 7.1. Authorization server, Clause 7

shall require and validate that all client authentication mechanism adhere to the requirements defined in Financial-grade API Security Profile 1.0 — Part 2: Advanced;

OBB DCR 1.0, 7.1. Authorization server, Clause 8

shall require encrypted request objects as required by the Brasil Open Banking Security Profile;

OBB DCR 1.0, 7.1. Authorization server, Clause 9

shall validate that requested scopes are appropriate for the softwares authorized regulatory roles;

"software_roles": [
"DADOS",
"PAGTO"
],

OBB DCR 1.0, 7.1. Authorization server, Clause 10

should where possible validate client asserted metadata against metadata provided in the software_statement;

OBB DCR 1.0, 7.1. Authorization server, Clause 11

shall accept all x.500 AttributeType name strings defined in the Distinguished Name of the x.509 Certificate Profiles defined in Open Banking Brasil x.509 Certificate Standards;

// The pre-registered value of tls_client_auth_subject_dn.
String tlsClientAuthSubjectDn = ...;
// Convert the string into a form suitable for comparison.
X500Pricipal expectedPrincipal =
new X500Princial(tlsClientAuthSubjectDn);

If the AttributeType is of the dotted-decimal form, the AttributeValue is represented by an number sign (‘#’ U+0023) character followed by the hexadecimal encoding of each of the octets of the BER encoding of the X.500 AttributeValue.

// Mappings from descriptor to OID
Map<String, String> map = new HashMap<>();
map.put("JURISDICTIONCOUNTRYNAME", "1.3.6.1.4.1.311.60.2.1.3");
map.put("BUSINESSCATEGORY", "2.5.4.15");

// Convert a string to an X500Principal instance with additional
// information about mappings from descriptor (AttributeType name
// string) to OID so that the Distinguished Name parser under the
// X500Principal class can recognize the descriptors.
X500Principal expectedPrincipal =
new X500Principal(tlsClientAuthSubjectDn, map);

OBB DCR 1.0, 7.1. Authorization server, Clause 12

if supporting tls_client_auth client authentication mechanism as defined in RFC8705 shall only accept tls_client_auth_subject_dn as an indication of the certificate subject value as defined in clause 2.1.2 RFC8705;

Supported Custom Client Metadata
"authlete:frontChannelRequestObjectEncryptionRequired":true
Client Registration Endpont for OBB-Specific Requirements

Sample Implementation

Finally

--

--

Co-founder and representative director of Authlete, Inc., working as a software engineer since 1997. https://www.authlete.com/

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store