---
title: Setting up authentication
---

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

<!-- dev-model:mvc start -->

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

Once you [integrate Xperience membership](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/integrating-xperience-membership.md) into your live site project, you can implement actions that allow visitors to sign in and out of the website with Xperience [user accounts.](https://docs.kentico.com/13/managing-users/user-management.md)

Use the following approach to develop sign-in actions:

> **Tip:** **Tip**: To view the full code of a functional example, you can inspect and download the [LearningKit project](https://github.com/Kentico/LearningKit-Mvc) on GitHub. You can also run the LearningKit website by connecting the project to an Xperience database.

1. Create a new controller class in your MVC project or edit an existing one.
2. Prepare a property that gets an instance of the **Kentico.Membership.KenticoSignInManager** class for the current request – call _HttpContext.GetOwinContext().Get()_.
3. Implement two sign-in actions – one basic GET action to display the sign-in form and a second POST action to handle the authentication when the form is submitted.
4. Call the **PasswordSignInAsync** method of the _KenticoSignInManager_ instance to authenticate users against the Xperience database (within the code of the POST action).

   ```csharp

   using System;
   using System.Web;
   using System.Web.Mvc;
   using System.Threading.Tasks;

   using Microsoft.AspNet.Identity;
   using Microsoft.AspNet.Identity.Owin;
   using Microsoft.Owin.Security;

   using Kentico.Membership;

   using CMS.Core;
   using CMS.Base.UploadExtensions;
   using CMS.Membership;
   using CMS.SiteProvider;


   ```

   ```csharp title="Sign-in actions example"

           /// <summary>
           /// Provides access to the Kentico.Membership.KenticoSignInManager instance.
           /// </summary>
           public KenticoSignInManager KenticoSignInManager
           {
               get
               {
                   return HttpContext.GetOwinContext().Get<KenticoSignInManager>();
               }
           }

           /// <summary>
           /// Basic action that displays the sign-in form.
           /// </summary>
           public ActionResult SignIn()
           {
               return View();
           }     

           /// <summary>
           /// Handles authentication when the sign-in form is submitted. Accepts parameters posted from the sign-in form via the SignInViewModel.
           /// </summary>
           [HttpPost]
           [ValidateAntiForgeryToken]
           [ValidateInput(false)]
           public async Task<ActionResult> SignIn(SignInViewModel model, string returnUrl)
           {
               // Validates the received user credentials based on the view model
               if (!ModelState.IsValid)
               {
                   // Displays the sign-in form if the user credentials are invalid
                   return View();
               }

               // Attempts to authenticate the user against the Xperience database
               SignInStatus signInResult = SignInStatus.Failure;
               try
               {
                   signInResult = await KenticoSignInManager.PasswordSignInAsync(model.UserName, model.Password, model.SignInIsPersistent, false);
               }
               catch (Exception ex)
               {
                   // Logs an error into the Xperience event log if the authentication fails
                   eventLogService.LogException("MvcApplication", "SignIn", ex);
               }            

               // If the authentication was successful, redirects to the return URL when possible or to a different default action
               if (signInResult == SignInStatus.Success)
               {                
                   string decodedReturnUrl = Server.UrlDecode(returnUrl);
                   if (!string.IsNullOrEmpty(decodedReturnUrl) && Url.IsLocalUrl(decodedReturnUrl))
                   {
                       return Redirect(decodedReturnUrl);
                   }
                   return RedirectToAction("Index", "Home");
               }

               // If the 'Registration requires administrator's approval' setting is enabled and the user account
               // is pending activation, displays an appropriate message
               if (signInResult == SignInStatus.LockedOut)
               {
                   // If the 'Registration requires administrator's approval' setting is enabled and the user account
                   // is pending activation, displays an appropriate message
                   User user = await KenticoUserManager.FindByNameAsync(model.UserName);
                   if (user.WaitingForApproval)
                   {
                       ModelState.AddModelError(String.Empty, "You account is pending administrator approval.");
                   }

                   return View();
               }

               // If the authentication was not successful, displays the sign-in form with an "Authentication failed" message 
               ModelState.AddModelError(String.Empty, "Authentication failed");
               return View();
           }


   ```
5. We recommend creating a view model for your sign-in action _(SignInViewModel_ in the example above). The view model allows you to:
   - Pass parameters from the sign-in form (username, password, and sign-in persistence status).
   - Use data annotations to define validation and formatting rules for the sign-in parameters. See [System.ComponentModel.DataAnnotations](https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.dataannotations) for more information about the available data annotation attributes.

To allow users to sign out on your website, extend your sign-in controller class:

1. Prepare a property that provides access to the authentication middleware functionality (_Microsoft.Owin.Security.IAuthenticationManager_ instance) – use the _HttpContext.GetOwinContext().Authentication_ property.
2. Add another action to handle sign-out requests.
3. Call the **SignOut(DefaultAuthenticationTypes.ApplicationCookie)** method of the authentication manager to sign out the current user.

   ```csharp title="Sign-out action example"

           /// <summary>
           /// Provides access to the Microsoft.Owin.Security.IAuthenticationManager instance.
           /// </summary>
           public IAuthenticationManager AuthenticationManager
           {
               get
               {
                   return HttpContext.GetOwinContext().Authentication;
               }
           }

           /// <summary>
           /// Action for signing out users. The Authorize attribute allows the action only for users who are already signed in.
           /// </summary>
           [Authorize]
           [HttpPost]
           [ValidateAntiForgeryToken]
           public ActionResult SignOut()
           {
               // Signs out the current user
               AuthenticationManager.SignOut(DefaultAuthenticationTypes.ApplicationCookie);

               // Redirects to a different action after the sign-out
               return RedirectToAction("Index", "Home");
           }


   ```

Finally, you need to design a user interface for the authentication logic:

- Create a view for the _SignIn_ action and display an appropriate sign-in form for your website. We recommend using a strongly typed view based on your sign-in view model.
- Add a sign in button or link that targets the _SignIn_ action (for example within your site's main layout page).
- Add a sign out button or link that targets the _SignOut_ action.

Visitors can now sign in to your site with Xperience user accounts from the connected database. If you wish to allow users to register new accounts, see [Enabling user registration](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/enabling-user-registration.md).

> **Tip:** **Tip**: When writing additional code or views for your website, you can access information about the currently authenticated user via the standard **User.Identity** object. For example, _User.Identity.Name_ returns the username of the currently signed in user.

> **Note:** **Ensuring the correct password format**
>
> If your administration application uses custom salt values when generating password hashes, you also need to set the same values for the MVC application. Authentication will always fail if the password hashes are not identical for both applications.
>
> Check the _appSettings_ section of your administration application's _web.config_ for the **CMSPasswordSalt** key. If the key is present, copy it to the _web.config_ file of your MVC project.
>
> See also: [Setting the user password format](https://docs.kentico.com/13/securing-websites/designing-secure-websites/securing-user-accounts-and-passwords/setting-the-user-password-format.md)

<!-- dev-model:mvc end -->

<!-- dev-model:core start -->

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

Once you integrate [Xperience ASP.NET Core Identity](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/integrating-xperience-membership.md) into your project, you can implement actions that allow visitors to sign in and out of the website with Xperience [user accounts.](https://docs.kentico.com/13/managing-users/user-management.md)

> **Tip:** **Tip**: To view the full code of a functional example, you can inspect and download the [LearningKit project](https://github.com/Kentico/LearningKit-Core) on GitHub. You can also run the LearningKit website by connecting the project to an Xperience database.

Use the following approach to develop sign-in actions (this example uses the MVC development approach):

1. Create a new controller class in your project or edit an existing one.
2. Provide an instance of the **Microsoft.AspNetCore.Identity.SignInManager** class using dependency injection.
3. Implement two sign-in actions – one basic GET action to display the sign-in form and a second POST action to handle the authentication when the form is submitted.
4. Call the **PasswordSignInAsync** method of the _SignInManager_ instance to authenticate users against the Xperience database.

   ```csharp

   using System;
   using System.Net;
   using System.Threading.Tasks;

   using Microsoft.AspNetCore.Mvc;
   using Microsoft.AspNetCore.Http;
   using Microsoft.AspNetCore.Authorization;
   using Microsoft.AspNetCore.Identity;

   using CMS.Base;
   using CMS.Core;
   using CMS.Membership;
   using CMS.Base.UploadExtensions;

   using Kentico.Membership;

   using LearningKitCore.Models.Users.Account;


   ```

   ```csharp title="Sign-in actions example"

           /// <summary>
           /// Basic action that displays the sign-in form.
           /// </summary>
           public IActionResult SignIn()
           {
               return View();
           }

           /// <summary>
           /// Handles authentication when the sign-in form is submitted. Accepts parameters posted from the sign-in form via the SignInViewModel.
           /// </summary>
           [HttpPost]
           [ValidateAntiForgeryToken]
           public async Task<IActionResult> SignIn(SignInViewModel model, string returnUrl)
           {
               // Validates the received user credentials based on the view model
               if (!ModelState.IsValid)
               {
                   // Displays the sign-in form if the user credentials are invalid
                   return View();
               }

               // Attempts to authenticate the user against the Xperience database
               var signInResult = Microsoft.AspNetCore.Identity.SignInResult.Failed;
               try
               {
                   signInResult = await signInManager.PasswordSignInAsync(model.UserName, model.Password, model.RememberMe, false);
               }
               catch (Exception ex)
               {
                   // Logs an error into the Xperience event log if the authentication fails
                   eventLogService.LogException("MvcApplication", "AUTHENTICATION", ex);
               }

               // If the authentication was successful, redirects to the return URL when possible or to a different default action
               if (signInResult.Succeeded)
               {
                   string decodedReturnUrl = WebUtility.UrlDecode(returnUrl);
                   if (!string.IsNullOrEmpty(decodedReturnUrl) && Url.IsLocalUrl(decodedReturnUrl))
                   {
                       return Redirect(decodedReturnUrl);
                   }
                   // Redirects the user to the homepage
                   return RedirectToAction(nameof(HomeController.Users), "Home");
               }

               if(signInResult.IsNotAllowed)
               {
                   // If the 'Registration requires administrator's approval' setting is enabled and the user account
                   // is pending activation, displays an appropriate message
                   ApplicationUser user = await userManager.FindByNameAsync(model.UserName);
                   if (user != null && user.WaitingForApproval)
                   {
                       ModelState.AddModelError(String.Empty, "You account is pending administrator approval.");

                       return RedirectToAction(nameof(WaitingForApproval));
                   }

                   // The other setting that causes 'IsNotAllowed' is 'Require email confirmation'
                   ModelState.AddModelError(String.Empty, "Please confirm your email.");

                   return View();
               }

               // If the authentication was not successful due to any other reason, displays the sign-in form with an "Authentication failed" message 
               ModelState.AddModelError(String.Empty, "Authentication failed, please verify that you entered the correct authentication credentials.");
               return View();            
           }

           public IActionResult WaitingForApproval()
           {
               return View();
           }


   ```
5. We recommend creating a view model for your sign-in action _(SignInViewModel_ in the example above). The view model allows you to:
   - Pass parameters from the sign-in form (username, password, and sign-in persistence status).
   - Use data annotations to define validation and formatting rules for the sign-in parameters. See [System.ComponentModel.DataAnnotations](https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.dataannotations?view=netcore-3.1) for more information about the available data annotation attributes.

To allow users to sign out on your website, extend your sign-in controller class:

1. Add another action to handle sign-out requests.
2. Call the **SignOutAsync** method of the sign-in manager to sign out the current user.

   ```csharp title="Sign-out action example"

           /// <summary>
           /// Action for signing out users. The Authorize attribute allows the action only for users who are already signed in.
           /// </summary>
           [Authorize]
           [HttpPost]
           [ValidateAntiForgeryToken]
           public IActionResult SignOut()
           {
               // Signs out the current user
               signInManager.SignOutAsync();

               // Redirects to a different action after the sign-out
               return RedirectToAction(nameof(HomeController.Index), "Home");
           }


   ```

Finally, you need to design a user interface for the authentication logic:

- Create a view for the sign-in action and display an appropriate sign-in form for your website. We recommend using a strongly typed view based on your sign-in view model.
- Add a sign in button or link that targets the sign-in action (for example within your site's main layout page).
- Add a sign out button or link that targets the sign-out action.

Visitors can now sign in to your site with Xperience user accounts from the connected database. If you wish to allow users to register new accounts, see [Enabling user registration](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/enabling-user-registration.md).

> **Tip:** **Tip**: When writing additional code or views for your website, you can access information about the currently authenticated user via the [User](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.controllerbase.user) property. For example, _User.Identity.Name_ returns the username of the currently signed-in user.

> **Note:** **Ensuring the correct password format**
>
> If your administration application uses a custom salt value when generating password hashes, you also need to set the same value for the Core application. Authentication will always fail if the password hashes are not identical for both applications.
>
> Check the _appSettings_ section of your administration application's web.config for the **CMSPasswordSalt** key. If the key is present, copy it to the application configuration file of your Core project (_appsettings.json_ by default).
>
> See also: [Setting the user password format](https://docs.kentico.com/13/securing-websites/designing-secure-websites/securing-user-accounts-and-passwords/setting-the-user-password-format.md)

<!-- dev-model:core end -->