Kentico Xperience 13 documentation and ASP.NET Core

Most documentation about running Xperience applications under ASP.NET Core can be found in a dedicated section: Developing Xperience applications using ASP.NET Core. The rest of the documentation still applies, but some code samples and scenarios might need slight modifications for Core projects.

Certain pages allow you to switch between Core and MVC 5 content using a selector located under the page heading.

All major differences between the MVC 5 and Core platforms are summarized in Migrating to ASP.NET Core.

×

Integrating Xperience membership

Xperience provides an integration API that allows you to work with Xperience membership data on websites presented by a separate MVC application. The API is available in the Kentico.Membership assembly and namespace, which is provided as part of the Kentico.Xperience.AspNet.Mvc5 integration package.
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.

You can set up the following scenarios:

The membership integration is based on ASP.NET Identity and the OWIN standard. As a result, you can work with user data through the standard approaches that you would use in any ASP.NET MVC application.

Download and examine the LearningKit project for a sample implementation of the Xperience membership integration.

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

Download and examine the LearningKit project for a sample implementation of the Xperience membership integration.

Integrating Xperience membership into your project

Before you can start working with Xperience membership data in your application, you need to register the required API:

  1. Open your MVC project in Visual Studio.
  2. Install the Microsoft.Owin.Host.SystemWeb NuGet package.
  3. Add a Startup.Auth class to your project's App_Start folder (or modify your existing authentication startup file):

    using System;
    using System.Web;
    using System.Web.Mvc;
    
    using Microsoft.Owin;
    using Microsoft.Owin.Security.Cookies;
    using Microsoft.AspNet.Identity;
    using Owin;
    
    using CMS.Helpers;
    using CMS.SiteProvider;
    
    using Kentico.Membership;
    
    // Assembly attribute that sets the OWIN startup class
    // This example sets the Startup class from the 'LearningKit.App_Start' namespace, not 'LearningKit.App_Start.Basic' used below
    // The active Startup class is defined in Startup.Auth.cs and additionally demonstrates registration of external authentication services
    [assembly: OwinStartup(typeof(LearningKit.App_Start.Startup))]
    
    namespace LearningKit.App_Start.Basic
    {
        public partial class Startup
        {
            // Cookie name prefix used by OWIN when creating authentication cookies
            private const string OWIN_COOKIE_PREFIX = ".AspNet.";
    
    
            public void Configuration(IAppBuilder app)
            {
                // Registers the Kentico.Membership identity implementation
                app.CreatePerOwinContext(() => KenticoUserManager.Initialize(app, new KenticoUserManager(new KenticoUserStore(SiteContext.CurrentSiteName))));
                app.CreatePerOwinContext<KenticoSignInManager>(KenticoSignInManager.Create);
    
                // Configures the authentication cookie
                UrlHelper urlHelper = new UrlHelper(HttpContext.Current.Request.RequestContext);
                app.UseCookieAuthentication(new CookieAuthenticationOptions
                {
                    AuthenticationType = DefaultAuthenticationTypes.ApplicationCookie,
                    // Fill in the name of your sign-in action and controller
                    LoginPath = new PathString(urlHelper.Action("SignIn", "Account")),
                    Provider = new CookieAuthenticationProvider
                    {
                        // Sets the return URL for the sign-in page redirect (fill in the name of your sign-in action and controller)
                        OnApplyRedirect = context => context.Response.Redirect(urlHelper.Action("SignIn", "Account")
                                                     + new Uri(context.RedirectUri).Query)
                    }
                });
    
                // Registers the authentication cookie with the 'Essential' cookie level
                // Ensures that the cookie is preserved when changing a visitor's allowed cookie level below 'Visitor'
                CookieHelper.RegisterCookie(OWIN_COOKIE_PREFIX + DefaultAuthenticationTypes.ApplicationCookie, CookieLevel.Essential);
            }
        }
    }
  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:

      using Microsoft.AspNetCore.Identity;
      
      using CMS.Helpers;
      
      using Kentico.Membership;
      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:

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

Registering authentication cookies

We strongly recommend registering all authentication cookies used on your website with an appropriate cookie level (Essential when working with the default cookie level values).

Otherwise you may encounter problems with the cookies being cleared after adjusting the allowed cookie level for visitors (typically when visitors do not consent with tracking). Changes of the allowed cookie level automatically remove all cookies above the given level. Any unregistered cookies are processed with the Visitor level, which is usually too high for basic authentication cookies.

To register a cookie, call the CookieHelper.RegisterCookie method (available in the CMS.Helpers namespace of the Xperience API) in your application's startup code. You can access the default level values in the CookieLevel enumeration.

The Xperience membership implementation is now registered and you can work with the Kentico.Membership API in your application's code. Continue by setting up user authentication. You can also implement the following features:

Configuring the membership integration

The configuration of the membership integration provided by Xperience reflects the Security & Membership and Passwords settings configured via the Settings application in the administration interface. The system maps these settings when initializing the KenticoUserManager class. 

SettingCorresponding membership configurationNotes
Require unique user emailsUserManager.UserValidator.RequireUniqueEmailThese settings are mapped during the KenticoUserManger.Initialize call.
Reset password intervalUserManager.UserTokenProvider.TokenLifespan

When configuring membership for your application, do not override the mentioned UserManager configuration unless you explicitly intend to do so. Otherwise, you effectively remove the ability to configure the corresponding behavior via the administration interface. 

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

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

SettingsIdentity configuration optionNotes
Require unique user emails

IdentityOptions.User.RequireUniqueEmail

These settings are mapped as part of the AddApplicationIdentity call before the user-provided Identity configuration is applied. 

Registration requires administrator's approval

IdentityOptions.SignIn.RequireConfirmedAccount

Reset password interval

DataProtectionTokenProviderOptions.TokenLifespan

This configuration is set during the AddApplicationDefaultTokenProviders call.

If the reset interval is set to 0, the password reset token expiration defaults to 24 hours. 

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.


Was this page helpful?