Improve documentation for the case when 'basic' client scope already exists

closes #29880

Signed-off-by: mposolda <mposolda@gmail.com>

docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc

@@ -266,7 +266,7 @@ When searching for users by user attribute, Keycloak no longer searches for user
 
 = New default client scope `basic`
 
-The new client scope named `basic` is added as a realm "default" client scope and hence will be added to all newly created clients. The client scope is also automatically added to all existing clients during migration.
+The new client scope named `basic` is added as a realm "default" client scope and hence will be added to all newly created OIDC clients. The client scope is also automatically added to all existing OIDC clients during migration.
 
 This scope contains preconfigured protocol mappers for the following claims:
 
@@ -275,6 +275,11 @@ This scope contains preconfigured protocol mappers for the following claims:
 
 This provides additional help to reduce the number of claims in a lightweight access token, but also gives the chance to configure claims that were always added automatically.
 
+NOTE: In case you already have client scope named `basic` in some of your realms, then the new client scope `basic` will not be added to your realm and will not be added to any clients. The
+migration would be ignored for this particular case. In that case, you either need to make sure to rename your client scope to something different than `basic` before you migrate to this
+{project_name} version or you need to manually deal with missing `sub` and `auth_time` claims in case you need them in your tokens and you may need to manually add corresponding protocol mappers
+to some of your client scopes.
+
 = Removed `session_state` claim
 
 The `session_state` claim, which contains the same value as the `sid` claim, is now removed from all tokens as it is not required according to the OpenID Connect Front-Channel Logout and OpenID Connect Back-Channel Logout specifications. The `session_state` claim remains present in the Access Token Response in accordance with OpenID Connect Session Management specification.

model/storage-private/src/main/java/org/keycloak/migration/migrators/MigrateTo25_0_0.java

@@ -21,7 +21,6 @@ package org.keycloak.migration.migrators;
 
 
 import org.jboss.logging.Logger;
-import org.keycloak.common.Profile;
 import org.keycloak.migration.MigrationProvider;
 import org.keycloak.migration.ModelVersion;
 import org.keycloak.models.ClientScopeModel;
@@ -63,6 +62,8 @@ public class MigrateTo25_0_0 implements Migration {
 
             //add basic scope to all existing OIDC clients
             session.clients().addClientScopeToAllClients(realm, basicScope, true);
+        } else {
+            LOG.warnf("Client scope '%s' already exists in the realm '%s'. Please migrate this realm manually if you need basic claims in your tokens.", basicScope.getName(), realm.getName());
         }
 
         // offer a migration for persistent user sessions which was added in KC25

server-spi/src/main/java/org/keycloak/models/ClientProvider.java

@@ -125,7 +125,10 @@ public interface ClientProvider extends ClientLookupProvider, Provider {
     void removeClientScope(RealmModel realm, ClientModel client, ClientScopeModel clientScope);
 
     /**
-     * Add specified client scope to all non bearer-only clients in the realm, which have same protocol as specified client scope
+     * Add specified client scope to all non bearer-only clients in the realm, which have same protocol as specified client scope.
+     *
+     * Method may be used just for new client scopes, which are not yet assigned to any clients as if specified clientScope is already assigned
+     * to some client, there might be issues related to duplicate entries.
      *
      * @param realm Realm
      * @param clientScope client scope from the specified realm, which would be added to all clients