Adds support for custom granular permissions when aggregating across user groups (#19660)

* Added abstraction for aggregation of granular permissions to support custom permissions.

* Refactor to move responsibility for aggregating granular permissions to the respective mappers.

* Added XML header comments for permission mappers.

* Tidied up/removed warnings in UserPresentationFactory interface and implementation.

* Optimized retrieval of documents in DocumentPermissionMapper.

* Fixed method header comment.

* Use entity service rather than content service to retrieve key and path.

Author: AndyButland

src/Umbraco.Cms.Api.Management/Factories/IUserPresentationFactory.cs

@@ -6,25 +6,58 @@
 
 namespace Umbraco.Cms.Api.Management.Factories;
 
+/// <summary>
+/// Defines factory methods for the creation of user presentation models.
+/// </summary>
 public interface IUserPresentationFactory
 {
+    /// <summary>
+    /// Creates a response model for the provided user.
+    /// </summary>
     UserResponseModel CreateResponseModel(IUser user);
 
+    /// <summary>
+    /// Creates a create model for a user based on the provided request model.
+    /// </summary>
     Task<UserCreateModel> CreateCreationModelAsync(CreateUserRequestModel requestModel);
 
+    /// <summary>
+    /// Creates an invite model for a user based on the provided request model.
+    /// </summary>
     Task<UserInviteModel> CreateInviteModelAsync(InviteUserRequestModel requestModel);
 
+    /// <summary>
+    /// Creates an update model for an existing user based on the provided request model.
+    /// </summary>
     Task<UserUpdateModel> CreateUpdateModelAsync(Guid existingUserKey, UpdateUserRequestModel updateModel);
 
+    /// <summary>
+    /// Creates a response model for the current user based on the provided user.
+    /// </summary>
     Task<CurrentUserResponseModel> CreateCurrentUserResponseModelAsync(IUser user);
 
+    /// <summary>
+    /// Creates an resend invite model for a user based on the provided request model.
+    /// </summary>
     Task<UserResendInviteModel> CreateResendInviteModelAsync(ResendInviteUserRequestModel requestModel);
 
+    /// <summary>
+    /// Creates a user configuration model that contains the necessary data for user management operations.
+    /// </summary>
     Task<UserConfigurationResponseModel> CreateUserConfigurationModelAsync();
 
+    /// <summary>
+    /// Creates a current user configuration model that contains the necessary data for the current user's management operations.
+    /// </summary>
     Task<CurrentUserConfigurationResponseModel> CreateCurrentUserConfigurationModelAsync();
 
+    /// <summary>
+    /// Creates a user item response model for the provided user.
+    /// </summary>
     UserItemResponseModel CreateItemResponseModel(IUser user);
 
+    /// <summary>
+    /// Creates a calculated user start nodes response model based on the provided user.
+    /// </summary>
     Task<CalculatedUserStartNodesResponseModel> CreateCalculatedUserStartNodesResponseModelAsync(IUser user);
 }

src/Umbraco.Cms.Api.Management/Factories/UserPresentationFactory.cs

@@ -1,5 +1,6 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Options;
+using Umbraco.Cms.Api.Management.Mapping.Permissions;
 using Umbraco.Cms.Api.Management.Routing;
 using Umbraco.Cms.Api.Management.Security;
 using Umbraco.Cms.Api.Management.ViewModels;
@@ -22,6 +23,9 @@
 
 namespace Umbraco.Cms.Api.Management.Factories;
 
+/// <summary>
+/// Factory for creating user presentation models, implementing <see cref="IUserPresentationFactory"/>.
+/// </summary>
 public class UserPresentationFactory : IUserPresentationFactory
 {
     private readonly IEntityService _entityService;
@@ -34,9 +38,11 @@ public class UserPresentationFactory : IUserPresentationFactory
     private readonly IPasswordConfigurationPresentationFactory _passwordConfigurationPresentationFactory;
     private readonly IBackOfficeExternalLoginProviders _externalLoginProviders;
     private readonly SecuritySettings _securitySettings;
-    private readonly IUserService _userService;
-    private readonly IContentService _contentService;
+    private readonly Dictionary<Type, IPermissionPresentationMapper> _permissionPresentationMappersByType;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserPresentationFactory"/> class.
+    /// </summary>
     [Obsolete("Please use the constructor taking all parameters. Scheduled for removal in Umbraco 17.")]
     public UserPresentationFactory(
         IEntityService entityService,
@@ -50,7 +56,7 @@ public UserPresentationFactory(
         IOptionsSnapshot<SecuritySettings> securitySettings,
         IBackOfficeExternalLoginProviders externalLoginProviders)
         : this(
-              entityService,
+            entityService,
             appCaches,
             mediaFileManager,
             imageUrlGenerator,
@@ -61,10 +67,15 @@ public UserPresentationFactory(
             securitySettings,
             externalLoginProviders,
             StaticServiceProvider.Instance.GetRequiredService<IUserService>(),
-            StaticServiceProvider.Instance.GetRequiredService<IContentService>())
+            StaticServiceProvider.Instance.GetRequiredService<IContentService>(),
+            StaticServiceProvider.Instance.GetRequiredService<IEnumerable<IPermissionPresentationMapper>>())
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserPresentationFactory"/> class.
+    /// </summary>
+    [Obsolete("Please use the constructor taking all parameters. Scheduled for removal in Umbraco 17.")]
     public UserPresentationFactory(
         IEntityService entityService,
         AppCaches appCaches,
@@ -78,6 +89,44 @@ public UserPresentationFactory(
         IBackOfficeExternalLoginProviders externalLoginProviders,
         IUserService userService,
         IContentService contentService)
+        : this(
+            entityService,
+            appCaches,
+            mediaFileManager,
+            imageUrlGenerator,
+            userGroupPresentationFactory,
+            absoluteUrlBuilder,
+            emailSender,
+            passwordConfigurationPresentationFactory,
+            securitySettings,
+            externalLoginProviders,
+            userService,
+            contentService,
+            StaticServiceProvider.Instance.GetRequiredService<IEnumerable<IPermissionPresentationMapper>>())
+    {
+    }
+
+    // TODO (V17): Remove the unused userService and contentService parameters from this constructor.
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserPresentationFactory"/> class.
+    /// </summary>
+    public UserPresentationFactory(
+        IEntityService entityService,
+        AppCaches appCaches,
+        MediaFileManager mediaFileManager,
+        IImageUrlGenerator imageUrlGenerator,
+        IUserGroupPresentationFactory userGroupPresentationFactory,
+        IAbsoluteUrlBuilder absoluteUrlBuilder,
+        IEmailSender emailSender,
+        IPasswordConfigurationPresentationFactory passwordConfigurationPresentationFactory,
+        IOptionsSnapshot<SecuritySettings> securitySettings,
+        IBackOfficeExternalLoginProviders externalLoginProviders,
+#pragma warning disable IDE0060 // Remove unused parameter - need to keep these until the next major to avoid breaking changes and/or ambiguous constructor errors
+        IUserService userService,
+        IContentService contentService,
+#pragma warning restore IDE0060 // Remove unused parameter
+        IEnumerable<IPermissionPresentationMapper> permissionPresentationMappers)
     {
         _entityService = entityService;
         _appCaches = appCaches;
@@ -89,10 +138,10 @@ public UserPresentationFactory(
         _externalLoginProviders = externalLoginProviders;
         _securitySettings = securitySettings.Value;
         _absoluteUrlBuilder = absoluteUrlBuilder;
-        _userService = userService;
-        _contentService = contentService;
+        _permissionPresentationMappersByType = permissionPresentationMappers.ToDictionary(x => x.PresentationModelToHandle);
     }
 
+    /// <inheritdoc/>
     public UserResponseModel CreateResponseModel(IUser user)
     {
         var responseModel = new UserResponseModel
@@ -123,16 +172,18 @@ public UserResponseModel CreateResponseModel(IUser user)
         return responseModel;
     }
 
+    /// <inheritdoc/>
     public UserItemResponseModel CreateItemResponseModel(IUser user) =>
         new()
         {
             Id = user.Key,
             Name = user.Name ?? user.Username,
             AvatarUrls = user.GetUserAvatarUrls(_appCaches.RuntimeCache, _mediaFileManager, _imageUrlGenerator)
                 .Select(url => _absoluteUrlBuilder.ToAbsoluteUrl(url).ToString()),
-            Kind = user.Kind
+            Kind = user.Kind,
         };
 
+    /// <inheritdoc/>
     public Task<UserCreateModel> CreateCreationModelAsync(CreateUserRequestModel requestModel)
     {
         var createModel = new UserCreateModel
@@ -142,12 +193,13 @@ public Task<UserCreateModel> CreateCreationModelAsync(CreateUserRequestModel req
             Name = requestModel.Name,
             UserName = requestModel.UserName,
             UserGroupKeys = requestModel.UserGroupIds.Select(x => x.Id).ToHashSet(),
-            Kind = requestModel.Kind
+            Kind = requestModel.Kind,
         };
 
         return Task.FromResult(createModel);
     }
 
+    /// <inheritdoc/>
     public Task<UserInviteModel> CreateInviteModelAsync(InviteUserRequestModel requestModel)
     {
         var inviteModel = new UserInviteModel
@@ -162,6 +214,7 @@ public Task<UserInviteModel> CreateInviteModelAsync(InviteUserRequestModel reque
         return Task.FromResult(inviteModel);
     }
 
+    /// <inheritdoc/>
     public Task<UserResendInviteModel> CreateResendInviteModelAsync(ResendInviteUserRequestModel requestModel)
     {
         var inviteModel = new UserResendInviteModel
@@ -173,6 +226,7 @@ public Task<UserResendInviteModel> CreateResendInviteModelAsync(ResendInviteUser
         return Task.FromResult(inviteModel);
     }
 
+    /// <inheritdoc/>
     public Task<CurrentUserConfigurationResponseModel> CreateCurrentUserConfigurationModelAsync()
     {
         var model = new CurrentUserConfigurationResponseModel
@@ -188,6 +242,7 @@ public Task<CurrentUserConfigurationResponseModel> CreateCurrentUserConfiguratio
         return Task.FromResult(model);
     }
 
+    /// <inheritdoc/>
     public Task<UserConfigurationResponseModel> CreateUserConfigurationModelAsync() =>
         Task.FromResult(new UserConfigurationResponseModel
         {
@@ -201,6 +256,7 @@ public Task<UserConfigurationResponseModel> CreateUserConfigurationModelAsync()
             AllowTwoFactor = _externalLoginProviders.HasDenyLocalLogin() is false,
         });
 
+    /// <inheritdoc/>
     public Task<UserUpdateModel> CreateUpdateModelAsync(Guid existingUserKey, UpdateUserRequestModel updateModel)
     {
         var model = new UserUpdateModel
@@ -214,24 +270,24 @@ public Task<UserUpdateModel> CreateUpdateModelAsync(Guid existingUserKey, Update
             HasContentRootAccess = updateModel.HasDocumentRootAccess,
             MediaStartNodeKeys = updateModel.MediaStartNodeIds.Select(x => x.Id).ToHashSet(),
             HasMediaRootAccess = updateModel.HasMediaRootAccess,
+            UserGroupKeys = updateModel.UserGroupIds.Select(x => x.Id).ToHashSet()
         };
 
-        model.UserGroupKeys = updateModel.UserGroupIds.Select(x => x.Id).ToHashSet();
-
         return Task.FromResult(model);
     }
 
+    /// <inheritdoc/>
     public async Task<CurrentUserResponseModel> CreateCurrentUserResponseModelAsync(IUser user)
     {
-        var presentationUser = CreateResponseModel(user);
-        var presentationGroups = await _userGroupPresentationFactory.CreateMultipleAsync(user.Groups);
+        UserResponseModel presentationUser = CreateResponseModel(user);
+        IEnumerable<UserGroupResponseModel> presentationGroups = await _userGroupPresentationFactory.CreateMultipleAsync(user.Groups);
         var languages = presentationGroups.SelectMany(x => x.Languages).Distinct().ToArray();
         var mediaStartNodeIds = user.CalculateMediaStartNodeIds(_entityService, _appCaches);
-        var mediaStartNodeKeys = GetKeysFromIds(mediaStartNodeIds, UmbracoObjectTypes.Media);
+        ISet<ReferenceByIdModel> mediaStartNodeKeys = GetKeysFromIds(mediaStartNodeIds, UmbracoObjectTypes.Media);
         var contentStartNodeIds = user.CalculateContentStartNodeIds(_entityService, _appCaches);
-        var documentStartNodeKeys = GetKeysFromIds(contentStartNodeIds, UmbracoObjectTypes.Document);
+        ISet<ReferenceByIdModel> documentStartNodeKeys = GetKeysFromIds(contentStartNodeIds, UmbracoObjectTypes.Document);
 
-        var permissions = GetAggregatedGranularPermissions(user, presentationGroups);
+        HashSet<IPermissionPresentationModel> permissions = GetAggregatedGranularPermissions(user, presentationGroups);
         var fallbackPermissions = presentationGroups.SelectMany(x => x.FallbackPermissions).ToHashSet();
 
         var hasAccessToAllLanguages = presentationGroups.Any(x => x.HasAccessToAllLanguages);
@@ -263,70 +319,56 @@ public async Task<CurrentUserResponseModel> CreateCurrentUserResponseModelAsync(
 
     private HashSet<IPermissionPresentationModel> GetAggregatedGranularPermissions(IUser user, IEnumerable<UserGroupResponseModel> presentationGroups)
     {
-        var aggregatedPermissions = new HashSet<IPermissionPresentationModel>();
-
         var permissions = presentationGroups.SelectMany(x => x.Permissions).ToHashSet();
-
-        AggregateAndAddDocumentPermissions(user, aggregatedPermissions, permissions);
-
-        AggregateAndAddDocumentPropertyValuePermissions(aggregatedPermissions, permissions);
-
-        return aggregatedPermissions;
+        return GetAggregatedGranularPermissions(user, permissions);
     }
 
-    private void AggregateAndAddDocumentPermissions(IUser user, HashSet<IPermissionPresentationModel> aggregatedPermissions, HashSet<IPermissionPresentationModel> permissions)
+    private HashSet<IPermissionPresentationModel> GetAggregatedGranularPermissions(IUser user, HashSet<IPermissionPresentationModel> permissions)
     {
-        // The raw permission data consists of several permissions for each document.  We want to aggregate this server-side so
-        // we return one set of aggregate permissions per document that the client will use.
-
-        // Get the unique document keys that have granular permissions.
-        IEnumerable<Guid> documentKeysWithGranularPermissions = permissions
-            .Where(x => x is DocumentPermissionPresentationModel)
-            .Cast<DocumentPermissionPresentationModel>()
-            .Select(x => x.Document.Id)
-            .Distinct();
+        // The raw permission data consists of several permissions for each entity (e.g. document), as permissions are assigned to user groups
+        // and a user may be part of multiple groups.  We want to aggregate this server-side so we return one set of aggregate permissions per
+        // entity that the client will use.
+        // We need to handle here not just permissions known to core (e.g. document and document property value permissions), but also custom
+        // permissions defined by packages or implemetors.
+        IEnumerable<(Type, IEnumerable<IPermissionPresentationModel>)> permissionModelsByType = permissions
+            .GroupBy(x => x.GetType())
+            .Select(x => (x.Key, x.Select(y => y)));
 
-        foreach (Guid documentKey in documentKeysWithGranularPermissions)
+        var aggregatedPermissions = new HashSet<IPermissionPresentationModel>();
+        foreach ((Type Type, IEnumerable<IPermissionPresentationModel> Models) permissionModelByType in permissionModelsByType)
         {
-            // Retrieve the path of the document.
-            var path = _contentService.GetById(documentKey)?.Path;
-            if (string.IsNullOrEmpty(path))
+            if (_permissionPresentationMappersByType.TryGetValue(permissionModelByType.Type, out IPermissionPresentationMapper? mapper))
             {
-                continue;
-            }
 
-            // With the path we can call the same logic as used server-side for authorizing access to resources.
-            EntityPermissionSet permissionsForPath = _userService.GetPermissionsForPath(user, path);
-            aggregatedPermissions.Add(new DocumentPermissionPresentationModel
+                IEnumerable<IPermissionPresentationModel> aggregatedModels = mapper.AggregatePresentationModels(user, permissionModelByType.Models);
+                foreach (IPermissionPresentationModel aggregatedModel in aggregatedModels)
+                {
+                    aggregatedPermissions.Add(aggregatedModel);
+                }
+            }
+            else
             {
-                Document = new ReferenceByIdModel(documentKey),
-                Verbs = permissionsForPath.GetAllPermissions()
-            });
+                IEnumerable<(string Context, ISet<string> Verbs)> groupedModels = permissionModelByType.Models
+                    .Where(x => x is UnknownTypePermissionPresentationModel)
+                    .Cast<UnknownTypePermissionPresentationModel>()
+                    .GroupBy(x => x.Context)
+                    .Select(x => (x.Key, (ISet<string>)x.SelectMany(y => y.Verbs).Distinct().ToHashSet()));
+
+                foreach ((string context, ISet<string> verbs) in groupedModels)
+                {
+                    aggregatedPermissions.Add(new UnknownTypePermissionPresentationModel
+                    {
+                        Context = context,
+                        Verbs = verbs
+                    });
+                }
+            }
         }
-    }
 
-    private static void AggregateAndAddDocumentPropertyValuePermissions(HashSet<IPermissionPresentationModel> aggregatedPermissions, HashSet<IPermissionPresentationModel> permissions)
-    {
-        // We also have permissions for document type/property type combinations.
-        // These don't have an ancestor relationship that we need to take into account, but should be aggregated
-        // and included in the set.
-        IEnumerable<((Guid DocumentTypeId, Guid PropertyTypeId) Key, ISet<string> Verbs)> documentTypePropertyTypeKeysWithGranularPermissions = permissions
-            .Where(x => x is DocumentPropertyValuePermissionPresentationModel)
-            .Cast<DocumentPropertyValuePermissionPresentationModel>()
-            .GroupBy(x => (x.DocumentType.Id, x.PropertyType.Id))
-            .Select(x => (x.Key, (ISet<string>)x.SelectMany(y => y.Verbs).Distinct().ToHashSet()));
-
-        foreach (((Guid DocumentTypeId, Guid PropertyTypeId) Key, ISet<string> Verbs) documentTypePropertyTypeKey in documentTypePropertyTypeKeysWithGranularPermissions)
-        {
-            aggregatedPermissions.Add(new DocumentPropertyValuePermissionPresentationModel
-            {
-                DocumentType = new ReferenceByIdModel(documentTypePropertyTypeKey.Key.DocumentTypeId),
-                PropertyType = new ReferenceByIdModel(documentTypePropertyTypeKey.Key.PropertyTypeId),
-                Verbs = documentTypePropertyTypeKey.Verbs
-            });
-        }
+        return aggregatedPermissions;
     }
 
+    /// <inheritdoc/>
     public Task<CalculatedUserStartNodesResponseModel> CreateCalculatedUserStartNodesResponseModelAsync(IUser user)
     {
         var mediaStartNodeIds = user.CalculateMediaStartNodeIds(_entityService, _appCaches);
@@ -357,6 +399,6 @@ private ISet<ReferenceByIdModel> GetKeysFromIds(IEnumerable<int>? ids, UmbracoOb
             : new HashSet<ReferenceByIdModel>(models);
     }
 
-    private bool HasRootAccess(IEnumerable<int>? startNodeIds)
+    private static bool HasRootAccess(IEnumerable<int>? startNodeIds)
         => startNodeIds?.Contains(Constants.System.Root) is true;
 }