• Documentation
  Kentico development modelsInstallationUsing the Kentico interfaceDeveloping websitesConfiguring KenticoManaging usersSecuring websitesDeploying websitesManaging website contentMultilingual websitesMacro expressionsExternal utilitiesIntegrating 3rd party systemsCustom developmentE-commerce featuresOn-line marketing featuresCommunity featuresRelease notes - Kentico 12
• Tutorial
  Getting started with KenticoUsing the Kentico interfaceSelecting your tutorial pathSite development overviewPortal Engine developmentMVC developmentMVC business tutorialResource hub for marketers
• API Examples
  Content managementOn-line marketingE-commerceSocial and CommunityDevelopmentConfiguration

You may be able to set up authentication via other types of services, but only the ones listed above are guaranteed and tested with the Kentico.Membership implementation.

Registering external authentication services

Use the following steps to install and register external authentication services into your MVC project:

1. Open your MVC project in Visual Studio.

2. Install the Microsoft.Owin.Host.SystemWeb NuGet package.

3. Install NuGet packages containing the authentication middleware components required for the services you wish to use:

   • Microsoft.Owin.Security.WsFederation
   • Microsoft.Owin.Security.OpenIdConnect
   • Microsoft.Owin.Security.Facebook
   • Microsoft.Owin.Security.Google

4. Add a Startup.Auth class to your project's App_Start folder (or modify your existing authentication startup file).

5. Set up cookie authentication to allow the application to store information about signed in users. See Integrating Kentico membership for details.

   Note: The code registering cookie authentication must be placed before you add any external authentication services.

6. Register any required authentication services within the Startup class (using the OWIN API provided by the installed packages):

   C#

   Copy

    using System;
   using System.Web;
   using System.Web.Mvc;
   
   using Microsoft.Owin;
   using Microsoft.Owin.Security;
   using Microsoft.Owin.Security.Cookies;
   using Microsoft.AspNet.Identity;
   using Owin;
   
   using CMS.Helpers;
   using CMS.SiteProvider;
   
   using Kentico.Membership;
   
   using Microsoft.Owin.Security.WsFederation;
   using Microsoft.Owin.Security.OpenIdConnect;
   using Microsoft.Owin.Security.Facebook;
   using Microsoft.Owin.Security.Google;
   
   // Assembly attribute that sets the OWIN startup class
   [assembly: OwinStartup(typeof(LearningKit.App_Start.Startup))]
   
   namespace LearningKit.App_Start
   {
       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(() => UserManager.Initialize(app, new UserManager(new UserStore(SiteContext.CurrentSiteName))));
               app.CreatePerOwinContext<SignInManager>(SignInManager.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);
   
               // Uses a cookie to temporarily store information about users signing in via external authentication services
               app.UseExternalSignInCookie(DefaultAuthenticationTypes.ExternalCookie);
   
               // Registers a WS-Federation authentication service
               app.UseWsFederationAuthentication(
                       new WsFederationAuthenticationOptions
                       {
                       // Set any properties required by your authentication service
                       MetadataAddress = "placeholder", // Fill in the address of your service's WS-Federation metadata
                       Wtrealm = "",
                       // When using external services, Passive authentication mode may help avoid redirect loops for 401 responses
                       AuthenticationMode = AuthenticationMode.Passive
                       });
   
               // Registers an OpenID Connect authentication service
               app.UseOpenIdConnectAuthentication(
                   new OpenIdConnectAuthenticationOptions
                   {
                       // Set any properties required by your authentication service
                       ClientId = "placeholder",
                       ClientSecret = "placeholder",
                       Authority = "placeholder",
                       AuthenticationMode = AuthenticationMode.Passive
                   });
   
               // Registers the Facebook authentication service
               app.UseFacebookAuthentication(
                   new FacebookAuthenticationOptions
                   {
                       // Fill in the application ID and secret of your Facebook authentication application
                       AppId = "placeholder",
                       AppSecret = "placeholder"
                   });
   
               // Registers the Google authentication service
               app.UseGoogleAuthentication(
                   new GoogleOAuth2AuthenticationOptions
                   {
                       // Fill in the client ID and secret of your Google authentication application
                       ClientId = "placeholder",
                       ClientSecret = "placeholder"
                   });
           }        
       }
   }

The Kentico identity implementation and the specified external authentication services are now registered for your application. Continue by setting up the components required for using external authentication on your website (controllers, views, etc.).

Setting up external authentication

After you register the required authentication services, you need to implement actions that redirect visitors to the external authentication service, process the response, and handle the corresponding user accounts in Kentico.

The following is a basic example of external authentication handling:

1. Create a new controller class in your MVC project or edit an existing one.

2. Prepare the following properties:

   • SignInManager - gets an instance of the Kentico.Membership.SignInManager class for the current request – call HttpContext.GetOwinContext().Get<SignInManager>().

   • UserManager - gets an instance of the Kentico.Membership.UserManager class for the current request – call HttpContext.GetOwinContext().Get<UserManager>().

   • AuthenticationManager - provides access to the authentication middleware functionality (Microsoft.Owin.Security.IAuthenticationManager instance) – use the HttpContext.GetOwinContext().Authentication property.

     C#

     Copy

     using System;
     using System.Web;
     using System.Web.Mvc;
     using System.Threading.Tasks;
     using CMS.Helpers;
     using CMS.SiteProvider;
     using Microsoft.AspNet.Identity;
     using Microsoft.AspNet.Identity.Owin;
     using Microsoft.Owin.Security;
     
     using Kentico.Membership;

     C#

     Copy

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

3. Add a POST action that handles redirection to external authentication services. Use a parameter to specify the name of the requested authentication middleware instance.

4. Add an action that handles the responses from external services.

   • Call the AuthenticationManager.GetExternalLoginInfoAsync method to get login information from the external identity provided by the service.
   • Use the SignInManager.ExternalSignInAsync method to sign in to Kentico based on external data.

5. Add logic that creates new users in the Kentico database if the first sign-in using the external data fails:

   1. Prepare a new Kentico.Membership.User object based on the external login data. You must enable the user object's IsExternal property.
   2. Call the UserManager.CreateAsync method to create the user in the Kentico database.
   3. Call the UserManager.AddLoginAsync method to create a mapping between the new user and the given authentication provider.
   4. (Optional) Add the user to any required roles. See Managing roles from MVC applications to learn how to add users to Kentico roles using the ASP.NET Identity API.

6. Design the user interface required for external authentication on your website

   • Add buttons onto your website's sign-in page that target the RequestSignIn action. Supply parameters that specify the provider type for each authentication service and optionally a return URL.

     XMLExample of external authentication buttons (Razor view)

     Copy

     @using Microsoft.Owin.Security
     
     @{
         @* Gets a collection of the authentication services registered in your application's startup class *@
         var authServices = Context.GetOwinContext().Authentication.GetExternalAuthenticationTypes();
     
         @* Generates a form with buttons targeting the RequestSignIn action. Optionally pass a redirect URL as a parameter. *@
         using (Html.BeginForm("RequestSignIn", "ExternalAuthentication"))
         {
             @Html.AntiForgeryToken()
             <p>
                 @foreach (AuthenticationDescription p in authServices)
                 {
                     <button type="submit" class="btn btn-default" id="@p.AuthenticationType" name="provider" value="@p.AuthenticationType" title="Sign in using your @p.Caption account">@p.AuthenticationType</button>
                 }
             </p>
         }
     }

   • Create a view for displaying information in situations where the external authentication fails (ExternalAuthenticationFailure in the example).

   • Create a view for displaying information in situations where the external authentication succeeds, but the matching Kentico user account is disabled (Lockout in the example).

   • Create a view for the SignInCallback action.

     In the most basic version of the SignInCallback view, you only need to display error messages in situations where the external authentication succeeds, but Kentico is unable to create a matching user account.

     You can implement an extended version with an editing form that allows visitors to adjust and resubmit the data of the new user account (using a strongly typed view that receives the external login data from the action).

Visitors can now sign in on the website through the external authentication services that you registered in the Startup class. Upon successful authentication, the system creates a corresponding user account in the shared Kentico database, along with a mapping between the user and the given authentication provider.