KEYCLOAK-6884 KEYCLOAK-3454 KEYCLOAK-8298 Documentation for default 'roles' and 'web-origins' client scopes

server_admin/topics/clients/client-scopes.adoc

@@ -28,7 +28,8 @@ Once you have created new realm, you can see that there is a list of pre-defined
 
 * 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` .
+* For the OpenID Connect protocol, there are client scopes `profile`, `email`, `address`, `phone`, `offline_access`, `roles` and
+`web-origins`.
 
 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 https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification],
@@ -51,6 +52,13 @@ 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).
 
+The client scope `roles` is not defined in the OpenID Connect specification and it is also not added automatically to the `scope`
+claim in the access token. This client scope has some mappers, which are used to add roles of the user to the access token and
+possibly add some audiences for the clients with at least one client role as described in the <<_audience_resolve, Audience section>>.
+
+The client scope `web-origins` is also not defined in the OpenID Connect specification and not added to the `scope` claim. This is used
+to add allowed web origins to the access token `allowed-origins` claim.
+
 ==== Consent related settings
 
 Client scope contains options related to the consent screen. Those options are useful only if the linked client is configured to

server_admin/topics/clients/oidc/audience.adoc

@@ -108,4 +108,25 @@ image:{project_images}/audience_mapper.png[]
   adapter, or the link:{adapterguide_link}#_javascript_adapter[javascript adapter section], if your application uses the
   javascript adapter.
 
+[[_audience_resolve]]
+===== Automatically add audience
+
+There is another way that the audience can be added to the token. In the default client scope _roles_, there is an _Audience Resolve_
+protocol mapper defined. This protocol mapper will check all the clients for which current token has at least one client role
+available. Then the client ID of each of those clients will be added as an audience automatically. This is especially useful if
+your service (usually bearer-only) clients rely on client roles. In the example in previous section, if all of those are true:
+
+* The `good-service` client has any client role defined on itself
+
+* Target user has this client role assigned
+
+* Client `my-app` has the role scope mappings for this role
+
+then the `good-service` will be automatically added as an audience. In this case, you do not need to set up the audience client
+scope as described in the previous section.
+
+NOTE: If you are unsure what the correct audience and roles in the token will be, it is always a good idea to
+<<_client_scopes_evaluate, Evaluate Client Scopes>> in the admin console and do some testing around it.
+
+
 

upgrading/topics/keycloak/changes.adoc

@@ -1,5 +1,25 @@
 == Migration Changes
 
+=== Migrating to 4.6.0
+
+==== New default client scopes
+
+We have added new realm default client scopes `roles` and `web-origins`. These client scopes contain protocol
+mappers to add the roles of the user and allowed web origins to the token. During migration, these client scopes should be
+automatically added to all the OpenID Connect clients as default client scopes. Hence no setup should be required after database
+migration is finished.
+
+===== Protocol mapper SPI addition
+Related to this, there is a small addition in the (unsupported) Protocol Mappers SPI. You can be affected only if you
+implemented a custom ProtocolMapper. There is a new `getPriority()`` method on the ProtocolMapper interface. The method has the
+default implementation set to return 0. If your protocol mapper implementation relies on the roles in the access token `realmAccess`
+or `resourceAccess` properties, you may need to increase the priority of your mapper.
+
+===== Audience resolving
+
+Audiences of all the clients, for which authenticated user has at least one client role in the token, are automatically added
+to the `aud` claim in the access token now.
+
 === Migrating to 4.4.0
 
 ==== Upgrade to Wildfly 13