Polish documentation for audience and client scopes (#38484)

closes #19127 Signed-off-by: mposolda <mposolda@gmail.com> Co-authored-by: Bruno Oliveira da Silva <bruno@abstractj.com> Signed-off-by: Marek Posolda <mposolda@gmail.com>
2026-05-07 23:50:03 -05:00 · 2025-04-03 08:43:06 +02:00
parent 93f6325a55
commit 6654e56a7c
15 changed files with 256 additions and 89 deletions
@@ -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]

@@ -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::[]
-
@@ -2,78 +2,140 @@
 = Audience support
 [role="_abstract"]
 Typically, the environment where {project_name} is deployed consists of a set of _confidential_ or _public_ client applications that use {project_name} for authentication.
+These clients are _frontend clients_, which may directly redirect user to {project_name} to request browser authentication. The particular client would then receive set of tokens after successful authentication.

-_Services_ (_Resource Servers_ in the https://datatracker.ietf.org/doc/html/draft-ietf-oauth-mtls-08#section-4.2[OAuth 2 specification]) are also available that serve requests from client applications and provide resources to these applications. These services require an _Access token_ (Bearer token) to be sent to them to authenticate a request. This token is obtained by the frontend application upon login to {project_name}.
+_Services_ (_Resource Servers_ in the https://datatracker.ietf.org/doc/html/draft-ietf-oauth-mtls-08#section-4.2[OAuth 2 specification]) are also available that serve requests from client applications and provide resources to these applications.
+These services require an _Access token_ (Bearer token) to be sent to them from _frontend application_ or from other service to authenticate a request.

-In the environment where trust among services is low, you may encounter this scenario:
+The care must be taken to make sure that access tokens have limited privileges and the particular access token cannot be misused by the service to access other third-party services.
+In the environment where trust among services is low, you may encounter this example scenario:

-. A frontend client application requires authentication against {project_name}.
+. A frontend client application `frontend-client` requires authentication against {project_name}.

 . {project_name} authenticates a user.

-. {project_name} issues a token to the application.
+. {project_name} issues a token to the application `frontend-client`.

-. The application uses the token to invoke an untrusted service.
+. The `frontend-client` application uses the token to invoke a service `service1`.

-. The untrusted service returns the response to the application. However, it keeps the applications token.
+. The `service1` service returns the response to the application. But assume that this service will try to misuse the token and keep it for the further use.

-. The untrusted service then invokes a trusted service using the applications token. This results in broken security as the untrusted service misuses the token to access other services on behalf of the client application.
+. The `service1` then invokes another service `service2` using the applications token, which was previously sent to it. The `service2` does not check that token was not supposed to be
+used to invoke it and it will serve the request and return successful response. This results in broken security as the `service1` misused the token to access other services on behalf of the client application `frontend-client`.

-This scenario is unlikely in environments with a high level of trust between services but not in environments where trust is low. In some environments, this workflow may be correct as the untrusted service may have to retrieve data from a trusted service to return data to the original client application.
+This scenario is unlikely in environments with a high level of trust between services but not in environments where trust is low.

-An unlimited audience is useful when a high level of trust exists between services. Otherwise, the audience should be limited. You can limit the audience and, at the same time, allow untrusted services to retrieve data from trusted services. In this case, ensure that the untrusted service and the trusted service are added as audiences to the token.
+To prevent any misuse of the access token, the access token can contain the claim `aud`, which represents the audience. The claim `aud` should typically represent client ids of all services where the token
+is supposed to be used. In the environments with low trust among services, it is recommended to:

-To prevent any misuse of the access token, limit the audience on the token and configure your services to verify the audience on the token. The flow will change as follows:
+* Limit the audience on the token to make sure that access tokens contain just limited amount of audiences.

-. A frontend application authenticates against {project_name}.
+* Configure your services to verify the audience on the token.
+
+To prevent `service1` from the example above to misuse the token, the secure variant of the flow may instead look like this:
+
+. A frontend application `frontend-client` authenticates against {project_name}.

 . {project_name} authenticates a user.

-. {project_name} issues a token to the application. The application knows that it will need to invoke an untrusted service so it places *scope=<untrusted service>* in the authentication request sent to {project_name} (see <<_client_scopes, Client Scopes section>> for more details about the _scope_ parameter).
+. {project_name} issues a token to the `frontend-client` application. The `frontend-client` knows that it will need to invoke `service1` so it places `scope=service1-scope` in the authentication request sent to {project_name}.
+The scope `service1-scope` is a <<_client_scopes,Client scope>>, which may need to be created by administrator. In the <<_audience_setup,sections below>> there are some options how to setup such a client scope.
+The token claim will look like:
 +
-The token issued to the application contains a reference to the untrusted service in its audience (*"audience": [ "<untrusted service>" ]*) which declares that the client uses this access token to invoke the untrusted service.
-+
-.The untrusted service serves the request to the client application but also keeps the token.
-
-. The untrusted service invokes a trusted service with the token. Invocation is not successful because the trusted service checks the audience on the token and find that its audience is only for the untrusted service. This behavior is expected and security is not broken.
-
-If the client wants to invoke the trusted service later, it must obtain another token by reissuing the SSO login with *scope=<trusted service>*. The returned token will then contain the trusted service as an audience:
-
 [source,json]
 ----
-"audience": [ "<trusted service>" ]
+"aud": "service1"
 ----
-Use this value to invoke the *<trusted service>*.
+
+This declares that the client can use this access token to invoke the `service1`.

+. The `frontend-client` application uses the token to invoke a service `service1`.
+
+. The `service1` serves the request to the client application `frontend-application`. But assume that this service will try to misuse the token and keep it for the further use.
+
+. The `service1` will then try to invoke a `service2` with the token. Invocation is not successful because the `service2` service checks the audience on the token and find that its audience is only for the `service1`. Hence `service2` will reject the request and will return an error to `service1`. This behavior is expected and security is not broken.
+
+== Ability for the service to call another service
+
+In some environments, it may be desired that the `service1` may have to retrieve additional data from a `service2` to return data to the original client application `frontend-client`. In order to make this
+possible to work, there are few possibilities:
+
+* Make sure that initial access token issued to `frontend-client` will contain both `service1` and `service2` as audiences. Assuming that there are proper client scopes set, the `frontend-client` can possibly use
+the `scope=service1-scope service2-scope` as a value of the `scope` parameter. The issued token would then contain the `aud` claim like:
+
+[source,json]
+----
+"aud": [ "service1", "service2" ]
+----
+
+Such access token can be used to invoke both `service1` or `service2`. Hence `service1` will be able to successfully use such token to invoke `service2` to retrieve additional data.
+
+* The previous approach with both services in the token audience allows that `service1` is allowed to invoke `service2`. However it means that `frontend-client` can also directly use his access token to invoke `service2`.
+This may not be desired in some cases. You may want `service1` to be able to invoke `service2`, but at the same time, you do not want `frontend-client` to be able to directly invoke `service2`. The solution
+to such scenario might be the use of the link:{securing_apps_token_exchange_link}[Token exchange]. In that case, the initial token would still have only `service1` as an audience.
+However once the token is sent to `service1`, the `service1` may send Token exchange request to exchange the token for another token, which would have `service2` as an audience. Please see
+the link:{securing_apps_token_exchange_link}[{securing_apps_token_exchange_name}] for the details on how to use it.
+
+[[_audience_setup]]
 == Setup

 When setting up audience checking:

 * Ensure that services are configured to check audience on the access token sent to them. This may be done in a way specific to your client OIDC adapter, which you are using to secure your OIDC client application.

-* Ensure that access tokens issued by {project_name} contain all necessary audiences. Audiences can be added using the client roles as described in the <<_audience_resolve, next section>> or hardcoded. See <<_audience_hardcoded, Hardcoded audience>>.
+* Ensure that access tokens issued by {project_name} contain all necessary audiences.
+
+Audiences can be added to the token by two ways:
+
+** Using the client roles as described in the <<_audience_resolve, Audience resolve section>>.
+
+** Hardcoded audience as described in the <<_audience_hardcoded, Hardcoded audience section>>.

 [[_audience_resolve]]
-== Automatically add audience
+== Automatically add audience based on client roles

-An _Audience Resolve_ protocol mapper is defined in the default client scope _roles_. The mapper checks for clients that have at least one client role available for the current token. The client ID of each client is then added as an audience, which is useful
+An _Audience Resolve_ protocol mapper is defined in the default client scope _roles_. The mapper checks for clients that have at least one client role available for the current token. The client ID of each such client is then added as an audience, which is useful
 if your service clients rely on client roles. Service client could be usually a client without any flows enabled, which may not have any tokens issued directly to itself. It represents an OAuth 2 _Resource Server_.

-For example, for a service client and a confidential client,
-you can use the access token issued for the confidential client to invoke the service client REST service. The service client will be automatically added as an audience to the access token issued for the confidential client if the following are true:
+The <<_oidc_token_role_mappings,Token role mappings section>> contains the details about how are client roles added into the token. Please also see the example below.

-* The service client has any client roles defined on itself.
+=== Example - token role mappings and audience claim

-* Target user has at least one of those client roles assigned.
+Here are the example steps how to use the client roles to make `aud` claim added to the token:

-* Confidential client has the role scope mappings for the assigned role.
+. Create a <<proc-creating-oidc-client_{context},OIDC client>> `service1`. It may be possible to disable *Standard flow* or any other flows for this client
+as it is a service client, which may never directly authenticate by itself. The possible exception might be *Standard Token Exchange* switch if needed as described above.

-[NOTE]
-====
-If you want to ensure that the audience is not added automatically, do not configure role scope mappings directly on the confidential client. Instead, you can create a dedicated client scope that contains the role scope mappings for the client roles of your dedicated client scope.
+. Go to *Roles* tab of that client and create client role `service1-role`.

-Assuming that the client scope is added as an optional client scope to the confidential client, the client roles and the audience will be added to the token if explicitly requested by the *scope=<trusted service>*  parameter.
-====
+. Create user `john` in the same realm and assign him the client role `service1-role` of client `service1` created in the previous step.
+<<proc-assigning-role-mappings_{context},This section>> contains some details on how to do it.
+
+. Create client scope named `service1-scope`. It can be marked with *Include in token scope* as *ON*. See <<_client_scopes,this section>> for the details on how to create and set new client scope.
+
+. Go to the tab *Scope* of the `service1-scope` and add the role `service1-role` of the client `service1` to the <<_role_scope_mappings,Role scope mappings>> of this client scope
+
+. Create another client `frontend-client` in the realm.
+
+. Click to the tab *Client scopes* of this client and select the first dedicated client scope `frontend-client-dedicated` and then go to the tab *Scope* and disable *Full scope allowed* switch
+
+. Go back to the tab *Client scopes* of this client and click *Add client scope* and link the `service1-scope` as *Optional*. See <<_client_scopes_linking, Client Scopes Linking section>> for more details.
+
+. Click the sub-tab *Evaluate* in the *Client scopes* as described in <<_client_scopes_evaluate,this section>>. When filling user `john` and the subtab *Generated access token*, it can be seen that
+there is not any `aud` claim as there are not any client roles in the generated example token. However when adding also the scope `service1-scope` to the *Scope* field, it can be seen that there is client
+role `service1-role` as it is in *Role scope mappings* of the `service1-scope` and also in the role mappings of the user `john`. Due to that the `aud` claim will also contain `service1`.
+
+.Audience resolve example
+image:images/audience_resolving_evaluate.png[]
+
+If you want the `service1` audience to be always applied for the tokens issued to the `frontend-client` client (without using the parameter `scope=service1-scope`), it can be fine to instead do any of these:
+
+* Assign the `service1-scope` as *Default* client scope rather than *Optional*
+
+* Add the role scope mapping of the `service1-role` directly to the <<_client_scopes_dedicated,Dedicated client scope>> of the client. In this case, you will not need the `service1-scope` at all.
+
+Note that since this approach is based on client roles, it also requires that user himself (user `john` in the example above) is a member of some client role of the client `service1`. Otherwise if there
+are not any client roles assigned, the audience `service1` will not be included. If you want audience to be included regardless of client roles, see the <<_audience_hardcoded,Hardcoded audience>> section instead.

 [NOTE]
 ====
@@ -91,28 +153,31 @@ You can use any custom value, for example a URL, if you want to use a different

 You can add the protocol mapper directly to the frontend client. If the protocol mapper is added directly, the audience will always be added as well.

-For more control over the protocol mapper, you can create the protocol mapper on the dedicated client scope, which will be called for example *good-service*.
+For more control over the protocol mapper, you can create the protocol mapper on the dedicated client scope, which will be called for example *service2*.

+Here the example steps for the hardcoded audience
+
+. Create a client `service2`
+
+. Create a client scope `service2-scope`.
+
+. In the tab *Mappers* of that client scope, select *Configure a new mapper* and select *Audience*
+
+. Select *Included Client Audience* as a `service2` and save the mapper
+
 .Audience protocol mapper
 image:images/audience_mapper.png[]
-
-* From the <<_client_installation, Client details tab>> of the *good-service* client, you can generate the adapter configuration and confirm that _verify-token-audience_  is set to *true*. This action forces the adapter to verify the audience if you use this configuration.
-
-* You need to ensure that the confidential client is able to request *good-service* as an audience in its tokens.
 +
-On the confidential client:
-+
-. Click the _Client Scopes_ tab.
-. Assign *good-service* as an optional (or default) client scope.
-+
-See <<_client_scopes_linking, Client Scopes Linking section>> for more details.
+. Link the newly created client scope with some client. For example it can be linked as *Optional* client scope to the client `frontend-client` created in the <<_audience_resolve,previous example>>.

-* You can optionally <<_client_scopes_evaluate, Evaluate Client Scopes>> and generate an example access token. *good-service* will be added to the audience of the generated access token if *good-service* is included in the _scope_ parameter, when you assigned it as an optional client scope.
+. You can optionally <<_client_scopes_evaluate, Evaluate Client Scopes>> for the client where the client scope was linked (For example `frontend-client`) and generate an example access token.
+The audience `service2` will be added to the audience of the generated access token if `service2-scope` is included in the _scope_ parameter, when you assigned it as an optional client scope.

-* In your confidential client application, ensure that the _scope_ parameter is used. The value *good-service* must be included when you want to issue the token for accessing *good-service*.
-+
-See:
-+
-** *Keycloak JavaScript adapter* in the link:{securing_apps_link}[securing apps] section if your application uses the javascript adapter.
+In your confidential client application, ensure that the _scope_ parameter is used. The value like _scope=service2-scope_ must be included when you want to issue the token for accessing `service2`.

-NOTE: Both the _Audience_ and _Audience Resolve_ protocol mappers add the audiences to the access token only, by default. The ID Token typically contains only a single audience, the client ID for which the token was issued, a requirement of the OpenID Connect specification. However, the access token does not necessarily have the client ID, which was the token issued for, unless the audience mappers added it.
+See in the link:{securing_apps_base_link}/javascript-adapter[{project_name} JavaScript adapter] section if your application uses the javascript adapter for how to send the _scope_ parameter with the desired value.
+
+If you prefer to not include `scope` parameter in your requests, you can instead link the `service2-scope` as a *Default* client scope or use the client dedicated scope where you configure this mapper.
+This is useful if you want to always apply the audience for all the authentication request of OIDC client `frontend-client`.
+
+NOTE: Both the _Audience_ and _Audience Resolve_ protocol mappers add the audiences to the access token only, by default. The ID Token typically contains only a single audience, the client ID for which the token was issued, a requirement of the OpenID Connect specification. However, the access token does not necessarily have the client ID, which was the token issued for, unless the _Audience_ mapper added it.
@@ -0,0 +1,80 @@
+[[_oidc_token_role_mappings]]
+= Role mappings in the token
+
+When a user authenticates, there are some roles that are added to the access token. By default, the <<proc-creating-realm-roles_{context},Realm roles>> are added to the access
+token into the `realm_access` claim. The <<con-client-roles_{context},Client roles>> are added by default to the `resource_access` claim.
+
+The roles added to the token are an intersection of:
+
+* Roles, that are <<_oidc_token_role_mappings_user_roles,assigned to the user>>.
+
+* <<_role_scope_mappings,Role scope mappings>> of the roles that the client is permitted to access
+
+[[_oidc_token_role_mappings_user_roles]]
+== Roles assigned to the user
+
+Roles assigned to the user can be defined in the Role mappings as described in <<proc-assigning-role-mappings_{context},this section>>. Few details:
+
+* In case that a user is a member of some <<proc-managing-groups_{context},groups>>, then all the roles of these groups are also applied.
+
+* In case that a role is a <<_composite-roles,composite role>>, the child roles of the composite role are also applied. In the token, the list of the roles is expanded and would contain all the roles.
+
+* In case that the authenticated user is not a normal user, but a <<_service_accounts,Service account>>, which represents a client, then the service account roles are used. The service account roles are defined
+in the tab *Service accounts roles* of the particular client.
+
+== Role protocol mappers
+
+Similarly to other claims, the roles are added to the access token issued for the client by the dedicated <<_protocol-mappers,Protocol mappers>>. There is a <<_client_scopes_protocol,Built-in client scope *roles*>>
+defined in the realm. Since it is a <<proc_updating_client_scopes_{context},Realm default client scope>>, it is defined by default as a <<_client_scopes_linking,Default client scope>> for every realm client.
+You can see this client scope in the admin console by looking at the tab *Client scopes* and then looking for the *roles* client scope. This client scope contains these protocol mappers by default:
+
+* The protocol mapper *realm roles* - This protocol mapper is used to add the realm roles to the token claim. By default, the configuration looks like this:
+
+.Realm roles mapper
+image:images/mapper-oidc-realm-roles.png[]
+
+* The protocol mapper *client roles* - This protocol mapper is used to add the client roles to the token claim. By default, the configuration looks like this:
+
+.Client roles mapper
+image:images/mapper-oidc-client-roles.png[]
+
+* The protocol mapper *audience resolve* - This protocol mapper is used to fill the `aud` claim in the access token based on the applied client roles. The details about this mapper are in the <<_audience_resolve,Audience resolve section>>.
+
+As you can see in the configuration of realm roles and client roles mappers, it is possible to configure:
+
+* If roles are added just to the access token or also to other tokens, like for example the ID token. By default, roles are added to the access token and to the introspection endpoint.
+
+* What are the claims where the roles would be added. By default, the realm roles are added to the `realm_access` claim. So, for example, the claim in the JWT token containing 2 realm roles `role1` and `role2` will look similar to this:
+
+[source,json]
+----
+"realm_access": {
+  "roles": [ "role1", "role2" ]
+}
+----
+
+The client roles are added to the `resource_access` token claim by default. This claim will look like this in the token, which contains
+client roles `manage-account` and `manage-account-links` of client `account` and client role `target-client1-role` of the client `target-client1`:
+
+[source,json]
+----
+"resource_access": {
+  "target-client1": {
+    "roles": [ "target-client1-role" ]
+  },
+  "account": {
+    "roles": [ "manage-account", "manage-account-links" ]
+  }
+}
+----
+
+By adjusting the configuration option *Token claim name* of the role protocol mappers, it is possible to specify that these roles will be added to the token in the configured claim.
+
+If you want to update the role claims just for one specific client (For example, client `foo` expects the realm roles in the claim `my-realm-roles` instead of the claim `realm_access`), then it is
+possible to remove the default client scope *roles* from your client and instead configure the realm/client protocol mapper in the <<_client_scopes_dedicated,dedicated client scope>> of your client.
+
+== Example
+
+The <<_audience_resolve,Audience documentation>> contains a more detailed example, which covers some details about the role mappings and about the audience (Claim `aud`) added to the token. Also, it can be
+useful to try the <<_client_scopes_evaluate,Client scopes evaluation>> to see what are the effective scopes, protocol mappers and role scope mappings used when issuing the token for the particular client
+and how the JWT tokens would look like for the particular combination of user, client, and applied client scopes.
@@ -10,12 +10,15 @@ The *Mappers* tab contains the protocol mappers and the *Scope* tab contains the

 This will also show you the value of the *scope* parameter. This parameter needs to be sent from the application to the {project_name} OpenID Connect authorization endpoint.

+[NOTE]
+====
+If your application uses the {securing_apps_base_link}/javascript-adapter[{project_name} JavaScript adapter], see its section to learn how to send the *scope* parameter with the desired value.
+====
+
+You can also simulate how the access token, ID token, or UserInfo response issued to this client looks for a particular selected user and for a specific value of the `audience` parameter. Note
+that the `audience` parameter is currently only supported for the token exchange grant. It is recommended to leave it empty when simulating any other grant.
+
 .Evaluating client scopes
 image:images/client-scopes-evaluate.png[]

-[NOTE]
-====
-To send a custom value for a *scope* parameter from your application, see the *Keycloak JavaScript adapter* in the link:{securing_apps_link}[securing apps] section, for javascript adapters.
-====
-
 All examples are generated for the particular user and issued for the particular client, with the specified value of the *scope* parameter. The examples include all of the claims and role mappings used.
@@ -3,15 +3,7 @@
 [role="_abstract"]
 Use *Realm Default Client Scopes* to define sets of client scopes that are automatically linked to newly created clients.

-.Procedure
-. Click the *Client Scopes* tab for the client.
-ifeval::[{project_product}==true]
-. Click *Default Client Scopes*.
-endif::[]
-
-From here, select the client scopes that you want to add as *Default Client Scopes* to newly created clients and *Optional Client Scopes*.
-
-.Default client scopes
-image:images/client-scopes-default.png[]
+To see the realm default client scopes, click the *Client Scopes* tab on the left side of the admin console. In the *Assigned type* column, you can specify whether a particular client scope should be added as
+a *Default Client Scope* or an *Optional Client Scope* to newly created clients. See <<_client_scopes_linking, this section>> for details on what _default_ and _optional_ client scopes are.

 When a client is created, you can unlink the default client scopes, if needed. This is similar to removing <<_default_roles, Default Roles>>.
@@ -1,14 +1,12 @@
 [[_oid4vci]]
 == Configuring {project_name} as a Verifiable Credential Issuer

-+
 [IMPORTANT]
 ====
 This is an experimental feature and should not be used in production. Backward compatibility is not guaranteed, and future updates may introduce breaking changes.
 ====
-+

-{project_name} provides support for https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html[OpenID for Verifiable Credential Issuance].
+{project_name} provides experimental support for https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html[OpenID for Verifiable Credential Issuance].

 === Introduction

@@ -58,8 +56,8 @@ An access token is required to authenticate API requests.

 Refer to the following {project_name} documentation sections for detailed steps on:

- https://www.{project_name}.org/docs/latest/server_admin/#proc-creating-oidc-client_server_administration_guide[Creating a Client^]
- https://www.{project_name}.org/securing-apps/token-exchange#_internal_internal_making_request[Obtaining an Access Token^]
+- <<proc-creating-oidc-client_{context},Creating a Client>>
+- <<_oidc-auth-flows-direct, Obtaining an Access Token>>

 === Configuration Steps

@@ -73,7 +71,7 @@ For Verifiable Credential (VC) issuance, create a dedicated realm to ensure isol
 [NOTE]
 ====
 For detailed instructions on creating a realm, refer to the {project_name} documentation:
-https://www.{project_name}.org/docs/latest/server_admin/index.html#proc-creating-a-realm_server_administration_guide[Creating a Realm^].
+<<proc-creating-a-realm_{context},Creating a Realm>>.
 ====

 === Creating a User Account
@@ -83,7 +81,7 @@ A test user is required to simulate credential issuance and verify the setup.
 [NOTE]
 ====
 For step-by-step instructions on creating a user, refer to the {project_name} documentation:
-https://www.{project_name}.org/docs/latest/server_admin/index.html#assembly-managing-users_server_administration_guide[Creating a User^].
+<<assembly-managing-users_{context},Creating a User>>.
 ====

 Ensure that the user has a valid username, email, and password. If the password should not be reset upon first login, disable the "Temporary" toggle during password configuration.
@@ -95,7 +93,7 @@ Ensure that the user has a valid username, email, and password. If the password
 [NOTE]
 ====
 For a detailed guide on configuring realm keys, refer to the {project_name} documentation:
-https://www.{project_name}.org/docs/latest/server_admin/#realm_keys[Managing Realm Keys^].
+<<realm_keys,Managing Realm Keys>>.
 ====

 ==== Configuring Key Providers
@@ -360,10 +358,10 @@ A successful response returns a JSON object containing details such as:
 - **Credential formats**
 - **Issuer metadata**

-== Conclusion
+=== Conclusion

 You have successfully configured **{project_name} as a Verifiable Credential Issuer** using the **OID4VCI protocol**.
 This setup leverages {project_name}'s robust **identity management capabilities** to issue secure, **standards-compliant VCs**.

-For a **complete reference implementation**, see our sample project:
+For a **complete reference implementation**, see the sample project:
 https://github.com/adorsys/{project_name}-ssi-deployment/tree/main[{project_name} SSI Deployment^].
@@ -6,7 +6,7 @@
 [role="_abstract"]
 On creation of an OIDC access token or SAML assertion, the user role mappings become claims within the token or assertion.  Applications use these claims to make access decisions on the resources controlled by the application.  {project_name} digitally signs access tokens and applications reuse them to invoke remotely secured REST services.  However, these tokens have an associated risk. An attacker can obtain these tokens and use their permissions to compromise your networks. To prevent this situation, use _Role Scope Mappings_.

-_Role Scope Mappings_ limit the roles declared inside an access token.  When a client requests a user authentication, the access token they receive contains only the role mappings that are explicitly specified for the client's scope.  The result is that you limit the permissions of each individual access token instead of giving the client access to all the users permissions.  
+_Role Scope Mappings_ limit the roles declared inside an access token. When a client requests user authentication, the access token it receives contains only the role mappings that are explicitly specified for the client's scope. The result is that the permissions of each individual access token are limited instead of giving the client access to all the user's permissions.

 By default, each client gets all the role mappings of the user.
 You can view the role mappings for a client.
@@ -26,3 +26,5 @@ You can also use <<_client_scopes, client scopes>> to define the same role scope

 .Partial scope
 image:images/client-scope.png[Partial scope]
+
+See the <<_oidc_token_role_mappings, Token Role mappings section>> for details about the algorithm that adds the roles to the token.