libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

KEYCLOAK-18883 KEYCLOAK-18864 FAPI CIBA and OpenBanking Brasil updates

Browse source
This commit is contained in:
mposolda 2021-07-29 13:52:21 +02:00 committed by Marek Posolda
parent 84e5203174
commit 34fcfb80a8
9 changed files with 56 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
release_notes/index.adoc
View file

@ -13,6 +13,9 @@ include::topics/templates/document-attributes-community.adoc[]
:release_header_latest_link: {releasenotes_link_latest}
include::topics/templates/release-header.adoc[]
== {project_name_full} 15.0.0
include::topics/15_0_0.adoc[leveloffset=2]
== {project_name_full} 14.0.0
include::topics/14_0_0.adoc[leveloffset=2]

2
release_notes/topics/14_0_0.adoc
View file

@ -4,7 +4,7 @@
The {project_name} server has now official support for client policies and Financial-grade API (FAPI). This capability was previewed in earlier versions, but now
it is more polished and properly documented. Thanks to https://github.com/tnorimat[Takashi Norimatsu], who did most of the work on this. Also thanks
to https://github.com/andriimurashkin[Andrii Murashkin] and https://github.com/HryhoriiHevorkian[Hryhorii Hevorkian], who did a great deal of the work on this feature as well.
to https://github.com/DmitryMishchuk[Dmytro Mishchuk], https://github.com/andriimurashkin[Andrii Murashkin] and https://github.com/HryhoriiHevorkian[Hryhorii Hevorkian], who did a great deal of the work on this feature as well.
Finally thanks to all the members of the https://github.com/keycloak/kc-sig-fapi/blob/master/members.adoc[FAPI Special interest group] for their help and feedback.
== Improvements to User Profile SPI and support for declarative configuration

9
release_notes/topics/15_0_0.adoc Normal file
View file

@ -0,0 +1,9 @@
= Highlights
== Financial-grade API (FAPI) Improvements, FAPI CIBA and Open Banking Brasil
The {project_name} server has improved support for the Financial-grade API (FAPI). More specifically, {project_name} is now compliant with FAPI CIBA and with OpenBanking Brasil.
We also have support for CIBA ping mode. Thanks to https://github.com/tnorimat[Takashi Norimatsu], who did most of the work on FAPI CIBA and who is
continually doing a really awesome job for the {project_name} project. Also thanks to https://github.com/DmitryMishchuk[Dmytro Mishchuk],
https://github.com/andriimurashkin[Andrii Murashkin], https://github.com/HryhoriiHevorkian[Hryhorii Hevorkian] and https://github.com/lbortoli[Leonardo Bortoli], who did a great deal of
the work on the FAPI compliance as well. Finally thanks to all the members of the https://github.com/keycloak/kc-sig-fapi/blob/master/members.adoc[FAPI Special interest group] for their help and feedback.

27
securing_apps/topics/oidc/fapi-support.adoc
View file

@ -1,9 +1,13 @@
[[_fapi-support]]
=== Financial-grade API (FAPI) Support
{project_name} makes it easier for administrators to make sure that their clients are compliant with
the https://openid.net/specs/openid-financial-api-part-1-1_0.html[Financial-grade API Security Profile 1.0 - Part 1: Baseline]
and https://openid.net/specs/openid-financial-api-part-2-1_0.html[Financial-grade API Security Profile 1.0 - Part 2: Advanced]. This compliance means that the {project_name} server will verify the requirements
{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.
@ -13,6 +17,23 @@ To make sure that your clients are FAPI compliant, you can configure Client Poli
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-financial-api-1_ID1.html[Open Banking Brasil Financial-grade API Security Profile 1.0 Implementers Draft 1].
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

6
securing_apps/topics/oidc/oidc-generic.adoc
View file

@ -219,11 +219,15 @@ Client Initiated Backchannel Authentication Grant is used by clients who want to
The client requests {project_name} an auth_req_id that identifies the authentication request made by the client. {project_name} creates the auth_req_id.
After receiving this auth_req_id, this client repeatedly needs to poll {project_name} to obtain an Access Token, Refresh Token and ID Token from {project_name} in return for the auth_req_id until the user is authenticated.
After receiving this auth_req_id, this client repeatedly needs to poll {project_name} to obtain an Access Token, Refresh Token and ID Token from {project_name} in return for the auth_req_id until the user is authenticated.
In case that client uses `ping` mode, it does not need to repeatedly poll the token endpoint, but it can wait for the notification sent by {project_name} to the specified Client Notification Endpoint.
The Client Notification Endpoint can be configured in the {project_name} Admin Console. The details of the contract for Client Notification Endpoint are described in the CIBA specification.
For more details refer to https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html[OpenID Connect Client Initiated Backchannel Authentication Flow specification].
Also please refer to other places of {project_name} documentation like <<_backchannel_authentication_endpoint,Backchannel Authentication Endpoint of this guide>> and link:{adminguide_link}#_client_initiated_backchannel_authentication_grant[Client Initiated Backchannel Authentication Grant section] of {adminguide_name}.
For the details about FAPI CIBA compliance, please refer to the <<_fapi-support,FAPI section of this guide>>.
==== Redirect URIs

5
server_admin/topics/clients/client-oidc.adoc
View file

@ -1,4 +1,5 @@
[[_oidc_clients]]
=== OIDC Clients
<<_oidc,OpenID Connect>> is the preferred protocol to secure applications. It was designed from the ground up to be web friendly
@ -226,10 +227,6 @@ Basic features of https://datatracker.ietf.org/doc/html/draft-ietf-oauth-par[OAu
For more details about PAR, see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-par[PAR Specification].
:tech_feature_name: OAuth 2.0 Pushed Authorization Requests
:tech_feature_setting: -Dkeycloak.profile.feature.par=enabled
include::../templates/techpreview.adoc[]
There are two configuration parameters. The former can be set up on Advanced Settings per client for activating and deactivating PAR.
|===

3
server_admin/topics/clients/client-policies.adoc
View file

@ -120,12 +120,13 @@ One of several purposes for this executor is to realize the security requirement
* Enforce Response Type of OIDC Hybrid Flow including ID Token used as _detached signature_ as described in the FAPI 1 specification, which means that ID Token returned from Authorization response won't contain user profile data
* Enforce more secure `state` and `nonce` parameters treatment for preventing CSRF
* Enforce more secure signature algorithm when client registration
* Enforce `binding_message` parameter is used for CIBA requests
[[_client_policy_profile]]
===== Profile
A profile consists of several executors, which can realize a security profile like FAPI. Profile can be configured by the Admin REST API (Admin Console) together with its executors.
Two _global profiles_ exist and they are configured in {project_name} by default with pre-configured executors compliant with the FAPI Baseline and FAPI Advanced specifications.
Three _global profiles_ exist and they are configured in {project_name} by default with pre-configured executors compliant with the FAPI Baseline, FAPI Advanced and FAPI CIBA specifications.
More details exist in the FAPI section of the link:{adapterguide_link}#_fapi-support[{adapterguide_name}].
[[_client_policy_policy]]

9
server_admin/topics/sso-protocols/oidc.adoc
View file

@ -100,10 +100,6 @@ This is used by clients running on internet-connected devices that have limited
[[_client_initiated_backchannel_authentication_grant]]
===== Client Initiated Backchannel Authentication Grant
:tech_feature_name: Client Initiated Backchannel Authentication Grant
:tech_feature_setting: -Dkeycloak.profile.feature.ciba=enabled
include::../templates/techpreview.adoc[]
This is used by clients who want to initiate the authentication flow by communicating with the OpenID Provider directly without redirect through the user's browser like OAuth 2.0's authorization code grant. Here's a brief summary of the protocol:
. The client requests {project_name} an auth_req_id that identifies the authentication request made by the client. {project_name} creates the auth_req_id.
@ -126,7 +122,8 @@ The configurable items and their description follow.
|Configuration|Description
|Backchannel Token Delivery Mode
|Specifying how the CD (Consumption Device) gets the authentication result and related tokens. There are three modes, "poll", "ping" and "push". {project_name} only supports "poll". The default setting is "poll". This configuration is required.
|Specifying how the CD (Consumption Device) gets the authentication result and related tokens. There are three modes, "poll", "ping" and "push". {project_name} only supports "poll" and "ping" modes.
The default setting is "poll". This configuration is used as the default mode for clients, however every client can override the mode.
For more details, see https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#rfc.section.5[CIBA Specification].
|Expires In
@ -241,6 +238,8 @@ This field is optional and was defined by CIBA standard document.
|===
Besides the mentioned parameters, any custom parameter that is sent to the Backchannel Authentication Endpoint, will be forwarded to Channel Provider as well.
Authentication Delegation Response:: The response is returned from the authentication entity to {project_name} to notify that the authentication entity received the authentication request from {project_name}.
* Responses

9
server_installation/topics/profiles.adoc
View file

@ -31,14 +31,19 @@ The features that can be enabled and disabled are:
|ciba
|OpenID Connect Client Initiated Backchannel Authentication (CIBA)
|No
|Preview
|Yes
|Supported
|client_policies
|Add client configuration policies
|Yes
|Supported
|par
|OAuth 2.0 Pushed Authorization Requests (PAR)
|Yes
|Supported
|declarative_user_profile
|Configure user profiles using a declarative style
|No