Configure FAPI Compliance
To help you configure your Auth0 tenant for Financial-Grade API (FAPI) compliance, the application model includes a compliance_level
property. This setting allows you to enforce a specific FAPI profile, ensuring all authorization requests and configurations meet the required security standards.
The compliance_level
property accepts one of the following values:
null
or undefined: No compliance level is required. This is the default.fapi1_adv_mtls_par
: Enforces the FAPI1 Advanced profile, requiring mTLS and PAR.fapi1_adv_pkj_par
: Enforces the FAPI1 Advanced profile, requiring Private Key JWT and PAR.fapi2_sp_pkj_mtls
: Enforces the FAPI2.0 Security Profile, requiring Private Key JWT Client Authentication and mTLS Sender Constraining.fapi2_sp_mtls_mtls
: Enforces the FAPI2.0 Security Profile, requiring mTLS Client Authentication and mTLS Sender Constraining.
Impact of compliance levels
When you set a compliance level, all authorization requests must be compliant with the selected standard, regardless of other settings. For example, if you set the compliance level to fapi1_adv_pkj_par
or fapi1_adv_mtls_par
, PAR is automatically required regardless of the require_pushed_authorization_requests
setting.
An authorization request that does not use PAR will fail with an invalid_request
error:
{
“error”: “invalid_request”,
“error_description”: “Pushed Authorization Requests are required by the configured compliance level”
}
Was this helpful?
In some cases, setting a compliance level also changes Auth0’s behavior. For example, both the fapi1_adv_pkj_par
and fapi1_adv_mtls_par
compliance levels cause Auth0 to include a s_hash
claim in the returned ID token. This claim contains a SHA256 hash of the state value, allowing the ID token to act as a detached signature.
The following tables summarize the validation rules and behavioral changes that each compliance level enables:
Validation
Validation | fapi1_adv_pkj_par |
fapi1_adv_mtls_par |
fapi2_sp_pkj_mtls |
fapi2_sp_mtls_mtls |
---|---|---|---|---|
Prevents the use of access tokens in the URL query when calling /userinfo . Access tokens must be placed in the Authorization header instead. |
Y | Y | Y | Y |
Requires PAR. | Y | Y | Y | Y |
Requires PKCE with the S256 challenge method. | Y | Y | Y | Y |
Prevents the use of wildcards in the allowed callbacks on a client. | Y | Y | N | N |
Enforces the use of JAR. | Y | Y | N | N |
Ensures the JAR payload is signed using the PS256 algorithm. | Y | Y | N | N |
Ensures the JAR payload contains the nbf claim and it is no longer than 60 minutes in the past. | Y | Y | N | N |
Ensures the JAR payload contains the exp claim and that it is no more than 60 minutes after the nbf claim. | Y | Y | N | N |
Ensures the client has set the oidc_conformant property to true. |
Y | Y | Y | Y |
Requires usage of x-fapi-* headers | Y | Y | N | N |
Ensures the response_type on the request is code id_token . |
Y | Y | ||
Requires the use of Private Key JWT for client authentication. | Y | N | Y | N |
Requires the use of mTLS for client authentication. | N | Y | N | Y |
Allowed response types | code id_token |
code id_token |
code | code |
Requires aud claim to strictly match issuer in Private Key JWT assertion |
N | N/A | Y | N/A |
Requires redirect_uri parameter in pushed authorization requests (PAR) |
N | N | Y | Y |
Behavioral changes
Auth0 behavioral changes | fapi1_adv_pkj_par |
fapi1_adv_mtls_par |
fapi2_sp_pkj_mtls |
fapi2_sp_mtls_mtls |
---|---|---|---|---|
Adds s_hash claim to ID tokens. | Y | Y | N | N |
When the profile scope is requested, the update_at claim contains an OIDC Conformant unix timestamp rather than a string. |
Y | Y | Y | Y |
Returns only OIDC conformant error codes. In some cases, Auth0 may return additional error codes, but enabling this compliance level ensures that Auth0 only uses error codes defined in the OpenID standards. | Y | Y | Y | Y |
Returns issuer as iss parameter in code responses |
N | N | Y | Y |
Reduces maximum lifetime of authorization codes to 60 seconds | N | N | Y | Y |
Configure FAPI compliance for a client
To perform this using the Auth0 Dashboard:
Navigate to Auth0 Dashboard > Applications.
Select the application.
Select the Application Settings tab.
Open the Advanced Settings section.
In the OAuth tab, select the FAPI Compliance Enforcement Level.
The options to configure FAPI compliance are:
None: No compliance level is required. This is the default.
FAPI 1 Advanced profile using Private Key JWT and PAR: The customer would like this client to behave in accordance with the FAPI1 Advanced profile using Private Key JWT and PAR.
FAPI 1 Advanced profile using mTLS and PAR: The customer would like this client to behave in accordance with the FAPI1 Advanced profile using mTLS and PAR.
Use the Management API to set the compliance_level
property with a POST or PATCH request:
curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
--header 'Authorization: Bearer $management_access_token' \
--header 'Content-Type: application/json' \
--data '{
"compliance_level": "fapi1_adv_mtls_par"
}'
Was this helpful?
To return the compliance_level
property, use a GET request:
curl --location 'https://$tenant/api/v2/clients/$client_id \
--header 'Authorization: Bearer $management_access_token'
Was this helpful?
For FAPI 2.0 compliance, you can configure the expiry for Pushed Authorization Requests (PAR) using the Management API. The expiry can be set to a value less than 600 seconds, with a default of 30 seconds.