Open Finance Brazil: How to run conformance tests for FAPI-CIBA RPs

This guide explains how to configure and run the Open Finance Brazil FAPI-CIBA tests for a Relying Party (RP), also called a client. The conformance suite acts as the OP and resource server and tests your RP. The steps below use Ping mode and Private Key JWT client authentication.

How the test works

Start a test in the suite, then use your RP to perform the flow against the endpoints that the test provides:

1. Read the server metadata and keys. Your RP reads the suite’s discovery document and JWKS and uses the advertised endpoints.
2. Create a consent. Your RP obtains an access token with the client_credentials grant, then calls the suite’s consent endpoint over mTLS. It keeps the returned consent ID.
3. Call the backchannel authentication endpoint. Your RP sends a signed CIBA request over mTLS. Use the consent ID as login_hint, include openid consents resources consent:<consentId> in the requested scope, and supply a client_notification_token. The suite returns an auth_req_id and an expiry period.
4. Simulate user approval. In the happy-path test, the suite authorizes the consent and simulates successful user authentication. You drive the flow from your RP; no approval in a real bank application is needed for this example.
5. Receive the ping. The suite calls your RP’s notification endpoint over mTLS. Your RP checks the notification token and auth_req_id and responds with HTTP 204 No Content. The ping indicates that the result is ready.
6. Obtain and validate the tokens. Your RP calls the suite’s token endpoint with the CIBA grant and auth_req_id. It decrypts the ID token, validates its signature and claims, and processes the token response.
7. Call the protected resource. Your RP uses the access token and its mTLS certificate to call the displayed resource endpoint. The suite checks the request and completes the test.

1. Select the test plan

1. Open the OpenID Foundation conformance suite and sign in with Google or GitLab.
2. On My Test Plans, select Create a new test.
3. Keep Guided selected, then choose OpenFinance Brazil, RP (Client), and CIBA client.
4. Check that the review screen shows the following plan and settings.

Setting	Value
Test plan	FAPI-CIBA-ID1: Relying Party (client test) fapi-ciba-id1-client-test-plan
Client Authentication Type	Private Key JWT
FAPI CIBA Profile	Open Finance Brazil
CIBA Mode	Ping

Select Configure this plan to open the configuration form.

2. Prepare the configuration

Use the Form tab to enter individual values, or the JSON tab to paste a complete configuration. The standard client test uses the Client configuration for the RP under test.

Example configuration: Open the preconfigured RP example plan (private link). Select View configuration to inspect the configuration used for the successful run. The link provides access to the shared example plan and its results; create your own plan to test your RP.

The values below are examples. Replace client details, keys, certificates, and the notification endpoint with values for your test environment.

Form section	Information to provide	Example values or guidance
Test information	A unique, URL-safe alias and a description. Keep publish set to No while checking the setup.	alias: documentation-alias-RP description: OFB-YOUR_OFB_IDENTIFIER_HERE_RP Choose your own alias to avoid clashes with other testers.
Server	Private keys in jwks format for the suite to use as the OP.	Include a private RSA signing key with alg: PS256. The suite signs ID tokens with this key and publishes the corresponding public key at its JWKS endpoint.
Client — identity	The client_id your RP will use when it calls the suite.	For example, ofb-ciba-client-1. Use the same client ID in your RP and in the test configuration.
Client — keys	The RP’s public signing and encryption keys in jwks format.	Provide a signing key for PS256 and an RSA encryption key with use: enc and alg: RSA-OAEP. Keep the corresponding private keys in your RP, which signs requests and decrypts ID tokens.
Client — certificate	The RP’s mTLS certificate.	Paste the public certificate in PEM format. Your RP must present this certificate when it calls the suite’s mTLS endpoints; its matching private key stays in the RP.
Client — ping endpoint	The RP’s backchannel_client_notification_endpoint. It must be reachable from the production suite over HTTPS with mTLS.	https://rp.example.org/ciba/notification Use your RP’s real notification endpoint. In the shared example, this points to the paired OP test because that test acts as the RP.
TLS certificates for client (used to make MTLS connections)	The certificate and private key that the suite uses when it sends pings to your RP.	Supply mtls.cert and mtls.key in PEM format, plus mtls.ca if a certificate chain is required. Configure your RP’s notification endpoint to accept this certificate.
Directory	The Directory keystore base for the environment used by the Brazil dynamic client registration test.	For the directory sandbox: https://keystore.sandbox.directory.openbankingbrasil.org.br/

Note: The two certificate fields have different roles. Client → certificate identifies your RP when it calls the suite. mtls.cert and mtls.key identify the suite when it calls your RP’s notification endpoint. Both directions use mTLS with Private Key JWT client authentication selected.

Note: The Brazil profile uses encrypted ID tokens. The RP must support RSA-OAEP with A256GCM and have the private key that matches the encryption key supplied in Client → jwks.

Note: Brazil CIBA maximum expiry sets the maximum authentication-request validity period, in seconds, for the product or service under test. If left empty, the suite uses a maximum of 86400 seconds. Your RP must process the expires_in returned by each test.

3. Create the plan and run the initial test

1. Select Validate Configuration and correct any configuration errors.
2. Select Create test plan. The plan page lists the tests that apply to your selected profile and settings.
3. Select Run Test for FAPI-CIBA-ID1: Client test (fapi-ciba-id1-client-test).
4. Open Exported values in the test log. Configure your RP with the displayed discoveryUrl, consents_endpoint, and resource_endpoint. Use the backchannel and token endpoints from mtls_endpoint_aliases in the discovery document.
5. Start a new consent and CIBA flow from your RP. The test waits for your RP to make the requests; opening the log alone does not start the protocol flow.
6. Check that your RP receives the ping, obtains and validates the tokens, and calls the resource endpoint. The completed happy-path test should show status FINISHED and result PASSED.

Example endpoints: With the alias documentation-alias-RP, the successful run used the following URLs. Use the values displayed by your own running test.

• Discovery: https://www.certification.openid.net/test/a/documentation-alias-RP/.well-known/openid-configuration
• Consent: https://mtls-www.certification.openid.net/test-mtls/a/documentation-alias-RP/open-banking/consents/v3/consents
• Resource: https://mtls-www.certification.openid.net/test-mtls/a/documentation-alias-RP/open-banking/resources/v3/resources

The suite’s endpoints are served by an active test instance. Start the required module before sending requests, and run one module at a time for a given alias.

4. Review the results and complete the plan

Open any warning or failure in the test log to see the condition, request or response details, and specification references. Correct configuration or implementation problems, then repeat the affected test with a new flow from your RP. A test marked FINISHED has stopped running; also check whether its result is PASSED, WARNING, or FAILED.

Continue through all applicable tests in the plan. Some tests deliberately return invalid responses or ID tokens, or send invalid pings. Follow each test’s instructions and let the suite verify that your RP handles the condition correctly. Some negative tests wait to confirm that your RP makes no further requests.

The plan also includes FAPI-CIBA-ID1: Open Finance Brazil client DCR happy path test. For that module, your RP must first register with the suite over mTLS using a valid Directory software statement and suitable client metadata, then complete the consent and CIBA flow. Use the client ID returned by registration. The ordinary happy-path example above uses the client details supplied in the test configuration.

The suite deliberately includes unsupported keys in its published JWKS so that it can test client key selection. Your RP must still find a suitable key and validate the ID token. Completing the example flow confirms the initial setup, but certification requires the complete applicable test plan and the OpenID Foundation certification submission process.