keycloak-scim/securing_apps/topics/oidc/fapi-support.adoc

51 lines
4.6 KiB
Text
Raw Normal View History

[[_fapi-support]]
=== Financial-grade API (FAPI) Support
{project_name} makes it easier for administrators to make sure that their clients are compliant with these specifications:
* https://openid.net/specs/openid-financial-api-part-1-1_0.html[Financial-grade API Security Profile 1.0 - Part 1: Baseline]
* https://openid.net/specs/openid-financial-api-part-2-1_0.html[Financial-grade API Security Profile 1.0 - Part 2: Advanced]
* https://openid.net/specs/openid-financial-api-ciba-ID1.html[Financial-grade API: Client Initiated Backchannel Authentication Profile] (FAPI CIBA)
This compliance means that the {project_name} server will verify the requirements
for the authorization server, which are mentioned in the specifications. {project_name} adapters do not have any specific support for the FAPI, hence the required validations on the client (application)
side may need to be still done manually or through some other third-party solutions.
==== FAPI client profiles
To make sure that your clients are FAPI compliant, you can configure Client Policies in your realm as described in the link:{adminguide_link}#_client_policies[{adminguide_name}]
and link them to the global client profiles for FAPI support, which are automatically available in each realm. You can use either `fapi-1-baseline` or `fapi-1-advanced` profile based on which FAPI
profile you need your clients to conform with.
In case you want to use link:{adminguide_link}#_oidc_clients[Pushed Authorization Request (PAR)], it is recommended that your client use
both the `fapi-1-baseline` profile and `fapi-1-advanced` for PAR requests. Specifically, the `fapi-1-baseline` profile contains `pkce-enforcer` executor, which makes sure
that client use PKCE with secured S256 algorithm. This is not required for FAPI Advanced clients unless they use PAR requests.
In case you want to use <<_backchannel_authentication_endpoint,CIBA>> in a FAPI compliant way, make sure that your clients use both `fapi-1-advanced` and `fapi-ciba` client profiles.
There is a need to use the `fapi-1-advanced` profile, or other client profile containing the requested executors, as the `fapi-ciba` profile contains just CIBA-specific executors.
When enforcing the requirements of the FAPI CIBA specification, there is a need for more requirements, such as enforcement of confidential clients or certificate-bound access tokens.
==== Open Banking Brasil Financial-grade API Security Profile
{project_name} is compliant with the https://openbanking-brasil.github.io/specs-seguranca/open-banking-brasil-dynamic-client-registration-1_ID2-ptbr.html[Open Banking Brasil Financial-grade API Security Profile 1.0 Implementers Draft 2].
This one is more strict in some requirements than the <<_fapi-support,FAPI 1 Advanced>> specification and hence it may be needed to configure link:{adminguide_link}#_client_policies[Client Policies]
in the more strict way to enforce some of the requirements. Especially:
* If your client does not use PAR, make sure that it uses encrypted OIDC request objects. This can be achieved by using a client profile with the `secure-request-object` executor configured with `Encryption Required` enabled.
* Make sure that for JWS, the client uses the `PS256` algorithm. For JWE, the client should use the `RSA-OAEP` with `A256GCM`. This may need to be set in all the link:{adminguide_link}#_oidc_clients[Client Settings] where these algorithms are applicable.
==== TLS considerations
As confidential information is being exchanged, all interactions shall be encrypted with TLS (HTTPS). Moreover, there are some requirements in the FAPI specification for
the cipher suites and TLS protocol versions used. To match these requirements, you can consider configure allowed ciphers. This configuration can be done in the
`KEYCLOAK_HOME/standalone/configuration/standalone-*.xml` file in the Elytron subsystem. For example this element can be added under `tls` -> `server-ssl-contexts`
[source,xml]
<server-ssl-context name="kcSSLContext" want-client-auth="true" protocols="TLSv1.2" \
key-manager="kcKeyManager" trust-manager="kcTrustManager" \
cipher-suite-filter="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384" protocols="TLSv1.2" />
The references to `kcKeyManager` and `kcTrustManager` refers to the corresponding Keystore and Truststore. See the documentation of Wildfly Elytron subsystem for more details and also
other parts of {project_name} documentation such as link:{installguide_link}#_network[Network Setup Section] or link:{adminguide_link}#_x509[X.509 Authentication Section].