KEYCLOAK-7075 Client scopes documentation (#389)

securing_apps/topics/client-registration.adoc

@@ -190,15 +190,15 @@ Request sent from some untrusted IP will be rejected. URLs of newly registered c
 to set `Redirect URI` of client pointing to some untrusted host. By default, there is not any whitelisted host, so anonymous client registration is de-facto disabled.
 
 * Consent Required Policy - Newly registered clients will have `Consent Allowed` switch enabled. So after successful authentication, user will always
-see consent screen when he needs to approve personal info and permissions (protocol mappers and roles). It means that client won't have access to any personal
+see consent screen when he needs to approve permissions (client scopes). It means that client won't have access to any personal
 info or permission of user unless user approves it.
 
 * Protocol Mappers Policy - Allows to configure list of whitelisted protocol mapper implementations. New client can't be registered
 or updated if it contains some non-whitelisted protocol mapper. Note that this policy is used for authenticated requests as well, so
 even for authenticated request there are some limitations which protocol mappers can be used.
 
-* Client Template Policy - Allow to whitelist `Client Templates`, which can be used with newly registered or updated clients.
+* Client Scope Policy - Allow to whitelist `Client Scopes`, which can be used with newly registered or updated clients.
-There are no whitelisted templates by default.
+There are no whitelisted scopes by default; only the client scopes, which are defined as `Realm Default Client Scopes` are whitelisted by default.
 
 * Full Scope Policy - Newly registered clients will have `Full Scope Allowed` switch disabled. This means they won't have any scoped
 realm roles or client roles of other clients.

securing_apps/topics/oidc/java/params_forwarding.adoc

@@ -1,4 +1,4 @@
-
+[[_params_forwarding]]
 ==== Parameters Forwarding
 
 The {project_name}  initial authorization endpoint request has support for various parameters. Most of the parameters are described in
@@ -17,7 +17,9 @@ and the parameter `scope=offline_access` will be automatically forwarded to the
 
 The supported parameters are:
 
-* scope
+* scope - Use a space-delimited list of scopes. A space-delimited list typically references link:{adminguide_link}#_client_scopes[Client scopes]
+defined on particular client. Note that the scope `openid` will be always be added to the list of scopes by the adapter. For example, if you
+enter the scope options `address phone`, then the request to {project_name} will contain the scope parameter `scope=openid address phone`.
 
 * prompt - {project_name} supports these settings:
 ** `login` - SSO will be ignored and the {project_name} login page will be always shown, even if the user is already authenticated
@@ -25,11 +27,13 @@ The supported parameters are:
 is not yet authenticated. This setting allows you to create a filter/interceptor on the application side and show a custom error page
 to the user. See more details in the specification.
 
-* max_age
+* max_age - Used only if a user is already authenticated. Specifies maximum permitted time for the authentication to persist, measured
+from when the user authenticated. If user is authenticated longer than `maxAge`, the SSO is ignored and he must re-authenticate.
 
-* login_hint
+* login_hint - Used to pre-fill the username/email field on the login form.
 
-* kc_idp_hint
+* kc_idp_hint - Used to tell {project_name} to skip showing login page and automatically redirect to specified identity provider instead.
+More info in the link:{adminguide_link}#_client_suggested_idp[Identity Provider documentation].
 
 Most of the parameters are described in the http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[OIDC specification].
 The only exception is parameter `kc_idp_hint`, which is specific to {project_name} and contains the name of the identity provider to automatically use.

securing_apps/topics/oidc/javascript-adapter.adoc

@@ -268,6 +268,12 @@ Options is an Object, where:
 * prompt - By default the login screen is displayed if the user is not logged-in to {project_name}. To only authenticate to the application if the user is already logged-in and not display the login page if the user is not logged-in, set this option to `none`. To always require re-authentication and ignore SSO, set this option to `login` .
 * maxAge - Used just if user is already authenticated. Specifies maximum time since the authentication of user happened. If user is already authenticated for longer time than `maxAge`, the SSO is ignored and he will need to re-authenticate again.
 * loginHint - Used to pre-fill the username/email field on the login form.
+* scope - Used to forward the scope parameter to the {project_name} login endpoint. Use a space-delimited list of scopes. Those typically
+reference link:{adminguide_link}#_client_scopes[Client scopes] defined on particular client. Note that the scope `openid` will be
+always be added to the list of scopes by the adapter. For example, if you enter the scope options `address phone`, then the request
+to {project_name} will contain the scope parameter `scope=openid address phone`.
+* idpHint - Used to tell {project_name} to skip showing the login page and automatically redirect to the specified identity
+provider instead. More info in the link:{adminguide_link}#_client_suggested_idp[Identity Provider documentation].
 * action - If value is 'register' then user is redirected to registration page, otherwise to login page.
 * locale - Sets the 'ui_locales' query param in compliance with section 3.1.2.1 of the OIDC 1.0 specification.
 * kcLocale - Specifies the desired Keycloak locale for the UI.  This differs from the locale param in that it tells the Keycloak server to set a cookie and update the user's profile to a new preferred locale.

server_admin/topics.adoc

@@ -44,14 +44,14 @@ include::topics/clients/saml/entity-descriptors.adoc[]
 include::topics/clients/client-link.adoc[]
 include::topics/clients/protocol-mappers.adoc[]
 include::topics/clients/installation.adoc[]
-include::topics/clients/client-templates.adoc[]
+include::topics/clients/client-scopes.adoc[]
 include::topics/roles.adoc[]
 include::topics/roles/realm-roles.adoc[]
 include::topics/roles/client-roles.adoc[]
 include::topics/roles/composite.adoc[]
 include::topics/roles/user-role-mappings.adoc[]
 include::topics/roles/user-role-mappings/default-roles.adoc[]
-include::topics/roles/client-scope.adoc[]
+include::topics/roles/role-scope-mappings.adoc[]
 include::topics/groups.adoc[]
 include::topics/groups/groups-vs-roles.adoc[]
 include::topics/groups/default-groups.adoc[]

server_admin/topics/clients/client-oidc.adoc

@@ -18,8 +18,6 @@ image:{project_images}/add-client-oidc.png[]
 Enter in the `Client ID` of the client.  This should be a simple
 alpha-numeric string that will be used in requests and in the {project_name} database to identify the client.
 Next select `openid-connect` in the `Client Protocol` drop down box.
-Ignore the `Client Template` listbox for now,
-we'll go over that later in this chapter.
 Finally enter in the base URL of your
 application in the `Root URL` field and click `Save`.  This will create the client and bring you to the client `Settings`
 tab.

server_admin/topics/clients/client-saml.adoc

@@ -18,8 +18,6 @@ image:{project_images}/add-client-saml.png[]
 
 Enter in the `Client ID` of the client.  This is often a URL and will be the expected `issuer` value in SAML requests sent
 by the application.  Next select `saml` in the `Client Protocol` drop down box.
-Ignore the `Client Template` listbox for now,
-we'll go over that later in this chapter.
 Finally enter in the `Client SAML Endpoint` URL.  Enter the
 URL you want the {project_name} server to send SAML requests and responses to.  Usually applications have only one URL for processing SAML requests.
 If your application has different URLs for its bindings, don't worry, you can fix this in the `Settings` tab of the client.

server_admin/topics/clients/client-scopes.adoc

@@ -0,0 +1,164 @@
+[[_client_scopes]]
+=== Client Scopes
+
+If you have many applications you need to secure and register within your organization, it can become tedious to configure the
+<<_protocol-mappers, protocol mappers>> and <<_role_scope_mappings, role scope mappings>> for each of these clients. {project_name} allows
+you to define a shared client configuration in an entity called a _client scope_.
+
+Client scopes also provide support for the OAuth 2 `scope` parameter, which allows a client application to request more or fewer
+claims or roles in the access token, according to the application needs.
+
+To create a client scope, follow these steps:
+
+* Go to the `Client Scopes` left menu item. This initial screen shows you a list of currently defined client scopes.
+
+.Client Scopes List
+image:{project_images}/client-scopes-list.png[]
+
+* Click the `Create` button. Name the client scope and save. A _client scope_ will have similar tabs to a regular clients. You can
+define <<_protocol-mappers, protocol mappers>> and <<_role_scope_mappings, role scope mappings>>, which can be inherited by other clients,
+and which are configured to inherit from this client scope.
+
+==== Protocol
+
+When you are creating the client scope, you must choose the `Protocol`. Only the clients which use same protocol can then be linked
+with this client scope.
+
+Once you have created new realm, you can see that there is a list of pre-defined (builtin) client scopes in the menu.
+
+* For the SAML protocol, there is one builtin client scope, `roles_list`, which contains one protocol mapper for showing the roles
+list in the SAML assertion.
+* For the OpenID Connect protocol, there are client scopes `profile`, `email`, `address`, `phone` and `offline_access` .
+
+The client scope, `offline_access`, is useful when client wants to obtain offline tokens. Learn about offline tokens in the
+<<_offline-access, Offline Access section>> or in the http://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification],
+where scope parameter is defined with the value `offline_access`.
+
+The client scopes `profile`, `email`, `address` and `phone` are also defined in the http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[OpenID Connect specification].
+These client scopes do not have any role scope mappings defined, but they have some protocol mappers defined, and these mappers correspond
+to the claims defined in the OpenID Connect specification.
+
+For example, when you click to open the `phone` client scope and open the `Mappers` tab, you will see the protocol mappers, which
+correspond to the claims defined in the specification for the scope `phone`.
+
+.Client Scope Mappers
+image:{project_images}/client-scopes-phone.png[]
+
+When the `phone` client scope is linked to a client, that client automatically inherits all the protocol mappers defined in the
+`phone` client scope. Access tokens issued for this client will contain the phone number information about the user, assuming that
+the user has a defined phone number.
+
+Builtin client scopes contain exactly the protocol mappers as defined per the specification,
+however you are free to edit client scopes and create/update/remove any protocol mappers (or role scope mappings).
+
+==== Consent related settings
+
+Client scope contains options related to the consent screen. Those options are useful only if the linked client is configured to
+require consent (if the `Consent Required` switch is enabled on the client).
+
+Display On Consent Screen::
+  If on, and if this client scope is added to a client with consent required, then the text specified by `Consent Screen Text` will
+  be displayed on the consent screen, which is shown once the user is authenticated and right before he is redirected from {project_name}
+  to the client. If the switch is off, then this client scope will not be displayed on the consent screen.
+
+Consent Screen Text::
+  The text shown on the consent screen when this client scope is added to some client with consent required defaults to
+  the name of client scope. The value for this text is localizable by specifying a substitution variable
+  with `${var-name}` strings. The localized value is then configured within property files in your theme. See the
+  link:{developerguide_link}[{developerguide_name}] for more information on localization.
+
+[[_client_scopes_linking]]
+==== Link Client Scope with the Client
+
+Linking between client scope and client is configured in the `Client Scopes` tab of the particular client. There are 2 ways of
+linking between client scope and client.
+
+Default Client Scopes::
+  This is applicable for both OpenID Connect and SAML clients. Default client scopes are always applied when issuing OpenID Connect tokens
+  or SAML assertions for this client. The client will inherit Protocol mappers and Role Scope Mappings defined on the client
+  scope. For the OpenID Connect Protocol, the Mappers and Role Scope Mappings are always applied, regardless of value of used for the scope
+  parameter in the OpenID Connect authorization request.
+
+Optional Client Scopes::
+  This is applicable only for OpenID Connect clients. Optional client scopes are applied when issuing tokens for this client,
+  but only when they are requested by the `scope` parameter in the OpenID Connect authorization request.
+
+===== Example
+
+For this example, we assume that the client has `profile` and `email` linked as default client scopes, and `phone` and `address`
+are linked as optional client scopes. The client will use the value of the scope parameter when sending a request to the OpenID Connect authorization
+endpoint:
+
+```
+scope=openid phone
+```
+
+The scope parameter contains the string, with the scope values divided by space (which is also the reason why a client scope name
+cannot contain a space character in it). The value `openid` is the meta-value used for all OpenID Connect requests, so we will ignore
+it for this example. The token will contain mappers and role scope mappings from the client scopes `profile`, `email` (which are
+default scopes) and `phone` (an optional client scope requested by the scope parameter).
+
+==== Evaluating Client Scopes
+
+The tabs `Mappers` and `Scope` of the client contain the protocol mappers and role scope mappings declared solely for this client.
+They do not contain the mappers and scope mappings inherited from client scopes. However, it may be useful to see what the
+effective protocol mappers will be (protocol mappers defined on the client itself as well as inherited from the linked client scopes)
+and the effective role scope mappings used when you generate the token for the particular client.
+
+You can see all of these when you click the `Client Scopes` tab for the client and then open the sub-tab `Evaluate`. From here you
+can select the optional client scopes that you want to apply. This will also show you the value of the `scope` parameter, which needs to
+be sent from the application to the {project_name} OpenID Connect authorization endpoint.
+
+.Evaluating Client Scopes
+image:{project_images}/client-scopes-evaluate.png[]
+
+NOTE: If you want to see how you can send a custom value for a `scope` parameter from your application, see the
+link:{adapterguide_link}#_params_forwarding[parameters forwarding section], if your application uses the servlet adapter, or the
+link:{adapterguide_link}#_javascript_adapter[javascript adapter section], if your application uses the javascript adapter.
+
+===== Generating Example Tokens
+
+To see an example of a real access token, generated for the particular user and issued for the particular client, with the specified
+value of `scope` parameter, select the user from the `Evaluate` screen. This will generate an example token that includes all of the
+claims and role mappings used.
+
+==== Realm Default Client Scopes
+
+The `Realm Default Client Scopes` allow you to define set of client scopes, which will be automatically linked to newly created clients.
+
+Open the left menu item `Client Scopes` and then select `Default Client Scopes`.
+
+From here, select the client scopes that you want to add as `Default Client Scopes` to newly created clients and `Optional Client Scopes`
+to newly created clients.
+
+.Default Client Scopes
+image:{project_images}/client-scopes-default.png[]
+
+Once the client is created, you can unlink the default client scopes, if needed. This is similar to how you
+remove <<_default_roles, Default Roles>>.
+
+==== Scopes explained
+
+The term `scope` is used in {project_name} on few places. Various occurences of scopes are related to each other, but may have
+a different context and meaning. To clarify, here we explain the various `scopes` used in {project_name}.
+
+Client scope::
+  Referenced in this chapter. Client scopes are entities in {project_name}, which are configured at the realm level and they can be
+  linked to clients. The client scopes are referenced by their name when a request is sent to the {project_name} authorization endpoint
+  with a corresponding value of the `scope` parameter. The details are described in the <<_client_scopes_linking, section about
+  client scopes linking>>.
+
+Role scope mapping::
+  This can be seen when you open tab `Scope` of a client or client scope. Role scope mapping allows you to limit the roles which can
+  be used in the access tokens. The details are described in the <<_role_scope_mappings, Role Scope Mappings section>>.
+
+ifeval::[{project_community}==true]
+
+Authorization scopes::
+  This is used by the Authorization feature. The `Authorization Scope` is the action which can be done in the application.
+  More details in the link:{authorizationguide_link}[Authorization Services Guide].
+
+endif::[]
+
+
+

server_admin/topics/clients/client-templates.adoc

@@ -1,19 +0,0 @@
-[[_client_templates]]
-=== Client Templates
-
-If you have a lot of applications you need to secure and register within your organization it can become quite tedious
-to configure the <<_protocol-mappers, protocol mappers>>
-and <<_client_scope, scope>> for each of these clients.  {project_name} allows you to define shared client configuration in an entity called a _client template_.
-
-To create a client template, go to the `Client Templates` left menu item.  This initial screen shows you a list of currently defined templates.
-
-To create a template click the `Create` button.  This brings you to a simple screen in which you name the template and hit save.
-A _client template_ will have similar tabs to regular clients.  You'll be able to define <<_protocol-mappers, protocol mappers>>
-and <<_client_scope, scope>> which can be inherited by other clients.
-
-Having a client inherit from a template is as simple as choosing the template from the `Client Template` drop down list on either the
-`Add Client` or client `Settings` tab.  You will see the `Mappers` and `Scope` tabs get additional switches which allow you
-to turn on or off inheriting from the parent template.
-
-Future versions of client templating may get more inheritable configuration options, but for now, that's all there is to talk about.
-

server_admin/topics/clients/oidc/service-accounts.adoc

@@ -10,7 +10,11 @@ configured your <<_client-credentials, client credentials>>.
 
 To use it you must have registered a valid `confidential` Client and you need to check the switch `Service Accounts Enabled` in {project_name} admin console for this client.
 In tab `Service Account Roles` you can configure the roles available to the service account retrieved on behalf of this client.
-Don't forget that you need those roles to be available in Scopes of this client as well (unless you have `Full Scope Allowed` on). As in normal login, roles from access token are the intersection of scopes and the service account roles.
+Remember that you must have the roles available in Role Scope Mappings (tab `Scope`) of this client as well, unless you
+have `Full Scope Allowed` on. As in a normal login, roles from access token are the intersection of:
+
+* Role scope mappings of particular client combined with the role scope mappings inherited from linked client scopes
+* Service account roles
 
 The REST URL to invoke on is `/auth/realms/{realm-name}/protocol/openid-connect/token`.
 Invoking on this URL is a POST request and requires you to post the client credentials.

server_admin/topics/clients/protocol-mappers.adoc

@@ -15,7 +15,8 @@ an OIDC based client.
 .Mappers Tab
 image:{project_images}/mappers-oidc.png[]
 
-Each client has several built-in mappers that are created for it by default.  They map things like, for example, email address to
+The new client does not have any built-in mappers, however it usually inherits some mappers from the client scopes as described
+in the <<_client_scopes, client scopes section>>. Protocol mappers map things like, for example, email address to
 a specific claim in the identity and access token.  Their function should each be self explanatory from their name.  There
 are additional pre-configured mappers that are not attached to the client that you can add
 by clicking the `Add Builtin` button.
@@ -26,16 +27,7 @@ next to one of the mappers in the list to get to the config screen.
 .Mapper Config
 image:{project_images}/mapper-config.png[]
 
-The best way to learn about a config option is to hover over its tooltip.  There are a few config options that
+The best way to learn about a config option is to hover over its tooltip.
-are common to all mappers:
-
-Consent Required::
-  If your client requires consent, this mapper will be displayed on the consent screen shown to the user.
-Consent Text::
-  If your client requires consent and the `Consent Required` switch is on, this is the text that will be displayed by the user.
-  The value for this text is localizable by specifying a substitution variable with `$\{var-name}` strings.  The
-  localized value is then configured within property files in your theme.  See the link:{developerguide_link}[{developerguide_name}]
-  for more information on localization.
 
 Most OIDC mappers also allow you to control where the claim gets put.  You can opt to include or exclude the claim from both the
 _id_ and _access_ tokens by fiddling with the `Add to ID token` and `Add to access token` switches.

server_admin/topics/overview/concepts.adoc

@@ -42,9 +42,10 @@ consent::
   Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process.
   After a user provides their credentials, {project_name} will pop up a screen identifying the client requesting a login and what identity
   information is requested of the user.  User can decide whether or not to grant the request.
-client templates::
+client scopes::
-  When a client is registered you need to enter configuration information about that client.  It is often useful to store a template
+  When a client is registered, you must define protocol mappers and role scope mappings for that client. It is often useful to store
-  to make create new clients easier.  {project_name} provides the concept of a client template for this.
+  a client scope, to make creating new clients easier by sharing some common settings. This is also useful for requesting some
+  claims or roles to be conditionally based on the value of `scope` parameter. {project_name} provides the concept of a client scope for this.
 client role::
   Clients can define roles that are specific to them.  This is basically a role namespace dedicated to the client.
 identity token::

server_admin/topics/roles/client-roles.adoc

@@ -2,9 +2,4 @@
 
 Client roles are basically a namespace dedicated to a client. Each client gets its own namespace. Client roles are managed under the `Roles` tab under each individual client. You interact with this UI the same way you do for realm-level roles.
 
-If the client has to explicitly request another client's role, the role has to be prefixed with the client ID when performing a request using the scope parameter. For example, if the client ID is `account` and the role is `admin`, the scope parameter is:
-
- `scope=account/admin`
-
-As noted in the realm roles section, multiple roles are separated by spaces.
 

server_admin/topics/roles/realm-roles.adoc

@@ -10,9 +10,8 @@ To create a role, click *Add Role* on this page, enter in the name and descripti
 .Add Role
 image:{project_images}/role.png[]
 
-The value for the `description` field is localizable by specifying a substitution variable with `$\{var-name}` strings. The localized value is then configured within property files in your theme. See the link:{developerguide_link}[{developerguide_name}] for more information on localization. If a client requires user _consent_, this description string is displayed on the consent page for the user.
+The value for the `description` field is localizable by specifying a substitution variable with `$\{var-name}` strings. The localized
+value is then configured within property files in your theme. See the link:{developerguide_link}[{developerguide_name}] for more information
+on localization.
 
-If the client has to explicitly request for a realm role, set `Scope Param Required` to true. The role then has to be specified using the `scope` parameter when requesting a token. Multiple realm roles are separated by space:
-
-`scope=admin user`
 

server_admin/topics/roles/role-scope-mappings.adoc

@@ -1,15 +1,15 @@
-[[_client_scope]]
+[[_role_scope_mappings]]
 
-=== Client Scope
+=== Role Scope Mappings
 
 When an OIDC access token or SAML assertion is created, all the user role mappings of the user are, by default, added as claims
 within the token or assertion.  Applications use this information to make access decisions on the resources controlled by that
 application.  In {project_name}, access tokens are digitally signed and can actually be re-used by the application
 to invoke on other remotely secured REST services.  This means that if an application gets compromised or there is a rogue
 client registered with the realm, attackers can get access tokens that have a broad range of permissions and your whole
-network is compromised.  This is where _client scope_ becomes important.
+network is compromised.  This is where _role scope mappings_ becomes important.
 
-_Client scope_ is a way to limit the roles that get declared inside an access token.  When a client requests that a user
+_Role Scope Mappings_ is a way to limit the roles that get declared inside an access token.  When a client requests that a user
 be authenticated, the access token they receive back will only contain the role mappings you've explicitly specified
 for the client's scope.  This allows you to limit the permissions each individual access token has rather than giving the
 client access to all of the user's permissions.  By default, each client gets all the role mappings of the user.
@@ -20,8 +20,8 @@ image:{project_images}/full-client-scope.png[]
 
 You can see from the picture that the effective roles of the scope are every declared role in the realm.
 To change this default behavior, you must explicitly turn off the `Full Scope Allowed` switch and declare the specific roles you want in each individual
-client.  Alternatively, you can also use <<_client_templates, client templates>>
+client.  Alternatively, you can also use <<_client_scopes, client scopes>>
-to define the scope for a whole set of clients.
+to define the same role scope mappings for a whole set of clients.
 
 .Partial Scope
 image:{project_images}/client-scope.png[]

server_admin/topics/roles/user-role-mappings/default-roles.adoc

@@ -1,4 +1,4 @@
-
+[[_default_roles]]
 ==== Default Roles
 
 Default roles allow you to automatically assign user role mappings when any user is newly created or imported through

server_admin/topics/sessions/offline.adoc

@@ -21,7 +21,8 @@ The admin can also view all the offline tokens issued in the `Offline Access` ta
 Offline tokens can also be revoked by setting a <<_revocation-policy, revocation policy>>.
 
 To be able to issue an offline token, users need to have the role mapping for the realm-level role `offline_access`.
-Clients also need to have that role in their scope.
+Clients also need to have that role in their scope. Finally, the client needs to have an `offline_access` client scope added as an `Optional
+client scope` to it, which is done by default.
 
 The client can request an offline token by adding the parameter `scope=offline_access` when sending authorization request to {project_name}.
 The {project_name} OIDC client adapter automatically adds this parameter when you use it to access secured URL of your application (i.e.

server_admin/topics/threat/scope.adoc

@@ -1,8 +1,8 @@
 
 === Limiting Scope
 
-By default, each new client application has an unlimited scope.  This means that every access token that is created
+By default, each new client application has an unlimited `role scope mappings`.  This means that every access token that is created
 for that client will contain all the permissions the user has.  If the client gets compromised and the access token
 is leaked, then each system that the user has permission to access is now also compromised.  It is highly suggested
-that you limit the roles an access token is assigned by using the <<_client_scope, Scope menu>> for each client.
+that you limit the roles an access token is assigned by using the <<_role_scope_mappings, Scope menu>> for each client.
 

upgrading/topics/keycloak/changes.adoc

@@ -1,5 +1,40 @@
 == Migration Changes
 
+=== Migrating to 4.0.0
+
+==== Client Templates changed to Client Scopes
+
+We added support for Client Scopes, which requires some attention during migration.
+
+Client Templates changed to Client Scopes::
+  Client Templates were changed to Client Scopes. If you had any Client Templates, their protocol mappers and role scope mappings
+  will be preserved.
+
+Spaces replaced in the names::
+  Client templates with the space character in the name were renamed by replacing spaces with an underscore, because spaces are
+  not allowed in the name of client scopes. For example, a client template `my template` will be changed to client scope `my_template`.
+
+Linking Client Scopes to Clients::
+  For clients which had the client template, the corresponding client scope
+  is now added as `Default Client Scope` to the client. So protocol mappers and role scope mappings will be preserved on the client.
+
+Realm Default Client Scopes not linked with existing clients::
+  During the migration, the list of built-in client scopes is added to each realm as well as list of `Realm Default Client Scopes`. However,
+  existing clients are NOT upgraded and new client scopes are NOT automatically added to them. Also all the protocol mappers and role
+  scope mappings are kept on existing clients. In the new version, when you create a new client, it automatically has Realm Default Client Scopes
+  attached to it and it does not have any protocol mappers attached to it. We did not change existing clients during migration as it
+  would be impossible to properly detect customizations, which you will have for protocol mappers of the clients, for example. If you want to
+  update existing clients (remove protocol mappers from them and link them with client scopes), you will need to do it manually.
+
+Consents need to be confirmed again::
+  The client scopes change required the refactoring of consents. Consents now point to client scopes, not to roles or protocol mappers.
+  Because of this change, the previously confirmed persistent consents by users are not valid anymore and users need to confirm
+  the consent page again after the migration.
+
+Some configuration switches removed::
+  The switch `Scope Param Required` was removed from Role Detail. The switches `Consent Required` and `Consent Text` were removed
+  from the Protocol Mapper details. Those switches were replaced by the Client Scope feature.
+
 === Migrating to 3.4.2
 
 ==== Added session_state parameter to OpenID Connect Authentication Response