To make it easy to secure client applications, it is beneficial to realize the following points in a unified way.
* Setting policies on what configuration a client can have
* Validation of client configurations
* Conformance to a required security standards and profiles such as Financial-grade API (FAPI)
To realize these points in a unified way, _Client Policies_ concept is introduced.
==== Use-cases
Client Policies realize the following points mentioned as follows.
Setting policies on what configuration a client can have::
Configuration settings on the client can be enforced by client policies during client creation/update, but also during OpenID Connect requests to {project_name} server, which are related to particular client.
{project_name} supports similar thing also through the Client Registration Policies described in the link:{adapterguide_link}#_client_registration_policies[{adapterguide_name}].
However, Client Registration Policies can only cover OIDC Dynamic Client Registration. Client Policies cover not only what Client Registration Policies can do, but other client
registration and configuration ways. The current plans are for Client Registration to be replaced by Client Policies.
Validation of client configurations::
{project_name} supports validation whether the client follows settings like Proof Key for Code Exchange,
Request Object Signing Algorithm, Holder-of-Key Token, and so on on some endpoints like Authorization Endpoint, Token Endpoint, and so on.
These can be specified by each setting item (on Admin Console, switch, pulldown menu and so on). To make the client application secure, the administrator needs to set
many settings in the appropriate way, which makes it difficult for the administrator to secure the client application.
Client Policies can do these validation of client configurations mentioned just above and they can also be used to auto-configure some client configuration switches to meet
the advanced security requirements. In the future, individual client configuration settings may be replaced by Client Policies directly performing required validations.
Conformance to a required security standards and profiles such as FAPI::
The _Global client profiles_ are client profiles pre-configured in {project_name} by default. They are pre-configured to be compliant with standard security profiles like link:{adapterguide_link}#_fapi-support[FAPI],
which makes it easy for the administrator to secure their client application to be compliant with the particular security profile. At this moment, {project_name} has global
profiles for the support of FAPI 1 specification. The administrator will just need to configure the client policies to specify which clients should
be compliant with the FAPI. The administrator can configure client profiles and client policies, so that {project_name} clients can be easily made compliant with various other
security profiles like SPA, Native App, Open Banking and so on.
==== Protocol
The client policy concept is independent of any specific protocol. However, {project_name} currently supports it only just for the link:{adapterguide_link}#_oidc[OpenID Connect (OIDC) protocol].
==== Architecture
Client Policies consists of the four building blocks: Condition, Executor, Profile and Policy.
===== Condition
A condition determines to which client a policy is adopted and when it is adopted. Some conditions are checked at the time of client create/update when some other conditions are
checked during client requests (OIDC Authorization request, Token endpoint request and so on). The condition checks whether one specified criteria is satisfied. For example,
some condition checks whether the access type of the client is confidential.
The condition can not be used solely by itself. It can be used in a <<_client_policy_policy,policy>> that is described afterwards.
A condition can be configurable the same as other configurable providers. What can be configured depends on each condition's nature.
The following conditions are provided:
The way of creating/updating a client::
* Dynamic Client Registration (Anonymous or Authenticated with Initial access token or Registration access token)
* Admin REST API (Admin Console and so on)
So for example when creating a client, a condition can be configured to evaluate to true when this client is created by OIDC Dynamic Client Registration without initial
access token (Anonymous Dynamic Client Registration). So this condition can be used for example to ensure that all clients registered through OIDC Dynamic Client Registration
are FAPI compliant.
Author of a client (Checked by presence to the particular role or group)::
On OpenID Connect dynamic client registration, an author of a client is the end user who was authenticated to get an access token for generating a new client, not Service
Account of the existing client that actually accesses the registration endpoint with the access token. On registration by Admin REST API, an author of a client is the end user
like the administrator of the {project_name}.
Client Access Type (confidential, public, bearer-only)::
For example when a client sends an authorization request, a policy is adopted if this client is confidential.
Client Scope::
Evaluates to true if the client has a particular client scope (either as default or as an optional scope used in current request). This can be used for example to ensure that
OIDC authorization requests with scope `fapi-example-scope` need to be FAPI compliant.
Client Role::
Applies for clients with the client role of the specified name
Client Domain Name, Host or IP Address::
Applied for specific domain names of client. Or for the cases when the administrator registers/updates client from particular Host or IP Address.
Any Client::
This condition always evaluates to true. It can be used for example to ensure that all clients in the particular realm are FAPI compliant.
===== Executor
An executor specifies what action is executed on a client to which a policy is adopted. The executor executes one or several specified actions. For example,
some executor checks whether the value of the parameter `redirect_uri` in the authorization request matches exactly with one of the pre-registered redirect URIs on
Authorization Endpoint and rejects this request if not.
The executor can not be used solely by itself. It can be used in a <<_client_policy_profile,profile>> that is described afterwards.
An executor can be configurable the same as other configurable providers. What can be configured depends on the nature of each executor.
An executor acts on various events. An executor implementation can ignore certain types of events (For example, executor for checking OIDC `request` object acts just
on the OIDC authorization request). Events are:
* Creating a client (including creation through dynamic client registration)
* Updating a client
* Sending an authorization request
* Sending a token request
* Sending a token refresh request
* Sending a token revocation request
* Sending a token introspection request
* Sending a userinfo request
* Sending a logout request with a refresh token
On each event, an executor can work in multiple phases. For example, on creating/updating a client, the executor can modify the client configuration by auto-configure specific client
settings. After that, the executor validates this configuration in validation phase.
One of several purposes for this executor is to realize the security requirements of client conformance profiles like FAPI. To do so, the following executors are needed:
* Enforce secure <<_client-credentials,Client Authentication method>> is used for the client
* Enforce <<_mtls-client-certificate-bound-tokens,Holder-of-key tokens>> are used
* Enforce <<_proof-key-for-code-exchange,Proof Key for Code Exchange (PKCE)>> is used
* Enforce secure signature algorithm for <<_client-credentials,Signed JWT client authentication (private-key-jwt)>> is used
* Enforce HTTPS redirect URI and make sure that configured redirect URI does not contain wildcards
* Enforce OIDC `request` object satisfying high security level
* 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
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.
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]]
===== Policy
A policy consists of several conditions and profiles. The policy can be adopted to clients satisfying all conditions of this policy. The policy refers several profiles and all
executors of these profiles execute their task against the client that this policy is adopted to.
==== Configuration
Policies, profiles, conditions, executors can be configured by Admin REST API, which means also the Admin Console. To do so, there is a tab _Realm_ -> _Realm Settings_ -> _Client Policies_
, which means the administrator can have client policies per realm.
The _Global Client Profiles_ are automatically available in each realm. However there are no client policies
configured by default. This means that the administrator is always required to create any client policy if they want for example the clients of his realm to be FAPI compliant. Global
profiles cannot be updated, but the administrator can easily use them as a template and create their own profile if they want to do some slight changes in the global profile configurations.
There is JSON Editor available in the Admin Console, which simplifies the creation of new profile based on some global profile.
==== Backward Compatibility
Client Policies can replace Client Registration Policies described in the link:{adapterguide_link}#_client_registration_policies[{adapterguide_name}].
However, Client Registration Policies also still co-exist. This means that for example during a Dynamic Client Registration request to create/update a client, both client policies and
client registration policies are applied.
The current plans are for the Client Registration Policies feature to be removed and the existing client registration policies will be migrated into new client policies automatically.
