--- title: Integrating Xperience membership related: - https://docs.kentico.com/13/managing-users/user-registration-and-authentication/setting-up-authentication.md - https://docs.kentico.com/13/managing-users/user-registration-and-authentication/enabling-user-registration.md - https://docs.kentico.com/13/securing-websites/designing-secure-websites/securing-user-accounts-and-passwords/implementing-password-reset-for-the-live-site.md - https://docs.kentico.com/13/managing-users/user-registration-and-authentication/configuring-external-authentication.md - https://docs.kentico.com/13/managing-users/authorizing-live-site-actions-via-roles.md - https://docs.kentico.com/13/managing-users/user-management.md - https://docs.kentico.com/13/managing-users/adding-custom-fields-to-users.md --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. Xperience provides an integration API that allows you to work with Xperience membership data on websites presented by a [separate MVC application](https://docs.kentico.com/13/developing-websites/mvc-development-overview.md). The API is available in the **Kentico.Membership** assembly and namespace, which is provided as part of the _Kentico.Xperience.AspNet.Mvc5_ [integration package](https://docs.kentico.com/13/developing-websites/starting-with-mvc-development/installing-xperience-integration-packages.md). **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. 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](https://docs.kentico.com/13/developing-websites/starting-with-mvc-development/installing-xperience-integration-packages.md). You can set up the following scenarios: - Allow visitors to [sign in](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/setting-up-authentication.md) with Xperience [user accounts](https://docs.kentico.com/13/managing-users/user-management.md) - Allow users to [register new accounts](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/enabling-user-registration.md) on the site (the user data is stored in the shared Xperience database) - Allow users to [reset their passwords](https://docs.kentico.com/13/securing-websites/designing-secure-websites/securing-user-accounts-and-passwords/implementing-password-reset-for-the-live-site.md) - Authorize actions based on Xperience [roles](https://docs.kentico.com/13/managing-users/role-management.md) - Use [external services](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/configuring-external-authentication.md) for authentication **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. The membership integration is based on [ASP.NET Identity](https://docs.microsoft.com/en-us/aspnet/identity/overview/getting-started/introduction-to-aspnet-identity) and the [OWIN](http://owin.org/) standard. As a result, you can work with user data through the standard approaches that you would use in any ASP.NET MVC application. > **Tip:** Download and examine the [LearningKit project](https://github.com/Kentico/LearningKit-Mvc) for a sample implementation of the Xperience membership integration. **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. The membership integration is based on [ASP.NET Core Identity](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/identity). As a result, you can work with user data through the standard approaches that you would use in any ASP.NET Core application. > **Tip:** Download and examine the [LearningKit project](https://github.com/Kentico/LearningKit-Core) 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: **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. 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): ```csharp 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.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); } } } ``` **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. 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: ```csharp using Microsoft.AspNetCore.Identity; using CMS.Helpers; using Kentico.Membership; ``` ```csharp 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, Kentico.Membership.PasswordHasher>(); services.AddScoped(); services.AddApplicationIdentity() // 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>() // Adds an implementation of the RoleStore used for working with Xperience roles .AddRoleStore>() // Adds an implementation of the UserManager for Xperience membership .AddUserManager>() // Adds the default implementation of the SignInManger .AddSignInManager>(); // 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: ```csharp public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { ... app.UseRouting(); app.UseAuthentication(); app.UseAuthorization(); ... } ``` > **Info:** **Registering authentication cookies** > > We strongly recommend [registering](https://docs.kentico.com/13/developing-websites/working-with-cookies.md) all authentication cookies used on your website with an appropriate [cookie level](https://docs.kentico.com/13/developing-websites/working-with-cookies.md) (**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](https://docs.kentico.com/13/configuring-xperience/data-protection/gdpr-compliance/working-with-consents.md)). 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](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/setting-up-authentication.md). You can also implement the following features: - [User registration](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/enabling-user-registration.md) - [Password reset functionality](https://docs.kentico.com/13/securing-websites/designing-secure-websites/securing-user-accounts-and-passwords/implementing-password-reset-for-the-live-site.md) - [Role-based authorization](https://docs.kentico.com/13/managing-users/authorizing-live-site-actions-via-roles.md) for your controller actions - [Integration of external authentication services](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/configuring-external-authentication.md) ## Configuring the membership integration **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. The configuration of the membership integration provided by Xperience reflects the [Security & Membership](https://docs.kentico.com/13/configuring-xperience/managing-sites/configuring-settings-for-sites/settings-security-membership.md) and [Passwords](https://docs.kentico.com/13/configuring-xperience/managing-sites/configuring-settings-for-sites/settings-security-membership/settings-passwords.md) 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](https://docs.microsoft.com/en-us/previous-versions/aspnet/mt151743\(v=vs.108\)) | These settings are mapped during the _KenticoUserManger.Initialize_ call. | | Reset password interval | [UserManager.UserTokenProvider.TokenLifespan](https://docs.microsoft.com/en-us/previous-versions/aspnet/mt173728\(v=vs.108\)) | | 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. **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. The configuration of the Identity classes provided by Xperience _(ApplicationUserManager, ApplicationUserStore_, etc.) reflects the [Security & Membership](https://docs.kentico.com/13/configuring-xperience/managing-sites/configuring-settings-for-sites/settings-security-membership.md) and [Passwords](https://docs.kentico.com/13/configuring-xperience/managing-sites/configuring-settings-for-sites/settings-security-membership/settings-passwords.md) 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](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/identity-configuration). The following table details the mapping of all Xperience settings to ASP.NET Core Identity configuration options: | Settings | Identity configuration option | Notes | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Require unique user emails | [IdentityOptions.User.RequireUniqueEmail](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.identity.useroptions.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](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.identity.signinoptions.requireconfirmedaccount) | | | Reset password interval | [DataProtectionTokenProviderOptions.TokenLifespan](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.identity.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.