Conformance Testing for FAPI Read/Write RPs


You can use the FAPI conformance suite (https://www.certification.openid.net/) to test your FAPI-RW ID2 and FAPI 1 Final Relying Party (RP) implementations.
In this case the conformance suite acts as the OpenID Provider (OP) and your client implementation acts as the relying party.

Please note that you can use a local instance of the FAPI conformance suite for your internal purposes but you must use https://www.certification.openid.net/ for certification submissions. You cannot certify with results obtained from a local instance.

Before You Begin

  • When submitting your test results, you must include logs from both the conformance suite and your client implementation. Please make sure that your client logs contain all the necessary information, e.g enabling debug level logging before running the tests may be needed.
  • When using a local instance of the conformance suite software, a self-signed certificate will be used for https endpoints. You may need to disable certificate checks in your client software.
    https://www.certification.openid.net uses valid certificates issued by Letsencrypt and disabling certificate checks should not be necessary.

Testing Steps

  1. Go to https://www.certification.openid.net/ or to your local conformance suite instance, e.g https://localhost:8443/.
    1. When using https://www.certification.openid.net/, log in using a Google or GitLab account, or any OpenID Provider that supports WebFinger.
  2. Select a FAPI client test plan from the “Select A Test Plan” dropdown, e.g FAPI1-Advanced-Final: Relying Party (client test).
    • For Open Banking Brazil certification, “FAPI1-Advanced-Final: Open Banking Brazil Relying Party (Client) Test Plan” must be selected.
  3. From the “Client Authentication Type” dropdown, select “mtls” or “private_key_jwt” testing depending on which type of client authentication you support.
  4. From the “Request Object Method” dropdown (if visible), select “pushed” if using PAR.
  5. From the “FAPI Profile” dropdown (if visible), select an option corresponding to an Open Banking ecosystem or select “plain_fapi” if you are not testing conformance to a specific Open Banking ecosystem.
  6. From the “FAPI Response Mode” dropdown (if visible), select “plain_response” or “jarm”. Please note that jarm mode is not included in the certification programme yet.
  7. From the “FAPI JARM Type” dropdown (if visible), select one of “oidc” or “plain_oauth”. When “plain_oauth” is selected then the suite will not issue any id_tokens. This field is applicable only when JARM response type is also selected.
  8. Fill in the configuration form (as per the guidance given in the form fields when empty). 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.

    • Server jwks must include private keys. Keys provided in server jwks will be used as the server keys for your tests.
      • For “Open Banking Brazil” test plans, server jwks MUST contain one key usable for signing (i.e use=sig) and one key usable for encryption (i.e use=enc).
    • Contrary to what the tooltip implies, client jwks does not need to include private keys. Only the public keys will be used ​
    • For plans based on “FAPI 1 Advanced Final”, two clients are required. The first client will be used for
      most tests. The second client will be used for encrypted id_token tests and jwks for the second client must contain an encryption key, e.g a key with use=enc.
  9. Click “Start Test Plan” button. You will be taken to a list of all the test modules in the plan.
  10. Click a “Run New Test” button
  11. Please read the description of the test in the light blue box near the top of the log page – this field usually contains specific instructions for the test being run.
  12. Runtime values that your client needs to use will be displayed by the test suite as highlighted in the following screenshot. The conformance suite will wait for requests from your client.
    RP Testing Runtime Variables
  13. For FAPI-RW ID2 testing, your client is typically expected to perform the following steps:

    1. Do OpenID discovery, using the discoveryUrl shown in the test suite front end.
    2. Redirect to the authorization_endpoint obtained from discovery.
    3. The conformance suite will return a 302 redirect straight away without the user taking any action – so there is no need for this to even be in a web browser.
    4. Exchange the authorization code for an access token at the token_endpoint obtained from discovery.
    5. Call the accounts_endpoint displayed on the screen using the access token.
  14. For Openbanking UK testing, your client is typically expected to perform the following steps:
    1. Do openid discovery, using the discoveryUrl shown in the test suite front end.
    2. Send a client_credentials request to the token_endpoint obtained from discovery.
    3. Create an account request, by sending a request to the account_requests_endpoint displayed on the screen.
    4. Redirect to the authorization_endpoint obtained from discovery.
    5. The conformance suite will return a 302 redirect straight away without the user taking any action – so there is no need for this to even be in a web browser.
    6. Exchange the authorization code for an access token at the token_endpoint obtained from discovery.
    7. Call the accounts_endpoint displayed on the screen using the access token.
  15. For Openbanking Brazil testing, your client is typically expected to perform the following steps:
    1. Do openid discovery, using the discoveryUrl shown in the test suite front end.
    2. Send a client_credentials request to the token_endpoint obtained from discovery.
    3. Create a consent request, by sending a request to the consents_endpoint displayed on the screen.
    4. Call the PAR endpoint if using PAR.
    5. Redirect to the authorization_endpoint obtained from discovery.
    6. The conformance suite will return a 302 redirect straight away without the user taking any action – so there is no need for this to even be in a web browser.
    7. Exchange the authorization code for an access token at the token_endpoint obtained from discovery.
    8. Call the accounts_endpoint displayed on the screen using the access token.
    9. The client MAY call the consent endpoint (e.g consents/v1/consents/123456) to get consent information at any step.
      This is not needed and was added for compatibility with clients that automatically fetch consent details as part of their workflow.

    Also see https://gitlab.com/openid/conformance-suite/-/wikis/Brazil-RP-Testing-Instructions-and-Example-Configuration for additional information.

  16. When the test has completed, press “Continue Plan” to start the next test, or “Return to Plan” to view your progress.
  17. Once you have successfully completed testing, please follow the submission instructions to complete the certification process.
  18. 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.

Example Client

An example client can be found at https://gitlab.com/openid/sample-openbanking-client-nodejs. This is a nodejs application and requires nodejs and npm installed on your system.
You can use this client to see how your client implementation should interact with the conformance suite.

Before Running The Client

Before running this client you need to set the following environment variables:

  • CONFORMANCE_SERVER : Base path for the conformance suite. For example:
    export CONFORMANCE_SERVER=https://localhost:8443
  • ACCOUNT_REQUEST : account_requests_endpoint path displayed on test details page. Only needed when using a UK Openbanking variant. For example:export ACCOUNT_REQUEST=test/a/your-company-name/open-banking/v1.1/account-requests
  • ACCOUNTS : accounts_endpoint path displayed on test details page. For example:export ACCOUNTS=test-mtls/a/your-company-name/open-banking/v1.1/accounts
  • ISSUER : issuer value displayed on test details page. For example: export ISSUER=https://localhost:8443/test/a/your-company-name/
  • TEST_MODULE_NAME : Name of the test module, e.g fapi1-advanced-final-client-test.
  • FAPI_AUTH_REQUEST_METHOD : Client authentication type, mtls or private_key_jwt.
  • FAPI_RESPONSE_MODE : Response mode, plain_response or jarm.
  • FAPI_JARM_TYPE : plain_oauth or oidc.
  • FAPI_PROFILE : One of plain_fapi, openbanking_uk, consumerdataright_au, openbanking_brazil.
  • BRAZIL_CONSENT_REQUEST : Relative path for Brazil consents endpoint, e.g consents/v1/consents.

Running The Client

  1. Install dependencies using npm install
  2. Run npm run client (node entrypoint.js will work too)
  3. You should see output ending with COMPLETE: accounts endpoints response is...