Integrating Xperience membership

✖
Copy to clipboard
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.

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);
        }
    }
}

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. 

Setting

Corresponding membership configuration

Notes

Require unique user emails

UserManager.UserValidator.RequireUniqueEmail

These settings are mapped during the KenticoUserManger.Initialize call.

Reset password interval

UserManager.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.