New names for Financial-grade API specifications

The OpenID Foundation currently supports certification for three different versions of the FAPI specifications:

1. FAPI Part 2 Read/Write Implementers Draft 2 (often written FAPIRWID2 or similar), as published October 2018.
2. FAPI 1.0 Part 2 Advanced Final, as published March 2021.
3. FAPI 2.0 Security Profile Implementers Draft 2 and FAPI 2.0 Message Signing Implementers Draft 1

FAPI 1.0 Advanced Final is an evolution of the FAPI RW draft. The ‘read write’ part was removed from the specification name to avoid confusion, due to many ecosystems choosing to use the more secure ‘read write’ profile for read-only operations.

The FAPI working group has published a summary of the differences between the two versions, the differences are generally minor changes that reflect how best practice has evolved between 2018 and 2021.

You can learn more about the differences between FAPI 1.0 and FAPI 2.0 on our blog post.

If in doubt, you would normally test against the latest ‘final’ specification – FAPI 1.0 Advanced Final.

Introduction

This page describes how to run conformance tests and gather testing results for OpenID Providers (OPs) using either of the above specifications.

Currently only FAPI-RW / FAPI Advanced (i.e. FAPI part 2) have a certification program. The parts of FAPI-RW that are not currently tested are described on our wiki: https://gitlab.com/openid/conformance-suite/wikis/OP-FAPI-RW-Test-Status

There are tests available for FAPI-R / FAPI Baseline (i.e. part 1); these are not complete. It is not necessary to run FAPI-R tests when certifying for FAPI-RW.

If your server complies with the UK OpenBanking specification, you should run only the ‘FAPI-RW-ID2: Authorization server test’ and in the test configuration options select ‘openbanking_uk’ as the ‘FAPI Profile’. These allow you to demonstrate compliance with both FAPI-RW and the OpenBanking UK Profile of FAPI-RW. The ‘openbankinguk’ variants are a superset of the FAPI-RW-ID2 tests, with the major difference being that OB compliant authorization servers require pre-registration of intent using an OB specific API for an authorization to succeed.

There are also separate tests for FAPI-CIBA; please see the FAPI-CIBA conformance instructions if you have an implementation of CIBA you would like to test.

Setup Steps

Register two clients in your authorisation server and the necessary keys/certificates (the keys and certificates used for each client must be different). Two clients are necessary as the suite tests various mixup attacks, for example, using a valid access token from one client with the TLS client certificate from the other client.

The redirect URLs for the clients must be:

• https://www.certification.openid.net/test/a/ALIAS/callback
• https://www.certification.openid.net/test/a/ALIAS/callback?dummy1=lorem&dummy2=ipsum

ALIAS must be replaced with a string that is unique to you/your organisation, to avoid other conformance suite users affecting your testing.

Please include the ?dummy1=lorem&dummy2=ipsum string in the redirect url exactly as written. The conformance suite will use both redirect URLs.

The IP address the conformance suite will make outgoing calls from is 35.196.44.185, also available on the suite home page after login.

Instructions for Running Tests

1. Open https://www.certification.openid.net/.
2. Login using a Google or GitLab account, or any Op that supports WebFinger. (Any google or gitlab account can be used. The login process is purely to protect access to the test data – the system is open for anyone to use.)
3. Click “Create a test plan”.
4. Select the relevant test plan from the “Select a Test Plan” dropdown menu, one with “FAPI-RW-ID2: Authorization server test” or “FAPI1-Advanced-Final: Authorization server test” in the name
5. DO NOT pick a test plan that has ‘client’ in the name. These are not applicable when testing an OpenID Provider.
6. Select the test options; this depends on your client authentication type(s) and whether your server follows the openbanking uk specification or not. For example, on a FAPI-RW compliant server that supports oauth-mtls client authentication you should select ‘Client Authentication Type
   ‘ mtls. For a server that complies with the openbanking uk specification, select ‘openbanking_uk’ as the ‘FAPI Profile’.
7. Fill in the configuration form (hover over the ‘i’ for guidance on a field). You can switch to the “JSON” tab to view/edit the configuration in the underlying JSON format. Changes to the form are automatically reflected in the JSON and vice versa. The JSON can be copied and saved locally to be pasted back in later. The server will automatically remember the most recent JSON you successfully created a test with. A “real world” example of a full working configuration is available here: https://gitlab.com/openid/conformance-suite/wikis/Authlete-Example-Configuration.
8. Note that both client JWK sets must contain an ‘alg’ field. For FAPI-RW this is most usually ‘PS256’, but ‘ES256’ is also permitted.
9. A resource server URL must be provided. This must be a simple GET endpoint that returns JSON and is used to test certificate binding of access tokens etc. (Specific values must be used in the country specific tests, see the help for the field.)
10. Press “Launch Test Plan”. You will be taken to a list of all the test modules in the plan.
11. Press “Run New Test” on the first test module.
12. Please read the description of the test in the light blue box near the top of the log page – this may contain specific instructions, for example one test requires that the user rejects the authentication process.
13. If applicable, click on the “Visit” button, and login to your OP; some tests require you to do this more than once. You will be either be:
    1. directed back to the test suite, in which case hit the link to return to the log page, or:
    2. shown an error by the AS. If the error is expected (i.e. is mentioned in the light blue summary box on the log page), you should screenshot it and upload it to the conformance suite on the log detail page.
14. When the test has completed, press “Continue Plan” to start the next test, or “Return to Plan” to view your progress.

If you require support, please email certification@oidf.org. If it relates to a test failure, please include a link to the relevant log-detail.html, or if using a local install the downloaded log file.

Once you have successfully completed testing, please follow the submission instructions to complete the certification process.

About the Conformance Suite

For more information, please see about the conformance suite.

‘Plain FAPI’ specific notes

For FAPI1 implementors not targeting the various ecosystems (as mentioned below), the server is expected to support the acr value ‘urn:mace:incommon:iap:silver’. This is not required by the specs, but is required for the tests to run correctly.

app2app Specific Notes

The conformance suite can also be used to test mobile apps that implement ‘app2app’, as used widely in the UK OpenBanking ecosystem and described at Implementing App-to-App Authorisation in OAuth2/OpenID Connect.

Technically this is testing the web2app scenario, but there are no significant differences on the authorization server side between web2app and app2app.

Please note that app2app tests should be run on a tablet sized device; see issue 865.

FAPI2 Specific Notes

OpenBanking UK Specific Notes

The conformance suite can also run tests against implementations and live deployments compliant to the FAPI-aligned OpenBanking UK standard. These tests are a superset of the FAPI-RW tests, and compliance with the FAPI UK OpenBanking test profile also demonstrates compliance to the FAPI-RW profile.

The main differences are:

1. OpenBanking UK authorization servers require an Intent ID to be created prior to authorisation using an access token obtained with the client credentials grant, which is then passed as an essential claim in the request object.
2. OpenBanking UK defines ecosystem-specific ACR values.

The suite requests only the ReadAccountsBasic permission.

The process of creating clients for the Conformance Suite is akin to on-boarding a Third Party, except that the suite and the credentials issued remain in the control of the ASPSP. The client credentials should be revoked after testing. The suite only requires AISP permission, as only this protocol is accessed during the flow, and only the ReadAccountsBasic permission is used. The suite does not require any significant customer data to be available; a dummy / reference account can be used.

When configuring the suite, the resource server url should be set to the base URL for the AISP endpoints, for example:
https://rs.example.com/open-banking/v3.1/aisp/.

Australian CDR Specific Notes

Tests can also be run against CDR compliant deployments.

The main differences are due to extra requirements in the CDR specifications, namely:

1. private_key_jwt must be used
2. required x-v header is sent to resource server endpoint
3. Refresh tokens must be supported (the sharing_duration claim will be requested when a refresh token must be returned)
4. Returned id_tokens must be encrypted
5. For ACR claims, a CDR specific value is used, “urn:cds.au:cdr:2”
6. x-fapi-auth-date header is included in all resource endpoint calls (it’s optional in FAPI but mandatory in CDR)
7. x-cds-client-headers header is included when the x-fapi-customer-ip-address header is sent

Brazil OpenBanking Specific Notes

The main differences are due to extra requirements in the Brazil specifications, namely:

1. A Brazil-specific pre-lodged intent mechanism is used, and passed via a structured scope
2. Encrypted request objects are required when passed via the front channel
3. Refresh tokens must be supported
4. Access token lifetime must be between 300 and 900 seconds (inclusive).
5. Only PS256 is permitted

An example configuration for Brazil is available.

Dynamic client registration tests are also available for Brazil (these are specific to the Brazil ecosystem, the tests cannot be passed unless your authorization server accepts software statements generated by a Brazil OpenBanking directory). There is an example configuration for the DCR tests.

KSA/SAMA OpenBanking Specific Notes

As per the KSA specific specification:

1. Pushed authentication requests (PAR) are mandatory
2. JWT Secured Authorization Response Mode (JARM is not used)
3. Client credentials grant is used to obtain an access token with scope=accounts
4. account-access-consents is used to create a ConsentId prior to test running – only one permission is requested: ReadAccountsBasic
5. ConsentId is pass in request object to PAR endpoint in a parameterized scope
6. accounts endpoint is expected to be used for resource endpoint tests

We have been told by the regulator that KSA banks are expected to always certify for MTLS client authentication, and may also optional certify for private_key_jwt client authentication.

Please note that the KSA FAPI Profile specifications are not currently publicly published but will be soon. In the meantime, to ensure that all interested entities can understand the necessary details to pass the KSA version of the FAPI certifications tests, a snapshot of the specifications are available here.

ConnectID Specific Notes

Getting help

If you would like any help, please email certification@oidf.org. If it relates to a test failure, please include a link to the relevant log-detail.html, or if using a local install the downloaded log file.

If you think you have found a bug, please report it in gitlab.