Registration Framework

1. Introduction

The Open Finance UAE Registration Framework, grounded in the OIDC Federation principles, aims to offer detailed implementation guidelines to enhance the security and interoperability of the ecosystem. These guidelines are intended for the identification, registration, and management of OIDC Relying Parties within the Open Finance UAE Ecosystem.

Federation, as a mechanism, establishes trust between interacting federation entities (for example, a fintech application and a bank) through a trusted third party, or a Trust Anchor (the Trust Framework). This Standard delineates the interactions within this distributed trust network, known as a federation.

1.1 Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174].

1.2 Terminology

Trust Anchor: An entity that represents a trusted third party, for example, a Trust Framework provider.
Federation Entity: An entity for which it is possible to contrast a trust chain from itself to the Trust Anchor.

Trust Framework: A set of standards, protocols, and components designed to establish trust and facilitate secure data sharing between organizations. It offers a robust framework for authentication, authorization, and encryption, safeguarding data integrity and confidentiality throughout the sharing process.

Data Receiver: Entity that can access data provided by other organizations to build new products and services.

Data Provider: Entity that offers customer-permission data to other organizations (Data Receivers) in a secure and controlled way.

Relying Party (RP): An application or website that outsources its user authentication function to an IDP.

OpenID Provider (OP): Also referred to as an Identity Provider (IDP) or an authorization server. It is an entity that implemented the OIDC and OAuth protocols.

2. Rationale for Choosing OIDC Federation as Profile Foundation

This document proposes adopting the OpenID Connect (OIDC) Federation model as the underlying framework for the UAE's Registration Profile. This approach aims to streamline the data access journey, enabling Authorized Data Receivers (e.g., Fintechs Onboarded into the Trust Framework) to interact with Data Providers without the need for a pre-registration step.

OIDC Federation addresses and resolves the interoperability challenges observed in other open finance ecosystems, such as Open Finance Brazil and Open Banking UK, which rely on OAuth Dynamic Client Registration (DCR) RFC7591.

2.1 Simplifying the Data Access Path for Data Receivers

The OIDC Federation model, particularly as outlined in Section 11.1 of the OIDC Federation specification, introduces an automated registration mechanism. This allows Data Receivers to initiate Authentication Requests directly, bypassing traditional registration with Data Providers. Upon integration into the Ecosystem Trust Framework, Data Receivers are allocated a unique client_id, bound to their created encryption and transport certificates. These credentials are utilized to authenticate the Data Receiver’s requests and secure token issuance via the Data Provider's Authorization Server Endpoints.

To enable this process, Data Providers must proactively acquire relevant metadata based on their client_id from the Trust Anchor, ensuring the registered Data Receiver metadata is always up-to-date.

2.2 Reduced Interoperability Problems and Improved Standardization

The DCR framework, employed in both the Brazil’s and the UK's Open Banking implementations, necessitates that Clients ( Data Receivers ) initiate contact with the Servers ( Data Providers ) registration endpoint to onboard. This process has led to:

2.3 Ensuring Responsibility Spread for Client Registration to the Fewest Number of Actors

Within the Proposed Registration Framework, the responsibility for registration entirely rests with the Data Providers. They are required to actively consult and regularly update data from the Trust Anchor (Trust Framework). This ensures they keep an up-to-date registry of all authorized Clients in the Ecosystem.

The Standard also specifies that when Data Providers encounter an Authentication Request from an unrecognized Data Receiver, they must fetch the client's data from the Trust Anchor. This is to accurately ascertain the client's access scopes, regardless of whether the regular updates have been properly conducted.

2.4 Cross-Border Integration Support

OIDC Federation supports the setup of unified trust network across multiple trust anchors through standardized metadata acquisition mechanisms.

This structure can be used to promote interoperability and trust among clients and servers across different ecosystems, fostering a seamless cross-border integration framework.

It’s important to note that while there is an expectation of Cross Border Integration between Open Finance UAE and other Data Sharing Ecosystems, no agreements have yet been established by CBUAE, with this being a mid to long-term objective.

3. Open Finance UAE OpenID Connect Discovery Provisions

To enhance clarity and precision in our documentation, it's important to delineate the scope of application regarding the integration between the Trust Framework and the Open Finance Hub. This section is presented as a policy statement, emphasizing that its directives are specifically tailored to the interface between these two entities. There is no broader implication for the ecosystem as a whole within this segment. The detailed requirements and protocols outlined here are pertinent solely to the Client section, which stakeholders within the ecosystem should focus on.

3.1 Authorization Server

The Authorization Server shall support OpenID Connect Discovery as required by the FAPI 2.0 Security Profile. This support shall be explicit in the Ecosystem Trust Framework configurations and the declaration of its attributes in the Discovery file (.well-known).

In addition, the Authorization Server:

1. Shall advertise its presence in the Open Finance UAE ecosystem by being listed on the Ecosystem Trust Framework.

2. Shall advertise all Open Finance UAE API resources on the Ecosystem Trust Framework.

3. Shall advertise support for all signing, encryption, authentication mechanisms and standards required to support the Open Finance UAE FAPI Profile.

4. Shall advertise mtls_endpoint_aliases as per clause 5 RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens, which shall include the token_endpoint, userinfo_endpoint and push_authorization_request_endpoint.

Within the Open Finance UAE Ecosystem, the responsibility for managing the Authorization Servers falls to the API Hub. Consequently, the provisions outlined above are directly related to the integration between the Hub and the Trust Framework. This section serves as a policy statement, specifically addressing this context. It does not imply broader repercussions for the ecosystem as a whole, except as it facilitates the Discovery Process executed by the Client.

3.2 Client Application

The Client shall assume its Client Identifier to be used with all the Authorization Servers on the Ecosystem to be equal to its Entity Identifier within the Open Finance UAE Federation, as defined by the Ecosystem Trust Framework upon creation of a Software Statement Resource.

In addition, the Client:

1. Shall rely on ecosystem discovery services provided by the Trust Framework only.

2. Shall derive necessary Authorisation Server metadata by relying on an Authorization Servers OpenID Connect Discovery services only.

3. Shall obtain the information about the Resource Server endpoints using the Trust Framework Participants endpoint, reached on - <To be Included once the TF is Fully Live>

4. Shall use endpoints advertised in the mtls_endpoint_aliases authorization server’s metadata object as per clause 5 RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens.

4. Open Finance UAE OpenID Connect Registration Provisions

The Authorization Server shall support the OIDC Federation with Automatic Registration.

In addition, the Authorization Server :

1. Shall trust all the Entity Statements issued by the “Open Finance UAE” Trust Anchor, whose entity configuration can be reached on - <To be Included once the TF is Fully Live>

2. Shall validate the Trust Chain Entity Statements signature using the keys supplied only by the Open Finance UAE Federation.

3. Shall obtain the list of authorized Relying Parties and their Entity Identifiers by using the Open Finance UAE Federation list endpoint.

4. Shall register the Relying Parties and issue them Client Identifiers (client_id) that have a value equal to their Entity Identifiers within the Open Finance UAE Federation.

5. Shall onboard all Relying Parties that have status set as “Active”

6. Shall deny any Token requests from Relying Parties with metadata containing status equal to “Inactive” or “Suspended”

7. Shall obtain the Relying Parties Entity Statements by calling their Well-Known URIs, issued by the Trust Framework, which can be obtained by appending /.well-known/openid-federation to their Entity Identifiers.

8. Shall only trust the information provided on the Entity Statement until the time defined on the “expiration” (exp) claim - Entity Statements are expected to

9. Shall maintain the integrity of all the associated consent resources, authorization grants and refresh tokens, upon successful registration of a new Relying Party and preserve the resources for a minimum duration of 30 days after either :

   1. Its status has been set as Inactive or

   2. The expiration of the Relying Party’s latest verified Entity Statement.

10. Shall maintain an updated registry of the authorized Relying Parties metadata by periodically fetching the Entity Statements and the Entity Identifiers from the Federation List Endpoint

    • The maximum validity period of an Entity Statement is 24 hours. This means that the difference between the "issued at" (iat) and "expiration" (exp) claims within an Entity Statement shall not exceed 24 hours.

11. Shall transition clients to the suspended status if it is not possible to verify the Relying Partie’s metadata – due to the inaccessibility or corruption of the Entity Statement. In the suspended state, clients cannot be issued new access tokens but all the linked consent resources, authorization grants, and refresh tokens remain intact.

12. Shall verify the Entity Statement validity against the Open Finance UAE Federation Trust Chain and consider the Relying Partie’s metadata before processing the authentication request if the authorization server receives an unknown client identifier while authenticating the client.

5. Entity Statement - Relying Party Metadata

An Entity Statement contains the information needed for the Entity to participate and be subject to a Federation. The Entity Statement is signed using the private key of the issuer Entity in the form of a JSON Web Signature (JWS) [RFC7515]. The information contained inside the Entity Statement shall only be trusted once its signature has been validated using the Trust Chain of the trusted Federations Anchors.

The Following Attributes can be identified, and should be processed by Open ID Providers on the Relying Party Entity Statement Parsed JSON, under metadata.openid_relying_party:

Attributes not defined above shall ignored by the Authorization Servers when registering existing clients as they do not serve a purpose in the Open Finance UAE Ecosystem.

The “How is it Managed” column defines how the values on a specific attribute can be updated, the three possible values are :

• Regulatory Roles: This property is defined by the Regulatory Roles assigned to the Client on the Trust Framework - They will be updated once a role is assigned or revoked.

• Trust Framework: This property is defined Automatically by the Trust Framework and can only be altered by the Ecosystem Global Administrators.

• Participant: This property is defined by the Organization Administrators or Users when configuring the Client on the Trust Framework.

6. Non-Normative Examples

6.1 Attributes of the Relying Parties Entity Statements

The following is an example of the JSO body of a Relying Parties Entity Statement after it has been parsed from its original JWT format :

{
  "authority_hints": [
    "https://federation.sandbox.raidiam.io/federation_entity/221a1d6c-2ab2-4b43-9baf-dd8dbda5047b",
    ,
  "exp": 1709686928,
  "iat": 1709683328,
  "iss": "https://rp.sandbox.raidiam.io/openid_relying_party/703ec16c-b1c6-479c-b01b-cbb29ba78579",
  "jwks": {
    "keys": [
      {
        "e": "AQAB",
        "n": "i6tLgmVIaFgGz9oW3AnjeOi1LG0XxnJEwWgbo5HN0KcncscvUPKAfs3LqidvTemlXvjx0gGgSbQEeh8Hz8ZzTLMrFrugzCOZkGgPhIhS4TfrdgVZDUEjf2scFYSHBUj96GTtwzZ4ojJyEiQZq6TSIr_JCNE0L2QtI5jQEiVg032KA7K2ybQQCuV0v_5zcKL37xgxxl2Et554I45Z3mOZT5E3y6VX5q-hUQlwbOr_Lpg2huBkxxvuQWeuKSZ03CkazUrP7kk7w_2tVxD_ggv8QhoihPhpmI5_ytOLWgl5Pabdfcko_HwgNMoigmBSLYjwHuhF1XO4eZPkGzIajahNxw",
        "kty": "RSA",
        "kid": "mrk-093eca7d9865403fa9e9175e609541b5"
      }
    ]
  },
  "metadata": {
    "openid_relying_party": {
      "client_id": "https://rp.sandbox.raidiam.io/openid_relying_party/703ec16c-b1c6-479c-b01b-cbb29ba78579",
      "client_name": "Web Channel Application",
      "client_uri": "https://www.raidiam.com",
      "client_description": "This is the Description for the My Bank Conglomerate Web Channel Client",
      "client_registration_types": [
        "automatic"
      ],
      "claims": [
        "example",
      ],
      "grant_types": [
        "client_credentials",
        "refresh_token",
        "authorization_code",
        "implicit"
      ],
      "jwks_uri": "https://keystore.sandbox.raidiam.io/d46bd24f-cc59-48c6-935a-a7724d1ab4d6/703ec16c-b1c6-479c-b01b-cbb29ba78579/application.jwks",
      "logo_uri": "https://www.sweetbank.com/file.jpg",
      "organisation_name": "My Bank Conglomerate",
      "policy_uri": "https://www.policy.com",
      "redirect_uris": [
        "https://www.callback.com"
      ],
      "require_signed_request_object": true,
      "response_types": [
        "code"
      ],
      "scope": "accounts credit-cards loans",
      "status": "Active",
      "use_mtls_endpoint_aliases": True,
      "token_endpoint_auth_method": "private_key_jwt",
      "authorization_detail_types":[
        "urn:openfinanceuae:service-initiation-consent:*",
        "urn:openfinanceuae:account-access-consent:*"
      ],
      "sector_identifier_uri": "https://keystore.sandbox.raidiam.io/d46bd24f-cc59-48c6-935a-a7724d1ab4d6/703ec16c-b1c6-479c-b01b-cbb29ba78579/redirect_uris.json",
      "software_id": "703ec16c-b1c6-479c-b01b-cbb29ba78579",
      "software_version": "1.00",
      "subject_type": "public",
      "tos_uri": "https://www.tos.com",
      "organisation_id": "d46bd24f-cc59-48c6-935a-a7724d1ab4d6",
    }
  },
  "sub": "https://rp.sandbox.raidiam.io/openid_relying_party/703ec16c-b1c6-479c-b01b-cbb29ba78579"
}

6.2 Attributes of the Federation Entity Statements

The following is an example of the json body of a Federation Entity Entity Statement, after it has been parsed from its original JWT format :

{
  "exp": 1709687032,
  "iat": 1709683432,
  "iss": "https://federation.sandbox.raidiam.io/federation_entity/221a1d6c-2ab2-4b43-9baf-dd8dbda5047b",
  "jwks": {
    "keys": [
      {
        "e": "AQAB",
        "n": "rr_yX_SnQ4aTz6DnWw8jvbIBP-gH6JLc8zvBPfDzWvv0_tdGEhxaEXM5WFT9hi1cddwD-KZ8841PVZcpiFKP9F9LxuHg4W8Cs7vYayIjNj166tysocP1gNjYR-ijt5Tx1pzCT5L9WHf9AQT-9CrpwUB4sUHfdUfPc4ohlRQd2GUMX-uSiXzhURpr6_hmDIYMIWCOL9sRY3-yikxI-ceJLnzohjpwmYjmKckvhz_ZgLxAt75hzJ35J4E7m0uZK4gs3xVBj0KnzldrPKU5UyDuKTb37OZYkkZ4tTCQB6Bt339GWk3j5OjDoAtExtFgdZnIQTQPK45x8-HNskBLayl3qQ",
        "kty": "RSA",
        "kid": "mrk-1c1da9c740ba4c628de298d73bc1f017"
      }
    ]
  },
  "metadata": {
    "federation_entity": {
      "federation_fetch_endpoint": "https://federation.sandbox.raidiam.io/federation_entity/221a1d6c-2ab2-4b43-9baf-dd8dbda5047b/fetch",
      "federation_list_endpoint": "https://federation.sandbox.raidiam.io/federation_entity/221a1d6c-2ab2-4b43-9baf-dd8dbda5047b/list",
      "homepage_uri": "https://www.raidiam.com/",
      "logo_uri": "https://www.raidiam.com/wp-content/uploads/2023/09/products-bkg.png",
      "organization_name": "Raidiam Federation",
      "policy_uri": "https://docs.connect.raidiam.io/raidiam"
    }
  },
  "sub": "https://federation.sandbox.raidiam.io/federation_entity/221a1d6c-2ab2-4b43-9baf-dd8dbda5047b"
}

6.3 Attributes of the Federation List Endpoint

The following is an example of the return of a Federation List Endpoint, obtained on the Federation Entity Entity Statement :

[
    "https://rp.sandbox.raidiam.io/openid_relying_party/cd97ec54-0dbe-4a14-8aa0-ec8243360e3d",
    "https://rp.sandbox.raidiam.io/openid_relying_party/0a2b8426-ba92-4ecd-be5c-99a418faf766",
    "https://rp.sandbox.raidiam.io/openid_relying_party/9a19d809-5d14-4388-bcc3-c7f0cccbf9dd",
    "https://rp.sandbox.raidiam.io/openid_relying_party/8c2435c8-5823-47f6-a37d-5ea7d1b18f53",
    "https://rp.sandbox.raidiam.io/openid_relying_party/a0e2203c-079b-4448-b4bc-d0ba5c5802fd",
    "https://rp.sandbox.raidiam.io/openid_relying_party/090ee3b8-ad26-4931-a4ec-02390630f298",
    "https://rp.sandbox.raidiam.io/openid_relying_party/a75548ef-4d68-405d-83a1-25f07bfccaec",
    "https://rp.sandbox.raidiam.io/openid_relying_party/0a3e8622-9ef6-41f2-9ecc-8d788e430455",
 ]

7. Processing and Registering the Entity Statements on the Open Finance UAE Federation

The diagram below provides a high-level visualization of the Registration Journey expected to be undertaken by Data Providers in the Open Finance UAE Ecosystem for the Open Finance UAE Relying Parties.

8. Alternative Registration Provisions - Trust Framework Clients Endpoint

The Open Finance UAE ecosystem, in addition to supporting the OIDC Federation Standard, introduces an mTLS-protected endpoint that aggregates Relying Party Metadata into a consolidated JSON file, serving as an alternate mechanism for Authorization Servers to facilitate client onboarding within the UAE Ecosystem. This approach remains viable until integration into a broader federation necessitates a full transition to Federation Registration processes to guarantee cross-ecosystem interoperability.

The structure and accessibility of the Clients Endpoint, including the JSON Schema detailing required Relying Party Metadata fields, are delineated in the Trust Framework API Documentation. Access to this endpoint is restricted to entities possessing valid Client Certificates as issued by the Trust Framework, ensuring secure and authenticated interactions.

8.1 Clients Endpoint Registration Provisions

If the Authorization Server opts to utilize the Client Endpoint Registration Method instead of the OIDC Federation, the Authorization Server :

1. Shall obtain the list of list of Relying Parties, inclusive of their Client Identifiers and associated metadata, exclusively via the Open Finance UAE Trust Framework Clients Endpoint - https://matls-api.directory.openfinance.ae/clients.

2. Shall onboard for the active Relying Party the metadata attributes returned by the Clients Endpoint contained under “Entity Statement - Relying Party Metadata”.

3. Shall onboard all Relying Parties that have status set as “Active”

4. Shall deny any Token requests from Relying Parties with metadata containing status equal to “Inactive” or “Suspended”

5. Shall ensure the registry of Relying Parties and their metadata is refreshed each 6 hours at the minimum.

6. Shall update the metadata of all Relying Parties upon each Clients Endpoint access, contingent upon the last_updated attribute being more recent than the current registry data.

7. Shall maintain the integrity of all the associated consent resources, authorization grants and refresh tokens, upon successful registration of a new Relying Party and preserve the resources for a minimum duration of 30 days after its status has been set as Inactive or after its details are no longer returned on the Clients Endpoint;

8. Shall transition clients to the Suspended status if it is not possible to verify the Relying Partie’s metadata – due to the inaccessibility or corruption of the Entity Statement. In the suspended state, clients cannot be issued new access tokens but all the linked consent resources, authorization grants, and refresh tokens remain intact.

8.2 Non-Normative Example - Clients Endpoint

The following is an example of the JSON Payload returned by the Trust Framework clients endpoint :

[ 
  {
            "client_description": "This is the Description for the Raidiam Client",
            "client_name": "TestClient",
            "client_uri": "https://www.raidiam.com",
            "redirect_uris": [
                "https://www.redirect.com"
            ],
            "grant_types": [
              "client_credentials",
              "refresh_token",
              "authorization_code",
              "implicit"
            ],
         
            "logo_uri": "https://www.raidiam.com/logo.png",
            "scope": "accounts credit-cards loans",
            "jwks_uri": "https://keystore.sandbox.raidiam.io/d46bd24f-cc59-48c6-935a-a7724d1ab4d6/703ec16c-b1c6-479c-b01b-cbb29ba78579/application.jwks",
            "software_id": "4d8d5aed-2c1c-428a-b0b3-8069b6b3c69e",
            "software_version": 1.00,
            "client_id": "https://rp.sandbox.raidiam.io/openid_relying_party/703ec16c-b1c6-479c-b01b-cbb29ba78579",
            "subject_type": "public",
            "sector_identifier_uri": "https://keystore.sandbox.directory.openbankingbrasil.org.br/b961c4eb-509d-4edf-afeb-35642b38185d/4d8d5aed-2c1c-428a-b0b3-8069b6b3c69e/redirect_uris.json",
            "status": "Active",
            "organisation_id": "b961c4eb-509d-4edf-afeb-35642b38185d",
            "use_mtls_endpoint_aliases": True,
            "token_endpoint_auth_method": "private_key_jwt",
            "authorization_detail_types":[
              "urn:openfinanceuae:service-initiation-consent:*",
              "urn:openfinanceuae:account-access-consent:*"
            ]
            "last_updated": "2023-02-28T12:18:13.936Z",
        }
]