Authorize using member roles

Xperience by Kentico integrates with ASP.NET Identity role management to provide member role functionality. Member roles allow you to categorize registered members and restrict access to pages and content items, assign benefits, or run any custom logic based on role membership.

Roles are represented by the ApplicationRole class, which maps to the MemberRoleInfo object in the Xperience database. The system supports creating, assigning, and querying roles through standard ASP.NET Identity APIs. See Manage member roles for details on role CRUD operations.

Enable member role management

To use member roles, register the role store and role manager when configuring ASP.NET Identity in Program.cs:

                     // Adds and configures ASP.NET Identity for the application
                     builder.Services.AddIdentity<ApplicationUser, ApplicationRole>(options =>
                     {
                     })
                         .AddUserStore<ApplicationUserStore<ApplicationUser>>()
                         .AddRoleStore<ApplicationRoleStore<ApplicationRole>>()
                         .AddUserManager<UserManager<ApplicationUser>>()
                         .AddRoleManager<RoleManager<ApplicationRole>>()
                         .AddSignInManager<SignInManager<ApplicationUser>>();

The key additions for member role management are:

• ApplicationRole – the Xperience implementation of the IdentityRole type, representing a member role with basic properties.
• ApplicationRoleStore – the Xperience role store that persists role data to the CMS_MemberRole database table.
• RoleManager – the standard ASP.NET Identity role manager for CRUD operations on roles.

For more details on the overall Identity configuration, see Registration and authentication.

Manage member roles

You can manage member roles using either the ASP.NET Identity RoleManager or the Xperience IInfoProvider<MemberRoleInfo> API.

Manage member roles with RoleManager

Use RoleManager for standard Identity-based role operations:

                             // Creates a new role
                             ApplicationRole role = new ApplicationRole
                             {
                                 Name = "Premium",
                                 DisplayName = "Premium Member",
                                 Description = "Members with premium access"
                             };
                             IdentityResult createResult = await roleManager.CreateAsync(role);
                     
                             // Finds a role by name
                             ApplicationRole? foundRole = await roleManager.FindByNameAsync("Premium");
                     
                             if (foundRole != null)
                             {
                                 // Updates the role
                                 foundRole.Description = "Updated premium member description";
                                 IdentityResult updateResult = await roleManager.UpdateAsync(foundRole);
                     
                                 // Deletes the role
                                 IdentityResult deleteResult = await roleManager.DeleteAsync(foundRole);
                             }

Manage member roles with IInfoProvider

For more direct database-level access, use IInfoProvider<MemberRoleInfo>:

                             // Creates a new role
                             MemberRoleInfo roleInfo = new MemberRoleInfo
                             {
                                 MemberRoleName = "Premium",
                                 MemberRoleDisplayName = "Premium Member",
                                 MemberRoleDescription = "Members with premium access"
                             };
                             memberRoleProvider.Set(roleInfo);
                     
                             // Retrieves a role by code name
                             MemberRoleInfo? retrievedRole = memberRoleProvider.Get("Premium");
                     
                             // Retrieves all roles
                             IEnumerable<MemberRoleInfo> allRoles = memberRoleProvider.Get()
                                 .GetEnumerableTypedResult();
                     
                             // Deletes a role
                             if (retrievedRole != null)
                             {
                                 memberRoleProvider.Delete(retrievedRole);
                             }

You can also manage member roles in the administration on the List of membership roles page of the Members application. For the administration workflow, see Manage roles.

Assign member roles to members

Use UserManager methods to assign and manage role membership:

                             // Assigns the "Premium" role to the member
                             IdentityResult addResult = await userManager.AddToRoleAsync(user, "Premium");
                     
                             // Gets all roles assigned to the member
                             IList<string> roles = await userManager.GetRolesAsync(user);
                     
                             // Checks if the member has a specific role
                             bool isPremium = await userManager.IsInRoleAsync(user, "Premium");
                     
                             // Removes the "Premium" role from the member
                             IdentityResult removeResult = await userManager.RemoveFromRoleAsync(user, "Premium");

Role assignments are stored as binding objects (MemberRoleMemberInfo) in the CMS_MemberRoleMember database table.

If you need role assignments to expire automatically – for example, trial memberships or subscription tiers – see Expire member role assignments.

Extend ApplicationRole

You can extend ApplicationRole with custom properties. The default role object provides Name, DisplayName, and Description fields. However, this may not be sufficient for scenarios that need to store additional role metadata.

When adding new fields:

1. Add the new fields to the MemberRoleInfo object
2. Modify ApplicationRole to account for the added fields
3. Configure ASP.NET Identity to work with the modified ApplicationRole
4. Display the added fields in the Members application

Add the new fields to the MemberRoleInfo object

The first step is to define new fields for CMS.Membership.MemberRoleInfo. The class is connected to Xperience’s ORM framework and its API is used when saving roles to the database. Extending the object adds new columns to the CMS_MemberRole database table, where the additional data will be stored.

1. In the admin UI, open the Modules application.
2. Select the Membership module.
3. Switch to the Classes tab.
4. Select the Member role class.
5. Switch to the Database columns tab.
6. Create new fields based on your requirements using the field editor.

You have added custom fields to the member role object. For more information about the ORM framework in Xperience, see: Database table API, Object types, Extend system object types

Modify the ApplicationRole class

The added fields now need to be reflected in ApplicationRole to make them available for use within ASP.NET Identity APIs.

1. In your project, create a new class that inherits from Kentico.Membership.ApplicationRole.
2. In the class, declare properties corresponding to the object type fields added via the Modules application.
3. Override the MapFromMemberRoleInfo and MapToMemberRoleInfo methods and:
   1. Call the base implementation of each method. This ensures the default mapping.
   2. Get and set values of the custom properties you wish to have available using MemberRoleInfo.GetValue and MemberRoleInfo.SetValue.

                     // Extends the default Kentico.Membership.ApplicationRole object
                     public class ExtendedApplicationRole : ApplicationRole
                     {
                         // Custom property that corresponds to a custom field added to MemberRoleInfo
                         public int MaxDownloads { get; set; }
                     
                         // Maps data from MemberRoleInfo to the extended role object
                         // Called when retrieving roles via RoleManager<ExtendedApplicationRole>
                         public override void MapFromMemberRoleInfo(MemberRoleInfo source)
                         {
                             // Calls the base class implementation
                             base.MapFromMemberRoleInfo(source);
                     
                             // Maps the custom 'MaxDownloads' property
                             MaxDownloads = source.GetValue("MemberRoleMaxDownloads", 0);
                         }
                     
                         // Maps data from the extended role object back to MemberRoleInfo
                         // Called when creating or updating roles via RoleManager<ExtendedApplicationRole>
                         public override void MapToMemberRoleInfo(MemberRoleInfo target)
                         {
                             // Calls the base class implementation
                             base.MapToMemberRoleInfo(target);
                     
                             // Sets the value of the custom field in MemberRoleInfo
                             target.SetValue("MemberRoleMaxDownloads", MaxDownloads);
                         }
                     }

The extended class is now ready. The main benefit of this approach is that it enables you to work with the added custom fields using strongly-typed properties.

Configure ASP.NET Identity to work with the modified ApplicationRole

In your application’s startup file (Program.cs by default), edit the Identity configuration. Substitute ApplicationRole with the extended class (ExtendedApplicationRole in this example):

builder.Services.AddIdentity<ApplicationUser, ExtendedApplicationRole>(options =>
{
    // ...
})
    .AddUserStore<ApplicationUserStore<ApplicationUser>>()
    .AddRoleStore<ApplicationRoleStore<ExtendedApplicationRole>>()
    .AddUserManager<UserManager<ApplicationUser>>()
    .AddRoleManager<RoleManager<ExtendedApplicationRole>>()
    .AddSignInManager<SignInManager<ApplicationUser>>();

Display added fields in the Members application

To display the fields added to the Member role object type in the Members application, add them to the object type’s Edit UI form:

1. Open the Modules application and navigate to Membership → Classes → Member Role → UI forms.
2. Select the Edit UI form.
3. Select New field. The Database column selector opens.
   • Use the selector to choose from among the columns added to the Member Role class. Data submitted via the created form field is persisted in the selected column.
4. Add the new columns to the form using the field editor.

The added columns now show in the modified UI form when viewing role details in the Members application under List of membership roles.

Additionally, to display the added fields in the role listing, write an extender for the MemberRoleList listing UI page:

                     public class MemberRoleListExtender : PageExtender<MemberRoleList>
                     {
                         public override Task ConfigurePage()
                         {
                             base.ConfigurePage();
                     
                             // Displays a custom column in the role listing
                             Page.PageConfiguration.ColumnConfigurations
                                 .AddColumn("CustomRoleField");
                     
                             return Task.CompletedTask;
                         }
                     }

Authorize with member roles

For pages and content items, use the built-in Membership access settings in the Xperience administration. Use the standard ASP.NET [Authorize] attribute with the Roles parameter when you need to restrict access to custom controllers or actions based on member roles:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

// Only members with the "Premium" role can access this controller
[Authorize(Roles = "Premium")]
public class PremiumContentController : Controller
{
    public IActionResult Index()
    {
        return View();
    }
}

For more advanced authorization scenarios, see ASP.NET Core role-based authorization and Secure custom endpoints.

Integrate custom authorization logic

Xperience’s built-in content security pipeline – the HasAccess method, ContentItemIsSecured property, and the secured-item filtering in ContentRetriever – evaluates only the built-in access model: public content, content that requires authentication, and content restricted to specific member roles. The pipeline does not expose extension points for injecting additional authorization rules.

If your application requires authorization logic beyond the built-in model, apply those checks after Xperience’s content security evaluation resolves. In practice this means working at the controller or business-service layer:

1. Retrieve content and let the built-in pipeline handle the standard access evaluation (e.g., via HasAccess).
2. Apply your own authorization rules on the already-evaluated results.

For details on how security affects content retrieval, see page security configuration and content item security.

Remarks

ApplicationRole and ApplicationRoleStore

ApplicationRole maps to CMS.Membership.MemberRoleInfo objects stored in the Xperience database. When saving or retrieving role data through ASP.NET Identity’s RoleManager, Xperience transfers data between ApplicationRole and MemberRoleInfo using the MapFromMemberRoleInfo and MapToMemberRoleInfo methods. This lets you expose custom role fields as strongly-typed properties on your extended role class.

ApplicationRoleStore implements IRoleStore and provides the CRUD operations that RoleManager uses to create, update, delete, and look up member roles in the Xperience database.

Changing role assignments for signed-in members

When you add or remove roles for a member who is already signed in, the change is not reflected immediately. The member can continue using the role information stored in their current authentication cookie until the next revalidation event. This means role-based access can remain granted or unavailable for up to 30 minutes by default.

If you need role changes to take effect immediately, configure SecurityStampValidatorOptions as described in Registration and authentication.

Page preview mode

Secured content, including content restricted to specific member roles, is accessible when previewing pages in the administration, through Page Builder, or via shareable preview URLs. Preview mode bypasses member role checks, allowing editors to view content regardless of role assignments. For preview limitations of ASP.NET authorization flows, see MVC authorization flows and preview mode.