Configure Auth0 to pass OpenID FAPI Certification Tests

To help you configure your Auth0 client to adhere to a Financial-Grade API (FAPI) profile and pass the OpenID FAPI Conformance Tests, follow these steps:

Step 1: Set the compliance level

To enforce a specific FAPI profile, set the compliance_level property on your client to the desired value. This ensures all authorization requests and configurations are compliant with the selected standard.

  • fapi1_adv_pkj_par

  • fapi1_adv_mtls_par

  • fapi2_sp_pkj_mtls

  • fapi2_sp_mtls_mtls

If compliance_level is null or undefined, no compliance level is required. This is the default. To learn more, read Configure FAPI compliance.

Step 2: Configure core FAPI requirements

To pass the OpenID FAPI Conformance Tests, ensure your client is configured for the following requirements.

  • Configure Pushed Authorization Requests (PAR): All the FAPI profiles require the use of PAR.

  • Configure mTLS or Private Key JWT: Depending on the selected profile, you must configure either mTLS (including aliases) or Private Key JWT.

  • Configure mTLS Token Binding: You must also set up mTLS token binding for the client.

  • Enable oidc_conformant: Ensure the oidc_conformant property is set to true on your client. This is the default for clients created in Auth0 Dashboard.

You must ensure that Auth0 prompts users for consent. To do this, set the is_first_party property on the client to false.

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "is_first_party": false  
}'

Was this helpful?

/

Step 4: Promote connection to domain level

Promote your connection to the domain level to ensure it functions correctly with the FAPI profile.

curl --location --request PATCH 'https://$tenant/api/v2/connections/$connection_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "is_domain_connection": true
}'

Was this helpful?

/

Step 5: Configure supported ACR claims (FAPI 1.0 Only)

The FAPI tests use a required ACR value of urn:mace:incommon:iap:silver. To include the ACR value in the ID token, add it to the list of supported ACR values for the tenant:

curl --location --request PATCH 'https://$tenant/api/v2/tenants/settings' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "acr_values_supported": ["urn:mace:incommon:iap:silver"]
}'

Was this helpful?

/

Step 6: Remove alg property from JWKS endpoint

To allow your keys to be used with multiple algorithms, remove the alg property from the output of the /.well-known/jwks.json endpoint:

curl --location --request PATCH 'https://$tenant/api/v2/tenants/settings' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "flags": {
        "remove_alg_from_jwks": true
    }
}'

Was this helpful?

/

Step 7: Add an Action to enforce scope and redirect URI (FAPI 1.0 Only)

By default, Auth0 allows requests without a scope. If no scope is present, Auth0 assumes the openid scope. Auth0 also allows requests without a redirect_uri, which you can set in Actions.

The FAPI conformance tests require these to be more restrictive. Add an Action to enforce the necessary restrictions on scope and redirect_uri:

exports.onExecutePostLogin = async (event, api) => {
  if (!event.request.body || !event.request.body.refresh_token) {
    // Require a scope
    if (!event.request.query.scope) {
      api.access.deny('scope must be provided in the request');
    }
    // To improve the error message if redirect_uri is not present
    if (!event.request.query.redirect_uri) {
      api.access.deny('redirect_uri must be provided in the request');
    }
  }
};

Was this helpful?

/

Step 8: Return iss claim in code response (FAPI 2.0 Only)

The FAPI 2.0 Security Profile requires that the iss parameter is returned in authorization responses, as defined in RFC 9207. For compatibility reasons, Auth0 does not require the iss parameter by default. To enable this behavior, set the authorization_response_iss_parameter_supported property in your tenant settings to true.

curl --location --request PATCH 
--url 'https://$tenant/api/v2/tenants/settings' \ 
--header 'Authorization: Bearer $management_access_token' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ "authorization_response_iss_parameter_supported": true }'

Was this helpful?

/

Learn more