FGAP documentation

Closes #37245

Signed-off-by: vramik <vramik@redhat.com>

docs/documentation/release_notes/topics/26_2_0.adoc

@@ -8,6 +8,21 @@ For more details, see the link:{securing_apps_token_exchange_link}#_standard-tok
 
 For information on how to upgrade from the legacy token exchange used in previous {project_name} versions, see the link:{upgradingguide_link}[{upgradingguide_name}].
 
+= Fine-grained admin permissions supported
+
+This release introduces support for a new version of fine-grained admin permissions. Version 2 (V2) provides enhanced flexibility and control over administrative access within realms. 
+With this feature, administrators can define permissions for administering users, groups, clients, and roles without relying on broad administrative roles. V2 offers the same level of access control over realm resources as the previous version, with plans to extend its capabilities in future versions. Some key points follow:
+
+* *Centralized Admin Console Management* - New *Permissions* section was introduced to allow management from a single place without having to navigate to different places in the Admin Console. 
+* *Improved manageability* - Administrators can more easily search and evaluate permissions when building a permission model for realm resources.
+* *Resource-Specific and Global Permissions* – Permissions can be defined for individual resources (such as specific users or groups),  or entire resource types (such as all users or all groups).
+* *Explicit Operation Scoping* – Permissions are now independent, removing hidden dependencies between operations. Administrators must assign each scope explicitly, making it easier to see what is granted without needing prior knowledge of implicit relationships.
+* *Per-Realm Enablement* – Fine-Grained Admin Permissions can be enabled on a per-realm basis, allowing greater control over adoption and configuration.
+
+For more details, see link:{adminguide_finegrained_link}[{adminguide_finegrained_name}].
+
+For more information about migration, see the link:{upgradingguide_link}[{upgradingguide_name}].
+
 = Guides for metrics and Grafana dashboards
 
 In addition to the list of useful metric names link:{observablitycategory_link}[the Observability guides category] now also contains a guide on how to display these metrics in Grafana.

docs/documentation/server_admin/topics.adoc

@@ -57,6 +57,7 @@ include::topics/sso-protocols.adoc[]
 include::topics/admin-console-permissions.adoc[]
 include::topics/admin-console-permissions/master-realm.adoc[]
 include::topics/admin-console-permissions/per-realm.adoc[]
+include::topics/admin-console-permissions/fine-grain-v2.adoc[]
 ifeval::[{project_community}==true]
 include::topics/admin-console-permissions/fine-grain.adoc[]
 endif::[]

docs/documentation/server_admin/topics/admin-console-permissions.adoc

@@ -1,6 +1,6 @@
 [[_admin_permissions]]
 
-== Controlling access to the Admin Console
+== Managing access to realm resources
 
 Each realm created on the {project_name} has a dedicated Admin Console from which that realm can be managed.
 The `master` realm is a special realm that allows admins to manage more than one realm on the system.

docs/documentation/server_admin/topics/admin-console-permissions/fine-grain-v2.adoc

@@ -0,0 +1,362 @@
+[[_fine_grained_permissions]]
+
+=== Fine grained admin permissions V2
+
+With fine-grained admin permissions, you can delegate realm management to other administrators, delegate realm management 
+to other administrators, the realm administrators. Different from the regular Role-Based Access Control Mechanism provided 
+through the Global and Realm specific roles (<<_master_realm_access_control, Master realm access control>>), this feature 
+provides a more fine-grained control over how realm resources can be accessed and managed based on a well-defined set of 
+operations that can be performed on them.
+
+By relying on a Policy-Based Access Control, server administrators can define permissions to realm resources such as users, 
+groups, and clients, using different policy types, or access control methods, so that a realm administrator is limited to 
+access a subset of realm resources and their operations.
+
+Here are some key points to understand about fine-grained admin permissions:
+
+* Fine grained admin permissions are only available within <<_per_realm_admin_permissions, dedicated admin consoles>> or 
+  realm-specific admin APIs and administrators defined within those realms. You cannot define cross-realm fine grained permissions.
+* Fine grained admin permissions are used to grant additional permissions. You cannot override the default behavior of the 
+  built-in admin roles.
+* Fine-grained admin permissions V2 do not support federated resources. This restriction is a known limitation under consideration 
+  for future improvement.
+
+[NOTE]
+====
+To maximize the effectiveness of fine-grained admin permissions while minimizing the impact of broad admin roles, 
+it is recommended to assign the *query-clients*, *query-groups*, and *query-users* roles (along with roles required
+for realm management) to allow querying. All other administrative access could be managed through fine-grained permissions.
+See <<_realm_access_control, Accessing a Realm Admin Console as a Realm Administrator>> for more information.
+====
+
+==== Understanding the Realm Resource Types
+
+In a realm, you can manage different types of resources such as users, groups, clients, client scopes, roles, and so on. 
+As a realm administrator, you are constantly managing these resources to manage your identities and how they authenticate 
+and authorize to a realm and your applications.
+
+Each realm resource supports a well-defined set of management operations, or actions, that can be performed on them, 
+such as view, manage, and resource-specific operations such as view-members if you take groups as an example.
+
+This feature provides the necessary mechanisms to enforce access to a well-defined set of realm resources, limited to:
+
+* Users
+* Groups
+* Clients
+* Roles
+
+When managing permissions for a specific realm resource type, you can choose to do it for all resources of a given resource 
+type, such as users, or for a specific realm resource, such as a specific user or set of users in the realm.
+
+===== Users Resource Type
+
+The *Users* realm resource type represents the users in a realm. You can manage permissions for users based on the following 
+set of management operations:
+
+[cols="30%,70%"]
+|===
+| *Operation*                | *Description*
+
+| *view*                    | Defines if a realm administrator can view users.
+| *manage*                  | Defines if a realm administrator can manage users.
+| *manage-group-membership* | Defines if a realm administrator can assign or anassign users into groups.
+| *map-roles*               | Defines if a realm administrator can assign or anassign roles to users.
+| *impersonate*             | Defines if a realm administrator can impersonate other users.
+|===
+
+[NOTE]
+====
+- An administrator must have explicit permission assigned for each operation to perform the corresponding action. For example, 
+  assigning only *manage* without *view* will prevent the user from being visible.  
+- The *view* operation also considers group-related permissions, specifically *view-members* for viewing group members. 
+  The evaluation takes permissions for specific resources (specific user permissions and specific group permissions) first. 
+  See <<_resolving-conflicting-permissions, Resolving Conflicting Permissions>> for more information.
+- Similarly, the *manage* operation takes *manage-members* into account when managing group members.  
+====
+
+===== Groups Resource Type
+
+The *Groups* realm resource type represents the groups in a realm. You can manage permissions for groups based on the following 
+set of management operations:
+
+[cols="30%,70%"]
+|===
+| *Operation*                | *Description*
+
+| *view*                    | Defines if a realm administrator can view groups.
+| *manage*                  | Defines if a realm administrator can manage groups.
+| *view-members*            | Defines if a realm administrator can view group members. 
+| *manage-members*          | Defines if a realm administrator can manage group members.
+| *manage-membership*       | Defines if a realm administrator can add or remove members from groups.
+|===
+
+[NOTE]
+====
+- An administrator must have explicit permission assigned for each operation to perform the corresponding action. For example, 
+  assigning only *manage* without *view* will prevent the group from being visible.  
+- The *view-members* and *manage-members* operations apply to the entire group hierarchy. In other words, if an administrator has 
+  permission to manage members of a group, they can also manage members of all its subgroups. This can be prevented by 
+  explicitly denying permission for specific subgroups.
+====
+
+===== Clients Resource Type
+
+The *Clients* realm resource type represents the clients in a realm. You can manage permissions for clients based on the following 
+set of management operations:
+
+[cols="30%,70%"]
+|===
+| *Operation*                | *Description*
+
+| *view*                    | Defines if a realm administrator can view clients.
+| *manage*                  | Defines if a realm administrator can manage clients. It allows operations, such as update certificates, manage 
+                              protocol-mappers or client scopes, regenerate access token.
+| *configure*               | Defines if a realm administrator can manage clients.
+| *map-roles*               | Defines if a realm administrator can assign any role defined by a client (or multiple clients) to a user.
+| *map-roles-composite*     | Defines if a realm administrator can assign any role defined by a client (or multiple clients) as a composite to 
+                              another role.
+| *map-roles-client-scope*  | Defines if a realm administrator can assign any role defined by a client (or multiple clients) to the scope of 
+                              another client.
+|===
+
+[NOTE]
+====
+- An administrator must have explicit permission assigned for each operation to perform the corresponding action. For example, 
+  assigning only *manage* without *view* will prevent the client from being visible.
+- The *map-roles* operation does not grant the ability to manage users or assign roles arbitrarily; the administrator must also 
+  have user role mapping permissions.
+- For certain operations like updating or deleting clients it is required both *manage* and *configure* assigned.
+====
+
+===== Roles Resource Type
+
+The *Roles* realm resource type represents the roles in a realm. You can manage permissions for roles based on the following set of management operations:
+
+[cols="30%,70%"]
+|===
+| *Operation*               | *Description*
+
+| *map-role*               | Defines if a realm administrator can assign a role (or multiple roles) to a user.
+| *map-role-composite*     | Defines if a realm administrator can assign a role (or multiple roles) as a composite to another role. 
+| *map-role-client-scope*  | Defines if a realm administrator can apply a role (or multiple roles) to an another client’s scope.
+|===
+
+[NOTE]
+====
+* The *map-role* operation does not grant the ability to manage users or assign roles arbitrarily; the administrator must also have 
+  user role mapping permissions.  
+* When mapping client roles, if an administrator has permission to *map-roles*, *map-roles-composite*, or *map-roles-client-scope* for 
+  a client, permissions for specific roles within that client are not evaluated.
+====
+
+==== Enabling admin permissions to a realm
+
+To enable fine-grained admin permissions in a realm, follow these steps:
+
+* Log in to the Admin Console.
+* Click *Realm settings*.
+* Enable *Admin Permissions* and click *Save*.
+
+image:images/fine-grain-enable.png[Fine grain enable]
+
+Once enabled, a *Permissions* section appears in the left-side menu of the administration console.
+
+image:images/fine-grain-permissions-tab.png[Fine grain permissions tab]
+
+==== Managing Permissions
+
+The *Permissions* tab provides an overview of all active permissions within a realm. From here, administrators can create, 
+update, delete, or search for permissions.
+
+The *Policies* tab allows administrators to define conditions using different access control methods (*policy type*) to determine whether 
+a permission should be granted to an administrator attempting to access a specific resource performing some operation. It also 
+supports basic searching capability, based on policy `name` and its `type`. Fine-grained admin permissions were implemented on top of 
+Authorization services. Read more about link:{authorizationguide_link}#_policy_overview[Managing policies] in the Authorization services 
+documentation. 
+
+===== Defining permissions for viewing realm resources
+
+IMPORTANT: When listing or searching for realm resources (such as clients, groups, or users) via the Admin Console or Admin API, {project_name} 
+evaluates permissions that contain the *view* scope for the specific resource. For this operation, only role, user, and group policy types are 
+considered, while other policy types are ignored due to partial evaluation performed at the database level. Because of this, only policies that 
+reference the resource directly—whether through user association, group membership, or role assignment—are found and permissions assiciated with 
+those are used for evaluation.
+
+When checking whether an admin can view a specific user, all policy types are taken into account.
+
+The partial evaluation mechanism helps identify and load relevant permissions from the database by using the resource 
+identifiers that the realm administrator has permission to "view". These identifiers are then applied in the subsequent 
+database query to fetch the actual stream of resources. Partial evaluation is supported for non-federated resources, which 
+is a limitation of the current implementation.
+
+===== Searching Permissions
+
+The Admin Console provides several ways to search for permissions, supporting the following capabilities:
+
+* Search for permissions that contain a specific string in their *Name*
+* Search for permissions of a specific resource type, such as *Users*
+* Search for permissions of a specific resource type that apply to a particular resource (such as *Users* resource type for user `myadmin`).
+* Search for permissions of a specific resource type with a given scope (such as *Users* resource type permissions with the *manage* scope).
+* Search for permissions of a specific resource type that apply to a particular resource and have a specific scope (such as *Users* resource 
+  type permissions with the *manage* scope for user `myadmin`).
+
+image:images/fine-grain-search.png[Fine grained permissions search]
+
+==== Evaluating Permissions
+
+The *Evaluation* tab provides a testing environment where administrators can verify that permissions are correctly enforcing access 
+control as expected.
+
+The administrator could see what permissions were involved in evaluation and what the outcome is by specifying a `username` of a user they 
+want to verify, *Resource type*, resource (usermane of a *User* in this case) and optionally an authorization scope.
+
+image:images/fine-grain-evaluation.png[Fine grained permissions evaluation tab]
+
+In the example above it is visible that the user `myadmin`, can *manage* user `user-1`. There is also information what permissions were involved 
+in the evaluation, what outcome it had and what scopes were granted or denied.
+
+[[_resolving-conflicting-permissions]]
+===== Resolving conflicting permissions
+
+Permissions can have multiple policies associated with them. As the authorization model evolves, it is common for some policies within a permission or 
+even different permissions related to a specific resource to conflict.
+
+The evaluation outcome will be "denied" whenever any permission is evaluated to "DENY." If there are multiple permissions related to the same resource, 
+all of them must grant access in order for the outcome to be "granted."
+
+IMPORTANT: Fine-grained admin permissions allow you to set up permissions for individual resources or for the resource type itself (such as all users, 
+all groups, and so on.). If a permission or permissions related to a specific resource exist, the "all-resource" permission is *NOT* taken into account 
+during evaluation. If no specific permission exists, the fallback is to the "all-resource" permission. This approach helps address scenarios like 
+allowing members of the `realm-admins` group to manage members of realm groups, but preventing them from managing members of the `realm-admins` group 
+themselves.
+
+*View and Manage users and group members*
+
+When evaluating *view* or *manage* permissions for users the group *view-members* and *manage-members* permissions are taken into an account.
+The evaluation follows:
+
+* Specific user/group permissions take precedence over broader all-resource permissions.
+* If multiple permissions apply to a given user or group (such as multiple user-specific permissions, or a permission covering a set of 
+  users/groups where the user is member of), all of them are evaluated, and all of them must grant access for the outcome to be GRANTED.
+* If no user/group-specific permissions exist, the evaluation falls back to all-resource permissions ("all-users", "all-groups").
+* When both all-users and all-groups permissions exist, both must grant access for the outcome to be GRANTED.
+* If only one of them exists, the outcome is determined by that permission alone.
+
+[[_realm_access_control]]
+==== Accessing a Realm Admin Console as a Realm Administrator
+
+Realm administrators can access a dedicated realm-specific Admin Console, which allows them to manage resources within their assigned realm. 
+This is separate from the main Keycloak Admin Console, which is typically used by server administrators.
+
+For more details on dedicated realm admin consoles and available roles, refer to: <<_per_realm_admin_permissions, Dedicated admin consoles>>.
+
+To access the Admin Console, a realm administrator must have at least one of the following roles assigned, depending on the resources they 
+need to administer:
+
+- *query-users* – Required to query realm users.  
+- *query-groups* – Required to query realm groups.  
+- *query-clients* – Required to query realm clients.  
+
+If an administrator is responsible for multiple resource types (such as both users and groups), they must have all corresponding "query-*" 
+roles assigned.
+
+These roles enable basic access to query resources but do not grant permission to view or modify them. To configure more fine-grained 
+administrative access, additional permissions must be granted using fine-grained admin permissions.
+
+===== Granting Administrative Roles to a Realm Administrator
+
+A realm administrator’s access must be configured by someone with permission to assign administrative roles. At a minimum, the administrator 
+must have:  
+
+- The appropriate "query-*" roles, depending on the resource types they need to administer.
+
+Beyond these foundational roles, *fine-grained admin permissions* can be used to define specific administrative capabilities. While fine-grained 
+permissions allow for more granular control over access, they cannot override the default behavior of built-in admin roles.
+This means that if an respective admin role is assigned to a realm administrator, permission evaluation will be bypassed, and access will be 
+granted. 
+
+====== Roles and Permission relationship
+
+Fine grained permissions are used to grant additional permissions. You cannot override the default behavior of the built-in admin roles.
+If a realm admin is assigned one or more admin roles, it prevents the permissions from being evaluated.
+
+[cols="30%,70%"]
+|===
+| *Admin Role*              | *Description*
+
+| *query-users*            | A realm administrator can see the *Users* section in Admin Console and can search for users in the realm. 
+                             It does not grant the ability to *view* users.
+| *query-groups*           | A realm administrator can see the *Groups* section in Admin Console and can search for groups in the realm. 
+                             It does not grant the ability to *view* groups.
+| *query-clients*          | A realm administrator can see the *Clients* section in Admin Console and can search for clients in the realm. 
+                             It does not grant the ability to *view* clients.
+| *view-users*             | A realm administrator can *view* all users and groups in the realm.
+| *manage-users*           | A realm administrator can *view*, *map-roles*, *manage-group-membership* and *manage* all users in the realm, 
+                             as well as *view*, *manage-membership* and *manage* groups in the realm.
+| *impersonation*          | A realm administrator can *impersonate* all users in the realm.
+| *view-clients*           | A realm administrator can *view* all clients in the realm.
+| *manage-clients*         | A realm administrator can *view* and *manage* all clients and client scopes in the realm.
+|===
+
+==== Understanding some common use cases
+
+Consider a situation where an administrator wants to allow a group of administrators to manage all users in the realm except those that 
+belong to the administrators group. This example includes a `test` realm and a `test-admins` group.
+
+===== Allow manage users by group of administrators
+
+Create user permission permission, allowing to view and manage all users in the realm for members of the `test-admins` group:
+
+* Navigate to the *Permissions* tab in the Admin Console.
+* Click *Create permission* and choose *Users* resource type.
+* Fill in the name, such as `Disallow managing test-admins`.
+* Choose *view* and *manage* authorization scopes, keep checked *All Users*.
+* Create a condition, which needs to be met to get an access by clicking *Create new policy*.
+* Fill in the name `Allow test-admins`, select *Group* as *Policy type*.
+* Click *Add groups* button and select `test-admins` group, click *Save*.
+* Click *Save* on *Create permission* page.
+
+===== Allow manage users by group of admins but not group members
+
+Let's exlude the members of the group itself, so that `test-admins` cannot manage other admins.
+
+* Create new permission by clicking *Create permission*.
+* This time choose *Groups* resource type.
+* Fill in the name, such as `Disallow managing test-admins`.
+* Choose *manage-members* authorization scope.
+* Select *Specific Groups* and choose `test-admins` group.
+* *Create new policy* of type *Group*.
+* Fill the name `Disallow test-admins` and select `test-admins` group.
+* Switch to *Negative Logic* for the policy, *Save* the policy
+* *Save* the permission
+
+=====  Allow impersonation of users for members of admin group with specific role assigned
+
+- Create a "User Permission" for specific users (or all users) you want to allow impersonation.
+- Create a "Group Policy" allowing access to members of `test-admins`.
+- Create a "Role Policy" allowing access to users assigned the `impersonation-admin` role.
+- Assign both policies to the permission.
+
+===== Blacklist specific users from being impersonated
+
+- Create a *User Permission* for the specific users you want to prevent from being impersonated.
+- Create any policy that evaluates to deny (such as a user policy with no users selected).
+- Assign the policy to the permission to effectively block impersonation for the selected users.
+
+===== Allow viewing users but not managing them for admins with defined role assigned
+
+- Create a "User Permission" with the *view* scope for all users.
+- Create a "Role Policy" allowing access to users with specific role assigned.
+- Do _not_ assign the `manage` scope to prevent modification of user details.
+
+===== Allow managing users and role assignment for members of a group
+
+- Create a "User Permission" with the *manage*, *map-roles* scopes for all users.
+- Create a "Group Policy" allowing access to members of `test-admins`.
+
+===== Allow viewing and managing members of a group but not members of its subgroups
+
+- Create a "Group Permission" with the *view-members* and *manage-members* scopes for specific group `mygroup`.
+- Assign a "Group Policy" targeting `test-admins` to it.
+- Create another "Group Permission" with the *view-members* and *manage-members* scopes for specific group, select all subgroups of the `mygroup`.
+- Create negative "Group Policy" for `test-admins` and assign it to the "subgroups" permission.

docs/documentation/server_admin/topics/admin-console-permissions/fine-grain.adoc

@@ -1,10 +1,9 @@
-[[_fine_grain_permissions]]
 
-=== Fine grain admin permissions
+=== Fine grained admin permissions V1
 
-:tech_feature_name: Fine Grain Admin Permissions
-:tech_feature_id: admin-fine-grained-authz
-include::../templates/techpreview.adoc[]
+IMPORTANT: fine-grained admin permissions V1 have been replaced by a <<_fine_grained_permissions, new version>>. 
+Version 1 of the feature is still marked as preview and is available, but it may be deprecated and removed 
+in future. To enable it, start the server with `--features=admin-fine-grained-authz:v1`.
 
 Sometimes roles like `manage-realm` or `manage-users` are too coarse grain and you want to create
 restricted admin accounts that have more fine grain permissions.  {project_name} allows you to define
@@ -298,4 +297,3 @@ manage-membership::
     Policies that decide if an admin can change the membership of the group.  Add or
     remove members from the group.
 
-

docs/documentation/server_admin/topics/admin-console-permissions/master-realm.adoc

@@ -1,9 +1,10 @@
+[[_master_realm_access_control]]
 
 === Master realm access control
 
 The `master` realm in {project_name} is a special realm and treated differently than other realms.
 Users in the {project_name} `master` realm can be granted permission to manage zero or more realms that are deployed on the {project_name} server.
-When a realm is created, {project_name} automatically creates various roles that grant fine-grain permissions to access that new realm.
+When a realm is created, {project_name} automatically creates various roles that grant permissions to access that new realm.
 Access to The Admin Console and Admin REST endpoints can be controlled by mapping these roles to users in the `master` realm.
 It's possible to create multiple superusers,  as well as users that can only manage specific realms.
 
@@ -27,18 +28,24 @@ level of access to manage an individual realm.
 
 The roles available are: 
 
-* view-realm
-* view-users
-* view-clients
-* view-events
+* create-client
+* impersonation
+* manage-authorization
+* manage-clients
+* manage-events
+* manage-identity-providers
 * manage-realm
 * manage-users
-* create-client
-* manage-clients
-* manage-events            
+* query-clients
+* query-groups
+* query-realms
+* query-users
+* view-authorization
+* view-clients
+* view-events
 * view-identity-providers
-* manage-identity-providers
-* impersonation
+* view-realm
+* view-users
 
 Assign the roles you want to your users and they will only be able to use that specific part of the administration console.
 

docs/documentation/server_admin/topics/admin-console-permissions/per-realm.adoc

@@ -8,18 +8,25 @@ Users within that realm can be granted realm management permissions by assigning
 Each realm has a built-in client called `realm-management`.  You can view this client by going to the
 `Clients` left menu item of your realm.  This client defines client-level roles that specify permissions that can be granted to manage the realm.
 
-* view-realm
-* view-users
-* view-clients
-* view-events
-* manage-realm
-* manage-users
 * create-client
+* impersonation
+* manage-authorization
 * manage-clients
 * manage-events
-* view-identity-providers
 * manage-identity-providers
-* impersonation
+* manage-realm
+* manage-users
+* query-clients
+* query-groups
+* query-realms
+* query-users
+* realm-admin
+* view-authorization
+* view-clients
+* view-events
+* view-identity-providers
+* view-realm
+* view-users
 
 Assign the roles you want to your users and they will only be able to use that specific part of the administration console.
 

docs/documentation/server_admin/topics/clients/oidc/con-advanced-settings.adoc

@@ -4,7 +4,7 @@
 
 After completing the fields on the *Settings* tab, you can use the other tabs to perform advanced configuration.
 ifeval::[{project_community}==true]
-For example, you can use the *Permissions* and *Roles* tabs to configure fine-grained authentication for administrators. See <<_fine_grain_permissions, Fine grain admin permissions>>.  Also, see the remaining sections in this chapter for other capabilities.
+For example, you can use the *Roles* or *Client scopes* tabs to configure client roles defined for the client or manage client scopes for the client. Also, see the remaining sections in this chapter for other capabilities.
 endif::[]
 
 == Advanced tab

docs/documentation/topics/templates/document-attributes.adoc

@@ -48,6 +48,8 @@
 :adminguide_bruteforce_link: {adminguide_link}#password-guess-brute-force-attacks
 :adminguide_eventlistener_name: Event listener
 :adminguide_eventlistener_link: {adminguide_link}#event-listener
+:adminguide_finegrained_name: fine-grained admin permissions
+:adminguide_finegrained_link: {adminguide_link}#_fine_grained_permissions
 :adminguide_timeouts_name: Timeouts
 :adminguide_timeouts_link: {adminguide_link}#_timeouts
 :adminguide_clearcache_name: Clearing Server Caches

docs/documentation/upgrading/topics/changes/changes-26_2_0.adoc

@@ -89,6 +89,42 @@ the https://datatracker.ietf.org/doc/html/rfc6749#section-6[OAuth2 specification
 Currently, it is not supported to request offline tokens or exchange a refresh token when the subject token was issued from an offline session. The recommended approach is to exchange for access tokens instead of
 refresh token when possible.
 
+=== Fine-grained admin permissions supported
+
+Starting with this release, {project_name} introduces *fine-grained admin permissions V2*, offering an improved and more flexible authorization model for administrative permissions.
+
+* FGAP:V2 feature is enabled by default.
+* FGAP:V1 feature remains in preview and can be enabled using `--features=admin-fine-grained-authz:v1`. However, V1 may be deprecated and removed in a future releases.
+
+==== Migration from V1 to V2
+
+Due to fundamental changes in the permission model, **automatic migration from V1 to V2 is not available**. To simplify the transition:
+
+* A new `admin-permissions` client is introduced. This client is created when you enable the capability for the realm. The client holds the authorization model for FGAP:V2.
+* The existing FGAP:V1 authorization model remains unchanged within the `realm-management` client.
+* Administrators must _recreate permissions and policies_ using the new model, which can be configured in the updated *Permissions* section of the Admin Console.
+
+==== Key Differences Between FGAP:V1 and FGAP:V2
+
+* Realm-level enablement: 
+  ** FGAP:V2 can be enabled for a realm using the new *Admin Permissions* switch in *Realm Settings*.
+* Centralized management:
+  ** The resource-specific *Permissions* tabs (for users, groups, clients, and roles) have been removed.
+  ** A new *Permissions* section provides centralized management for all administrative permissions from a single place in the Admin Console.
+* Explicit operation scoping:
+  ** Transitive dependencies between permissions have been removed.
+  ** Administrators must now explicitly assign each required permission.
+  ** Example: To both view and manage a resource, both *view* and *manage* scopes for a permissions must be assigned separately.
+* Permission model changes:
+  ** The *user-impersonated* user permission has been _removed_.
+* Flexible resource scoping:
+  ** Unlike V1, where permissions were granted either to *a single resource* (for clients, groups, and roles) or *all resources* (for users), V2 introduces greater flexibility.
+  ** Administrators can now define permissions for:
+    *** A *specific resource*
+    *** A *set of selected resources*
+    *** *All resources* of a given type
+    *** This applies to *all resource types*: clients, users,groups, and roles.
+
 === LDAP provider now can store new users, groups, and roles in a sub-DN of the base DN
 
 When adding new users, groups, or roles, the LDAP provider would always store them in the same base DN configured for the searches. However, in some deployments admins may want to configure a broader DN with `subtree` scope to fetch users (or groups/roles) from multiple sub-DNs, but they don't want new users (or groups/roles) to be stored in this base DN in LDAP. Instead, they would like to chose one of the sub-DNs for that.