Integrating Xperience membership

Xperience provides an integration API that allows you to work with the system's membership data on websites presented by ASP.NET Core applications. The API is available in the Kentico.Membership namespace, which is provided as part of the Xperience.AspNetCore.WebApp integration package.

The membership integration is based on ASP.NET Core Identity⁠ (opens in a new tab). As a result, you can work with user data through the standard approaches that you would use in any ASP.NET Core application.

1. Open your ASP.NET Core project in Visual Studio.

2. Install the Microsoft.AspNetCore.Identity NuGet package.

3. Modify the startup file of your project (Startup.cs by default).

   • In the ConfigureServices method, add types and services required to work with Xperience Identity:

     C#

     Copy

     using Microsoft.AspNetCore.Identity;
     
     using CMS.Helpers;
     
     using Kentico.Membership;

     C#

     Copy

     private const string AUTHENTICATION_COOKIE_NAME = "identity.authentication";
     
     public void ConfigureServices(IServiceCollection services)
     {
         ...
         // Adds Xperience services required by the system's Identity implementation
         services.AddScoped<IPasswordHasher<ApplicationUser>, Kentico.Membership.PasswordHasher<ApplicationUser>>();
         services.AddScoped<IMessageService, MessageService>();
     
         services.AddApplicationIdentity<ApplicationUser, ApplicationRole>()
                         // Adds token providers used to generate tokens for email confirmations, password resets, etc.
                         .AddApplicationDefaultTokenProviders()
                         // Adds an implementation of the UserStore for working with Xperience user objects
                         .AddUserStore<ApplicationUserStore<ApplicationUser>>()
                         // Adds an implementation of the RoleStore used for working with Xperience roles
                         .AddRoleStore<ApplicationRoleStore<ApplicationRole>>()
                         // Adds an implementation of the UserManager for Xperience membership
                         .AddUserManager<ApplicationUserManager<ApplicationUser>>()
                         // Adds the default implementation of the SignInManger
                         .AddSignInManager<SignInManager<ApplicationUser>>();
     
         // Adds authentication and authorization services provided by the framework
         services.AddAuthentication();
         services.AddAuthorization();
     
         // Configures the application's authentication cookie
         services.ConfigureApplicationCookie(c =>
         {
             c.LoginPath = new PathString("/");
             c.ExpireTimeSpan = TimeSpan.FromDays(14);
             c.SlidingExpiration = true;
             c.Cookie.Name = AUTHENTICATION_COOKIE_NAME;
         });
     
         // Registers the authentication cookie in Xperience with the 'Essential' cookie level
         // Ensures that the cookie is preserved when changing a visitor's allowed cookie level below 'Visitor'
         CookieHelper.RegisterCookie(AUTHENTICATION_COOKIE_NAME, CookieLevel.Essential);
         ...
     }

   • In the Configure method, register the corresponding middleware:

     C#

     Copy

     public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
     {
         ...
         app.UseRouting();
     
         app.UseAuthentication();
         app.UseAuthorization();
         ...
     }

The configuration of the Identity classes provided by Xperience (ApplicationUserManager, ApplicationUserStore, etc.) reflects the Security & Membership and Passwords settings configured via the Settings application in the administration interface. To ensure these settings do not interfere with existing Identity functionality, the system maps certain settings to the Identity configuration⁠ (opens in a new tab).

The following table details the mapping of all Xperience settings to ASP.NET Core Identity configuration options:

When configuring Identity for your application, do not override these options unless you explicitly intend to do so. Otherwise, you effectively remove the ability to configure the corresponding behavior via the administration interface.