Polish documentation for audience and client scopes (#38484)

closes #19127

Signed-off-by: mposolda <[email protected]>


Co-authored-by: Bruno Oliveira da Silva <[email protected]>
Signed-off-by: Marek Posolda <[email protected]>

Author: mposolda

docs/documentation/server_admin/images/audience_mapper.png

@@ -16,5 +16,6 @@ include::oidc/proc-secret-rotation.adoc[leveloffset=+1]
 
 include::oidc/proc-using-a-service-account.adoc[leveloffset=+1]
 
+include::oidc/con-token-role-mappings.adoc[leveloffset=+1]
 include::oidc/con-audience.adoc[leveloffset=+1]
 

docs/documentation/server_admin/images/audience_resolving_evaluate.png

@@ -10,7 +10,7 @@ Client scopes also support the OAuth 2 *scope* parameter. Client applications us
 
 include::proc-creating-client-scopes.adoc[]
 
-
+[[_client_scopes_protocol]]
 == Protocol
 When you create a client scope, choose the *Protocol*. Clients linked in the same scope must have the same protocol.
 
@@ -21,7 +21,7 @@ Each realm has a set of pre-defined built-in client scopes in the menu.
 ** *roles*
 +
 This scope is not defined in the OpenID Connect specification and is not added automatically to the *scope* claim in the access token. This scope has mappers, which are used to add the roles of the user to the access token and
-add audiences for clients that have at least one client role. These mappers are described in more detail in the <<_audience_resolve, Audience section>>.
+add audiences for clients that have at least one client role. These mappers are described in more detail in the <<_oidc_token_role_mappings, Token Role mappings section>> and <<_audience_resolve, Audience section>>.
 +
 ** *web-origins*
 +
@@ -60,9 +60,20 @@ Display On Consent Screen::
 Consent Screen Text::
   The text displayed on the consent screen when this client scope is added to a client when consent required defaults to the name of client scope. The value for this text can be customised by specifying a substitution variable with *${var-name}* strings. The customised value is  configured within the property files in your theme. See the  link:{developerguide_link}[{developerguide_name}] for more information on customisation.
 
+== Include in token scope
+
+There is the *Include in token scope* switch on the client scope. If on, the name of this client scope will be added to the access token property scope, and to the Token Response and Token Introspection Endpoint
+response claim `scope`. If off, this client scope will be omitted from the token and from the Token Introspection Endpoint response. As mentioned above, some built-in client scopes have this switch disabled, which means
+that they are not included in the `scope` claim even if they are applied for the particular request.
+
 [[_client_scopes_linking]]
 == Link client scope with the client
-Linking between a client scope and a client is configured in the *Client Scopes* tab of the client. Two ways of linking between client scope and client are available.
+Linking between a client scope and a client is configured in the *Client Scopes* tab of the client. Here is how it looks for the client application `myclient`:
+
+.Client scopes linking to client
+image:images/client-scopes-default.png[]
+
+There are two ways of linking between the client scope and the client.
 
 Default Client Scopes::
 This setting is applicable to the OpenID Connect and SAML clients. Default client scopes are applied when issuing OpenID Connect tokens or SAML assertions for a client. The client will inherit Protocol Mappers and Role Scope Mappings that are defined on the client scope. For the OpenID Connect Protocol, the Mappers and Role Scope Mappings are always applied, regardless of the value used for the scope parameter in the OpenID Connect authorization request.
@@ -80,6 +91,22 @@ scope=openid phone
 
 The scope parameter contains the string, with the scope values divided by spaces. The value *openid* is the meta-value used for all OpenID Connect requests. The token will contain mappers and role scope mappings from the default client scopes *profile* and *email* as well as *phone*, an optional client scope requested by the scope parameter.
 
+[[_client_scopes_dedicated]]
+=== Dedicated client scope
+
+There is a special client scope, which is linked to every client. It is a dedicated client scope, which is always shown as the first client scope when you click on the tab *Client scopes* of the particular client. 
+For example, for client `myclient`, the client scope is shown as `myclient-dedicated`. This client scope represents the protocol mappers and role scope mappings, which are linked directly to the client itself.
+
+It is not possible to unlink the dedicated client scope from a client. Also, it is not possible to link this dedicated client scope to a different client. In other words, the dedicated client scope is useful
+just for protocol mappers and role scope mappings, which are specific to a single client. In case you want to share the same protocol mapper configuration among multiple clients, it is usually useful to create
+a client scope in the realm tab *Client scopes* and then link this shared client scope to every client that should apply this shared configuration.
+
+In the tab *Scope* of the dedicated client scope, you can define role scope mappings applicable to this client. You can also see the switch *Full scope allowed* in this tab.
+The details about this switch are described in <<_role_scope_mappings, this section>> and in <<_oidc_token_role_mappings,this section>>.
+
+NOTE: In the admin REST API and in the internal {project_name} storage, the dedicated client scope does not exist as its protocol mappers and role scope mappings are internally linked to the client itself. The.
+dedicated client scope is in fact just an abstraction for the admin console UI.
+
 [[_client_scopes_evaluate]]
 == Evaluating Client Scopes
 include::proc-evaluating-client-scopes.adoc[]
@@ -97,16 +124,14 @@ If a user is not permitted to use the client scope, no protocol mappers or role
 include::proc-updating-default-scopes.adoc[]
 
 == Scopes explained
+
+The term _scope_ has multiple meanings within {project_name} and across the OAuth/OIDC specifications. Below is a clarification of the different _scopes_ used in {project_name}:
+
 Client scope::
 Client scopes are entities in {project_name} that are configured at the realm level and can be linked to clients. 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. See the <<_client_scopes_linking, client scopes linking>> section for more details.
 
 Role scope mapping::
 This is available under the *Scope* tab of a client or client scope. Use *Role scope mapping* to limit the roles that can be used in the access tokens. See the <<_role_scope_mappings, Role Scope Mappings section>> for more details.
 
-ifeval::[{project_community}==true]
-
 Authorization scopes::
 The *Authorization Scope* covers the actions that can be performed in the application. See the link:{authorizationguide_link}[Authorization Services Guide] for more details.
-
-endif::[]
-