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.

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.

Integrating Xperience membership into your project

Before you can start working with Xperience membership data in your MVC 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);
            }
        }
    }

    Registering authentication cookies

    We strongly recommend registering all authentication cookies used on your website with an appropriate cookie level (typically 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 (for example when managing tracking consent). 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 identity 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. 

Was this page helpful?