UI page permission checks

This page covers how to add permissions to applications and evaluate them within UI pages using the role-based access control model.

Add and evaluate permissions for applications

Define the set of application permissions

Each application in the admin UI needs to declare the set of permissions it actively evaluates. This set is reflected when assigning permissions to roles via the Role management application. Define the permissions by decorating UI application pages with the UIPermission attribute and specifying permission names. The system’s default application permissions (VIEW, CREATE, DELETE, UPDATE) are accessible via the SystemPermissions class.

C#

Add permissions to UI applications



using CMS.Membership;

using Kentico.Xperience.Admin.Base;

// Adds the default application permissions to the 'OfficeManagement' application
[UIPermission(SystemPermissions.VIEW)]
[UIPermission(SystemPermissions.CREATE)]
[UIPermission(SystemPermissions.DELETE)]
[UIPermission(SystemPermissions.UPDATE)]
// Adds a custom permission to the application
// Permission semantics are implementation-dependent
[UIPermission("Acme.HumanResources", "Human resources")]
public class OfficeManagementApplication : ApplicationPage

For applications without any permission requirements, use the UINoPermissionRequired attribute. The attribute ensures global visibility and accessibility to all users, regardless of their roles or permissions.

C#



using CMS.Membership;

using Kentico.Xperience.Admin.Base;

// Ensures global visibility and accessibility to all users, regardless of their roles or permissions 
[UINoPermissionRequired]
public class OfficeManagementApplication : ApplicationPage

Require permissions to access UI pages

To place UI pages behind permissions, use the UIEvaluatePermission attribute. This permission must be from the set defined for the corresponding application using the UIPermission attribute. Otherwise, you would be unable to assign this permission to roles via Role management.

C#

Place UI pages behind permissions



using CMS.Membership;

using Kentico.Xperience.Admin.Base;

// Only roles with the 'Human resources' permission can access this page
[UIEvaluatePermission("Acme.HumanResources")]
public class OpenPositionListing : ListingPage

Permission evaluation in UI page templates

The following UI page templates provided by the API by default contain permission checks:

Listing pages – require VIEW to access.
Create pages – require CREATE to access.

Roles without proper permissions attempting to access such pages receive a forbidden (HTTP 403) response.

Evaluate permissions within page commands

You can configure each page command to evaluate a single permission:

C#

Page command permissions



// Only roles with the 'CREATE' permission can call this command
[PageCommand(Permission = SystemPermissions.CREATE)]
public async Task<ICommandResponse<RowActionResult>> DoSomething()
{
    // Command logic
}

Propagate permission information to client UI templates

You might need to send information about a user’s permissions to the client UI template to, for example, disable certain interactive elements. To check whether the current user has the required permissions, use IUIPermissionEvaluator:

C#

Send permission information to the client



using System.Threading.Tasks;

using Kentico.Xperience.Admin.Base;

public class HrPage : Page<PageClientProperties>
{
    private readonly IUIPermissionEvaluator permissionEvaluator;

    public HrPage(IUIPermissionEvaluator permissionEvaluator)
    {
        this.permissionEvaluator = permissionEvaluator;
    }

    // Sends the required data to the client. 
    // Based on this information, the logic within the template can, e.g., disable interactive elements
    public override async Task<PageClientProperties> ConfigureTemplateProperties(PageClientProperties properties)
    {
        var permissionResult = await permissionEvaluator.Evaluate("Acme.HumanResources");

        properties.HrPermission = permissionResult.Succeeded;

        return properties;
    }
}

public class PageClientProperties : TemplateClientProperties
{
    public bool HrPermission { get; set; }
}

UI permission model and page extenders

If you need to add permissions to system pages or pages provided via third-party integrations where you cannot access the source code, you can do so via UI page extenders:

C#

Permission definition



using Kentico.Xperience.Admin.Base;

// Adds a custom permission to the user listing page in the 'Users' application
[UIPermission("Acme.Permission")]
public class UserListExtender : PageExtender<UserList>

This applies only to application permissions that you can grant to roles via the Role management application. The page permissions of website channel applications cannot be extended.

After annotating the extender class as demonstrated in the example above, you can work with the added permission as if it was assigned directly to the application. The following example defines a new action on the users listing page from the Users application and places it behind the “Acme.Permission” permission.

C#

Permission usage



using Kentico.Xperience.Admin.Base;

[UIPermission("Acme.Permission")]
public class UserListExtender : PageExtender<UserList>
{
    public override Task ConfigurePage()
    {
        ...
        configuration.TableActions
                    .AddCommand("Do something", nameof(DoSomething), Icons.ArrowsCrooked);
        ...
    }

    [PageCommand(Permission = "Acme.Permission")]
    public async Task<ICommandResponse<RowActionResult>> DoSomething()
    {
        // Command logic
    }
}

The added permission is now also assignable via the Role management application.

Role management application