Implementer’s note about Open Banking Brasil

This article explains technical details of Open Banking Brasil (OBB), especially differences between OBB extensions and global standard specifications.

July 24, 2021: I greatly appreciate Carol Morais and Skalena translating this article into Portuguese and publishing it at “Notas de um implementador sobre Open Banking Brasil”.

OBB Financial-grade API Security Profile

Specification Stack

OBB published “Open Banking Brasil Financial-grade API Security Profile 1.0 Implementers Draft 1” (hereinafter referred to as “OBB FAPI”) late in May, 2021. As of this writing, the specification has been being updated since then through discussion on GitHub (OpenBanking-Brasil/specs-seguranca) and in workshops and maybe somewhere else I’m unaware of. In that sense, the specification is not stable yet. (So this article will be updated in future accordingly.)

The OBB FAPI specification is built on top of the final version of “Financial-grade API Security Profile 1.0” (hereinafter referred to as “FAPI 1.0”) which was published in March, 2021.

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

The FAPI 1.0 specification consists of “Part 1: Baseline” and “Part 2: Advanced”. The Advanced Security Profile (Part 2) defines stricker requirements than the Basline Security Profile (Part 1) does. The OBB FAPI specification requires that implementations conform to the Advanced Security Profile.

Please read “Financial-grade API (FAPI), explained by an implementer” for technical details of the FAPI 1.0 specification. Also, the Portuguese translation “Financial-grade API (FAPI), Explicada por um Desenvolvedor” is availabe on the website of OpenID Foundation.

OBB Authorization Server Requirements

The OBB FAPI specification has a section titled “5.2.2. Authorization server”. The section lists additional requirements for authorization servers. That is, the requirements there are differences between the OBB FAPI specification and the FAPI 1.0. Let’s read them one by one.

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;

To begin with, you need to know what a “request object” is. It is a JWT (RFC 7519: JSON Web Token) that includes request parameters of an authorization request. If you are not familiar with request object, please read the FAPI blog.

Passing a Request Object by Value

In FAPI 1.0 Advanced, request objects must always be signed, but they don’t have to be encrypted. On the other hand, OBB FAPI requires that request objects be always encrypted unless the authorization request is registered in advance using PAR.

PAR here means “OAuth 2.0 Pushed Authorization Requests”. It is a relatively new specification which defines a way where a client application registers an authorization request in advance and gets a “request URI” in return, and then later the client application makes an authorization request with the issued request URI. By using this mechanism, the client application can avoid sending authorization request parameters by value via a web browser; “via a web browser” is sometimes expressed like “through the front channel”. Please read “Illustrated PAR: OAuth 2.0 Pushed Authorization Requests” for the overview of PAR.

Overview of OAuth 2.0 Pushed Authorization Requests (PAR)

“OpenID Connect Dynamic Client Registration 1.0” defines two client metadata related to request object encryption as follows.

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.

The part I emphasized states “The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present.” This means that an authorization server does not reject unencrypted request objects even if the request_object_encryption_alg client metadata of the client application is set.

Because the specification is defined in that way, an authorization server cannot rely on the standard request_object_encryption_alg client metadata if the server wants to reject unencrypted request objects passed through the front channel. As a result, the service provider or the solution vendor of the authorization server has to customize its implementation for the OBB-specific requirement.

For example, Authlete implemented the “Encryption in Front Channel” feature as a configuration option of both the server and the client for the purpose. The feature is available since Authlete 2.2.11.

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

OIDD here is short for “OpenID Connect Discovery 1.0”. The specification defines an endpoint called “discovery endpoint” which returns server metadata in JSON format. The JSON is called “discovery document”. The discovery endpoint itself is not OBB-specific.

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

In “OpenID Connect Core 1.0” (OIDC Core), an authorization server does not necessarily have to support the claims request parameter. The server can advertise whether it supports the parameter or not by using the claims_parameter_supported server metadata in the discovery document.

All discovery documents of authorization servers in the Open Banking Brasil ecosystem will include "claims_parameter_supported":true because the support is mandatory.

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

The 4th and 5th clauses require that an authorization server support the cpf claim and conditionally the cnpj claim. Although the OBB FAPI specification uses the word “oidc standard claim”, they are not included in the list of the standard claims defined in “5.1. Standard Claims” of OIDC Core. The cpf claim and the cnpj claim are OBB-specific.

The claims should be included in the claims_supported server metadata in the discovery document. Otherwise, some OBB test cases in the official conformance suite will fail.

It is highly likely that your authorization server implementation provides a mechanism whereby to list supported claims like below. Otherwise, it would be impossible to advertise the OBB-specific claims in the discovery document.

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

The 6th and 7th clauses require that an authorization server support the urn:brasil:openbanking:loa2 ACR value and optionally the urn:brasil:openbanking:loa3 ACR value. loa in the ACR values means “Level of Assurance”. You can find the definitions of LoA2 and LoA3 in “X.1254 : Entity authentication assurance framework”.

The ACR values should be included in the acr_values_supported server metadata in the discovery document. To achieve this, it is highly likely that your authorization server implementation provides a mechanism whereby to list supported ACR values like below. Otherwise, it would be impossible to advertise the OBB-specific ACR values in the discovery 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

The UserInfo endpoint returns information about the user who is associated with the presented access token. The format of responses from the endpoint is plain JSON unless the userinfo_signed_response_alg client metadata and/or the userinfo_encrypted_response_alg client metadata of the client application is set.

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

This clause requires a feature that is often referred to as “parameterized scope” or “dynamic scope”. The feature enables scope values (which are listed in the scope request parameter) to have dynamic values which are determined at runtime.

Some authorization servers support the feature, but basically their implementations are not interoperable. The main reason is that there is no standard in regard to the format of dynamic scope values. Some variants may be simple like “a fixed prefix + dynamic part” (e.g. myprefix:123456), others may be more complex like printer:print,manage, *:view, etc.

From the experience of UK Open Banking and other ecosystems, the OAuth community realized that they should develop a standard way that can replace non-interoperable “dynamic scope” features in the wild. After a long discussion, the community developed “OAuth 2.0 Rich Authorization Requests” a.k.a. RAR. The new specification is to be a part of FAPI 2.0 as stated in the FAPI FAQ.

Therefore, when the community noticed that OBB was going to adopt their own “dynamic scope” feature, they recommended RAR to OBB. However, inspite of some trials of persuasion, OBB did not follow the recommendation and decided to go with the dynamic scope feature.

It depends on each implementation how developers can use the feature. A certain implementation requires that developers write a script to parse dynamic scopes in exchange for maximum flexibility. Others may be much easier to use but lack flexibility.

In the case of Authlete, developers can use the dynamic scope feature by attaching a “regex” attribute to a scope. The “regex” attribute represents the regular expression of a dynamic scope. If a scope value included in the scope request parameter matches the regular expression, the scope value is recognized.

For example, by attaching a “regex” attribute whose value is ^consent:.+$ to the consent scope, an authorization server can support the “Dynamic Consent Scope” which is defined in “7.1.2. Dynamic Consent Scope Definition” of the OBB FAPI specification. See “Using parameterized scopes” on Authlete Knowledge Base for details.

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

The “Financial-grade API: Client Initiated Backchannel Authentication Profile” a.k.a. FAPI-CIBA Profile defines additional requirements that authorization servers should conform to when they support FAPI and CIBA at the same time.

Client Initiated Backchannel Authentication a.k.a. CIBA defines new authorization flows that are different from the traditional ones defined in RFC 6749: The OAuth 2.0 Authorization Framework. The most important point of CIBA is that it separates the “authentication device” (on which user authentication is performed) from the “consumption device” (which obtains an access token and calls Web APIs). This separation enables to support new use cases. Please read “CIBA, explained by an implementer” for technical details of CIBA.

Concept of CIBA

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

In RFC 6749, “refresh token” support is optional. The OBB FAPI specification makes it mandatory.

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

The OBB FAPI specification puts a restriction on the lifetime of access tokens.

It depends on each implementation how to configure the lifetime of access tokens. Modern implementations provide several ways to configure it. Typical patterns are per-server configuration and per-client configuration. In addition, per-scope configration may be provided. See “How Authlete determines token duration” if you are interested in examples of actual implementations.

OBB Algorithm Requirements

“6. Security considerations” of the OBB FAPI specifications lists some requirements related to algorithms.

OBB FAPI 1.0, 6.1. Algorithm considerations

For JWS, both clients and Authorization Servers

1. shall use PS256 algorithm;

JWS here means “JSON Web Signature”. Its specification is defined in RFC 7515. JWS is a format for “signed data”. This implies that JWS contains a “signature” in addition to data itself. The following is the structure of JWS. See “Understanding ID Token” for details about JWS (and JWE and JWT).

{Header}.{Payload}.{Signature}

In any case, for the signature, a signing algorithm is needed. RFC 7518: JSON Web Algorithms (JWA) lists the following signing algorithms for JWS.

• HS256 — HMAC using SHA-256
• HS384 — HMAC using SHA-384
• HS512 — HMAC using SHA-512
• RS256 — RSASSA-PKCS1-v1_5 using SHA-256
• RS384 — RSASSA-PKCS1-v1_5 using SHA-384
• RS512 — RSASSA-PKCS1-v1_5 using SHA-512
• ES256 — ECDSA using P-256 and SHA-256
• ES384 — ECDSA using P-384 and SHA-384
• ES512 — ECDSA using P-521 and SHA-512
• PS256 — RSASSA-PSS using SHA-256 and MGF1 with SHA-256
• PS384 — RSASSA-PSS using SHA-384 and MGF1 with SHA-384
• PS512 — RSASSA-PSS using SHA-512 and MGF1 with SHA-512
• none — No digital signature or MAC performed

FAPI 1.0 Advanced puts restrictions on permitted signing algorithms as below.

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.

In short, in the context of FAPI 1.0 Advanced, permitted signing algorithms for JWS are PS256 and ES256 only.

The requirement of the OBB FAPI specification on JWS signing algorithm is more restrictive than that of FAPI 1.0 Advanced. In the context of OBB, PS256 is the only permitted signing algorithm for JWS.

OBB FAPI 1.0, 6.1.1. Encryption algorithm considerations

For JWE, both clients and Authorization Servers

1. shall use RSA-OAEP with A256GCM

JWE here means “JSON Web Encryption”. Its specification is defined in RFC 7516. JWE is a format for “encrypted data”.

In most cases, JWE uses two algorithms for two-step encryption as illustrated below (excerpted from “Understanding ID Token”).

Two-Step Encryption

The two-step encryption is the reason that JWE-related metadata are defined as a pair of *_alg and *_enc. For instance, OpenID Connect Dynamic Client Registration 1.0 defines request_object_encryption_alg and request_object_encryption_enc client metadata for request object encryption.

RSA-OAEP in the section 6.1.1 of OBB FAPI is an identifier that represents “RSAES OAEP using default parameters”. The indentifier is defined in “4.1. “alg” (Algorithm) Header Parameter Values for JWE” of RFC 7518. As the section title itself states, the identifier is used as a value for the alg parameter in the JWE header. Encryption-related client metadata that end with _alg can take an identifier defined in the section. For example, the id_token_encrypted_response_alg client metadata can be RSA-OAEP.

Likewise, A256GCM in the section 6.1.1 of OBB FAPI is an identifer defined in “5.1. “enc” (Encryption Algorithm) Header Parameter Values for JWE” of RFC 7518. As the section title itself states, the identifier is used as a value for the enc parameter in the JWE header. Encryption-related client metadata that end with _enc can take an identifier defined in the section. For example, the userinfo_encrypted_response_enc client metadata can be A256GCM.

It should be noted that configuring a *_alg client metadata for encryption does not necessarily force the client application to use the algorithm. As I mentioned previously, for instance, even if RSA-OAEP is set to the request_object_encryption_alg client metadata, the authorization server does not reject request objects encrypted with a different algorithm. Furthermore, the authorization server does not reject request objects even if they are not encrypted.

If an authorization server wants to reject request objects encrypted with a different algorithm than RSA-OAEP to conform to the OBB-specific requirement strictly, it cannot rely on the standard client metadata. This means that custom development or a vendor-dependent mechanism is needed to meet the OBB requirement.

In the case of Authlete, the mechanism whereby to force encryption algorithms for request objects is provided as “Encryption Algorithm Match” and “Encryption Encoding Algorithm Match” options in the “Request Object” section as shown below.

Options for Request Object Encryption Algorithms

Note that similar options for other client metadata (e.g. id_token_encrypted_response_alg, userinfo_encrypted_response_alg and authorization_encrypted_response_alg) are not needed because other JWTs than request objects are encrypted by an authorization server, not by a client application.

Dynamic Consent Scope

To follow the “Lodging Intent” pattern of UK Open Banking, OBB defined an OBB-specific flow where a client application obtains a “Consent ID” from the “Consent API” in advance and then makes an authorization request with the Consent ID. That is, an extra step is needed before starting the traditional OAuth 2.0 flow. The diagram below shows the flow.

Consent API Call + Authorization Request

If PAR is used, one more extra step is inserted as the diagram below illustrates.

Consent API Call + PAR Request + Authorization Request

In either case, the issued consent ID is embedded in the scope request parameter of the subsequent API call. When it is embedded, the prefix consent: is prepended. For example, when the issued consent ID is urn:bancoex:C1DD33123, consent:urn:bancoex:C1DD33123 is included in the scope request parameter as a scope value.

Authorization servers for OBB must be able to recognize the Dynamic Consent Scope which has the format of consent:{ConsentID}. See “7.1. Authorisation Mechanism” of the OBB FAPI specification for details.

OBB Dynamic Client Registration

Specification Stack

OBB published “Open Banking Brasil Financial-grade API Dynamic Client Registration 1.0 Implementers Draft 1” (hereinafter referred to as “OBB DCR”) late in May, 2021. As of this writing, the specification has been being updated since then as the OBB FAPI specifications has.

There are three standards related to “Dynamic Client Registration” (hereinafter referred to as “DCR”) as listed below.

• OpenID Connect Dynamic Client Registration 1.0 (OIDR)
• RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol
• RFC 7592: OAuth 2.0 Dynamic Client Registration Management Protocol

The OBB DCR specification is built on top of these standard specifications.

Open Banking Brasil Dynamic Client Registration on top of standards

Basics of Dynamic Client Registration

An authorization server that supports DCR provides a Web API called “Client Registration Endpoint”. The endpoint accepts JSON including client metadata, registers the metadata into its database, and issues a client ID that corresponds to the registered metadata. The issued client ID can be used as a value for the client_id request parameter of authorization requests, token requests and so on.

Client Registration Endpoint

“2. Client Metadata” of OIDR defines many standard client metadata such as client_name and redirect_uris. RFC 7591 also has a section titled “2. Client Metadata”. And, various other specifications define client metadata as necessary.

An interesting but complex mechanism that RFC 7591 has introduced is “software statement”. It is a JWT whose payload lists client metadata. A client registration request may include a software statement with other client metadata. Client metadata inside the software statement and those outside are merged when registered. If client metadata having the same name exist both inside and outside the software statement, the one inside takes precedence.

Client Registration Request Using a Software Statement

OBB Discovery Requirements

“6.1. Authorization server” of the OBB DCR specification lists requirements for the discovery endpoint. Among them, a point that draws implementers’ attention is that the mtls_endpoint_aliases server metadata is mandatory.

The mtls_endpoint_aliases server metadata is defined in “RFC 8705: OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens”. Its value is a JSON object holding pairs of an endpoint name and its location. The following is the example shown in “5. Metadata for Mutual-TLS Endpoint Aliases” of RFC 8705.

Example of the mtls_endpoint_aliases Server Metadata

When an authorization server wants to support (a) client authentication methods which utilize a client certificate (tls_client_auth and self_signed_tls_client_auth) and/or (b) certificate-bound access tokens, connections between client applications and the server’s endpoints must be “mutual TLS”. This means that the server administrator configures the endpoints so that they request a client certificate during a TLS handshake. In this case, the discovery document of the authorization server may list the names and locations of the endpoints in the mtls_endpoint_aliases server metadata.

In RFC 8705, the use of the mtls_endpoint_aliases server metadata is optional even if endpoints require a client certificate during a TLS handshake. On the other hand, the server metadata is mandatory in the OBB DCR specification.

It depends on each implementation how to include the mtls_endpoint_aliases server metadata in the discovery document. The simplest implementation will let the administrator edit a static file that is the very discovery document of the authorization server. Others may provide other means. In the case of Authlete, GUI for editing entries of the mtls_endpoint_aliases server metadata is provided like below.

Configuration of MTLS Endpoint Aliases

OBB Dynamic Client Registration Requirements

“7.1. Authorization server” of the OBB DCR specification lists requirements for DCR. Let’s read them one by one.

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

In a mutual TLS connection, both the server and the client send their X.509 certificates to each other. In the OBB ecosystem, such certificates have to be issued by a particular issuer (Brazil ICP or Sandbox). Please read “Illustrated X.509 Certificate” if you are not familiar with X.509 certificates.

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;

DCR requests in OBB must contain a software statement which has been issued by the Open Banking Brasil Directory. This means that the API caller must obtain a software statement in advance before making a DCR request.

Implementations of Client Registration Endpoint must validate the software statement included in a DCR request. The most important part of the validation is to confirm that the software statement has been signed by the OBB Directory.

To verify the signature of the software statement, the verifier (the implementation of Client Registration Endpoint in this context) must obtain the public key which corresponds to the private key which was used to generate the signature.

The public key is included in the JWK Set Document (RFC 7517: JSON Web Key (JWK)) exposed through the JWK Set Endpoint of the Directory.

The diagram below illustrates the steps from issuance of a software statement to verification of the signature of the software statement.

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;

By definition, the format of the payload part of a JWT is JSON. Entries in the payload part are called “claims”. The JWT specification (RFC 7519: JSON Web Token) defines some standard claims. The iat claim is one of them and it represents the time the JWT was issued at. The value is the number of seconds elapsed since the Unix epoch (January 1, 1970). The following snippet shows what the iat claim looks like.

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

The OBB DCR specification requires that an authorization server confirm that the value of the iat claim in the software statement is in the range between 5 minutes ago and the current time.

OBB DCR 1.0, 7.1. Authorization server, Clause 4

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

The jwks client metadata must not be included in a DCR request. The jwks client medata is a standard one defined in OIDR and RFC 7591. These specifications state that jwks and jwks_uri must not both be present in the same DCR request.

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;

While the jwks_uri client metadata is a standard one, software_jwks_uri is a custom parameter for OBB that is included in a software statement issued by the OBB Directory.

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;

In other words, the redirect_uris client metadata must not include values that are not listed in the software_redirect_uris claim.

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;

In the context of FAPI 1.0 Advanced, permitted client authentication methods are three as listed below.

• private_key_jwt (defined in RFC 7523)
• tls_client_auth (defined in RFC 8705)
• self_signed_tls_client_auth (defined in RFC 8705)

The 7th clause requires that the value of client metadata whose value is a client authentication method be one of private_key_jwt, tls_client_auth and self_signed_tls_client_auth. Among known standard client metadata, token_endpoint_auth_method is the only one that meets the condition.

In summary, what an authorization server has to do for the 7th clause is to confirm that the value of the token_endpoint_auth_method client metadata is private_key_jwt, tls_client_auth or self_signed_tls_client_auth.

However, practically speaking, self_signed_tls_client_auth won’t work because a self-signed certificate is not allowed in OBB.

If you want to learn more details about client authentication, please read “OAuth 2.0 Client Authentication”.

OBB DCR 1.0, 7.1. Authorization server, Clause 8

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

In the context of DCR, “shall require encrypted request objects” means that the request_object_encryption_alg client metadata and the request_object_encryption_enc client metadata shall be set properly.

If a DCR request contains these client metadata, their values must be RSA-OAEP and A256GCM, respectively, as required by the OBB FAPI specification.

On the other hand, if a DCR request does not contain them, the implementation of Client Registration Endpoint should complement the DCR request with "request_object_encryption_alg":"RSA-OAEP" and "request_object_encryption_enc":"A256GCM".

OBB DCR 1.0, 7.1. Authorization server, Clause 9

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

A software statement issued by the OBB Directory contains the software_roles claim like below.

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

“7.2. Regulatory Roles to OpenID and OAuth 2.0 Mappings” has a table that shows what scopes are allowed for each regulatory role that may appear in the software_roles claim.

The values listed in the scope client metadata should be checked with the table. However, the validation logic is unclear, especially in cases where multiple roles are listed and where scope values not listed in the table are included.

OBB DCR 1.0, 7.1. Authorization server, Clause 10

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

Propbably this means that it should be checked whether values match when client metadata having the same name exist both inside and outside the software statement.

In any case, RFC 7519 requires “client metadata values conveyed in the software statement MUST take precedence over those conveyed using plain JSON elements.”

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;

“AttributeType name strings”, also called as “descriptors”, are aliases of OIDs (Object Identifiers). For example, the AttributeType name string “CN” is an alias of the OID “2.5.4.3”.

“3. Parsing a String Back to a Distinguished Name” of “RFC 4514: Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names” (which was published in June 2006) requires that the following descriptors be recognized.

• CN — 2.5.4.3 (commonName)
• L — 2.5.4.7 (localityName)
• ST — 2.5.4.8 (stateOrProvinceName)
• O — 2.5.4.10 (organizationName)
• OU — 2.5.4.11 (organizationalUnitName)
• C — 2.5.4.6 (countryName)
• STREET — 2.5.4.9 (streetAddress)
• DC — 0.9.2342.19200300.100.1.25 (domainComponent)
• UID — 0.9.2342.19200300.100.1.1 (userId)

So, it is highly likely that your “Distinguished Name” parser recognizes these descriptors.

Among the descriptors mentioned in “5.2.2. Client Certificate” of “Open Banking Brasil Certificate Standards 1.0”, the following are not included in RFC 4514 but can be found in “RFC 4519: Lightweight Directory Access Protocol (LDAP): Schema for User Applications”.

• serialNumber — 2.5.4.5
• businessCategory — 2.5.4.15

On the other hand, the descriptor below is not found in either of the RFCs.

• jurisdictionCountryName — 1.3.6.1.4.1.311.60.2.1.3

Your Distinguished Name parser may fail to recognize some of the descriptors above. For example, theX500Principal class in my Java environment does not recognize businessCategory and jurisdictionCountryName.

Even if descriptors are not recognized, your “X.509 certificate” parser will not fail. It’s because X.509 certificates use OIDs internally instead of descriptors. But, if you are writing a program that parses a Distinguished Name (not an X.509 certificate) directly, unrecognized descriptors will cause a problem.

In the layer of OAuth/OIDC implementations, this kind of problems may occur arround the processing of the tls_client_auth_subject_dn client metadata which is defined in RFC 8705.

When the client authentication method of a client application is tls_client_auth and the tls_client_auth_subject_dn client metadata is registered, the authorization server checks whether (a) the Distinguished Name of the subject of the X.509 certificate presented by the client application matches (b) the pre-registered value of the tls_client_auth_subject_dn client metadata.

To do this comparison, the authorization server converts the pre-registered string into a form suitable for the comparison. For instance, an implementation written in Java may convert it to an X500Principal instance like below.

// 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);

At this timing, if the pre-registered value contains unrecognized descriptors like jurisdictionCountryName = BR, the constructor of X500Principal throws an exception.

A simple way to solve this problem is to avoid using unrecognized descriptors in the value of the tls_client_auth_subject_dn client metadata and instead to use the OIDs like 1.3.6.1.4.1.311.60.2.1.3 = BR.

But, to conform strictly to a sentence in “2.4. Converting an AttributeValue from ASN.1 to a String” of RFC 4514,

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.

your Distinguished Name parser may require that the value part be encoded in the format of “# + hexadecimals” like #13024252.

Another way is to give information about mappings from descriptor to OID to your Distinguished Name parser. In the case of X500Principal, it can be achieved by writing a code like below.

// 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);

In either case, the comparison should be performed by comparing OIDs, not descriptors.

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;

RFC 8705 requires that one and only one of the following client metadata be registered for the tls_client_auth client authentication method.

• tls_client_auth_subject_dn
• tls_client_auth_san_dns
• tls_client_auth_san_uri
• tls_client_auth_san_ip
• tls_client_auth_san_email

In the context of OBB DCR, the tls_client_auth_san_* client metadata must be rejected.

Custom Client Metadata

The sample DCR request shown in the OBB DCR specification includes some non-standard client metadata such as org_name and software_roles.

It depends on each implementation whether custom client metadata are registered or discarded. In the case of Authlete, custom client metadata are registered only when they are explicitly listed as supported custom client metadata like below.

Supported Custom Client Metadata

Registered custom client metadata are accessible as the value of the customMetadata property of Client. See the JavaDoc of Client.getCustomMetadata() for details.

Vendor-Specific Client Properties

It depends on each implementation how to define the data structure of a client application. It is highly likely that the data structure has properties that correspond to standard client metadata but at the same time it may have other properties that do not have corresponding standards.

To configure client properties that do not have corresponding standard client metadata at the timing of DCR, solution vendors may provide custom mechanisms.

In the case of Authlete, some client metadata that have prefix authlete: are recognized. For example, when a DCR request contains a client metadata like below,

"authlete:frontChannelRequestObjectEncryptionRequired":true

the client is configured accordingly (sample code → OBBDCRProcessor.java).

In addition, Authlete provides a set of client management APIs (/api/client/*) from the beginning. Please refer to the Authlete API document or the JavaDoc of the authlete-java-comon library for details. The JavaDoc is always up-to-date; it sometimes contains even information about new features that have not been implemented yet.

Implementation for OBB DCR Requirements

Because the requirements by the OBB DCR specification are too OBB-specific, no vendor solution can meet the requirements off the shelf unless vendors fork their prodcuts to develop a variant dedicated to OBB.

Therefore, some or all parts of Client Registration Endpoint have to be implemented by customers. One of possible approaches is as follows.

1. [customer] Implement a front Client Registration Endpoint that accepts DCR requests from outside.
2. [customer] Extract a software statement from a DCR request and perform OBB-specific validation.
3. [customer] Construct a DCR request by merging the client metadata inside the software statement and ones outside.
4. [customer] Send the newly constructed DCR request (which does not include software_statement) to the Client Registration Endpoint of the authorization server (e.g. a vendor solution) sitting behind.
5. [vendor solution] Process the flatten DCR request as required by global standards.
6. [customer] Get a response from the backend authorization server and pass the response to the original API caller.

The diagram below illustrates this approach.

Client Registration Endpont for OBB-Specific Requirements

In the case of Authlete, “Authorization Server” in the diagram is Authlete and its “Client Registration Endpoint” is Authlete’s /api/client/registration API. “Customer’s Frontend” is what Authlete’s customers are required to implement.

ClientRegistrationEndpoint.java in java-oauth-server is a sample code of “Client Registration Endpoint (front)”. The steps to “perform OBB-specific validation” and “construct a DCR request including no software statement” are implemented in OBBDCRProcessor.java.

Sample Implementation

java-oauth-server is an open-source sample implementation of an authorization server which uses Authlete as a backend service. It includes sample codes of some OBB-specific APIs.

• Accounts API (→ /api/obb/accounts; AccountsEndpoint.java)
• Consent API (→ /api/obb/consents; ConsentsEndpoint.java)
• Resources API (→ /api/obb/resources; ResourcesEndpoint.java)

In addition, the sample implementation of Client Registration Endpoint (→ /api/register; ClientRegistrationEndpoint.java) does OBB-specific validation when a DCR request includes a software statement issued by the OBB Directory. The most interesting part is in OBBDCRProcessor.java. The source code shows how the OBB DCR specification should be interpreted and implemented.

Note that the sample codes for OBB do not work if the version of the backend Authlete server is older than Authlete 2.2.11. Because the current version of Authlete on the shared server (api.authlete.com) is 2.1.x (it will be upgraded in near future, though), you cannot try the OBB sample codes with the shared server. Please contact Authlete, Inc. (via the contact form or email to sales@authlete.com) to access the latest Authlete.

Finally

Thank you for reading till the end. Authlete has already been adopted by some banks in Brazil. For example, by the world’s largest digital bank and by the largest investment bank in Latin America. Please consider Authlete for your Open Banking Brasil! 🇧🇷