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 *Client registration service* from link:{securing_apps_link}[{securing_apps_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 some endpoints like Authorization Endpoint, Token Endpoint, and so on.
These can be specified by each setting item (on Admin Console, switch, pull-down menu and so on). To make the client application secure, the administrator needs to set
Client Policies can do these validation of client configurations mentioned just above and they can also be used to autoconfigure 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.
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 *FAPI* and *OAuth 2.1* in the link:{securing_apps_link}[securing apps] section,
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 and OAuth 2.1 specifications. The administrator will just need to configure the client policies to specify which clients should
be compliant with the FAPI and OAuth 2.1. The administrator can configure client profiles and client policies, so that {project_name} clients can be easily made compliant with various other
The client policy concept is independent of any specific protocol. {project_name} currently supports especially client profiles for the link:{securing_apps_link}[OpenID Connect (OIDC) protocol], but there is
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
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. Confidential client has enabled client authentication when public client has disabled client authentication. Bearer-only is a deprecated client type.
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.
Applies for clients with the client role of the specified name. Typically you can create a client role of specified name to requested clients and use it as a "marker role" to make
sure that specified client policy will be applied for requested clients.
NOTE: A use-case often exists for requiring the application of a particular client policy for the specified clients such as `my-client-1` and `my-client-2`. The best way to achieve this result
is to use a *Client Role* condition in your policy and then a create client role of specified name to requested clients. This client role can be used as a "marker role" used solely
for marking that particular client policy for particular clients.
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)
* Sending a logout request with a refresh token (note that logout with refresh token is proprietary {project_name} functionality unsupported by any specification. It is rather recommended to rely on the <<_oidc-logout,official OIDC logout>>).
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 autoconfigure specific client
One of several purposes for this executor is to realize the security requirements of client conformance profiles like FAPI and OAuth 2.1. 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
* Enforce checking if a client is the one to which an intent was issued in a use case where an intent is issued before starting an authorization code flow to get an access token like UK OpenBanking
A profile consists of several executors, which can realize a security profile like FAPI and OAuth 2.1. 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 1 Baseline, FAPI 1 Advanced, FAPI CIBA, FAPI 2 and OAuth 2.1 specifications.
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.
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.
Client Policies can replace Client Registration Policies described in the *Client registration service* from link:{securing_apps_link}[{securing_apps_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.
