Sharing cookies among apps

By Rick Anderson and Luke Latham

Websites often consist of individual web apps working together. To provide a single sign-on (SSO) experience, web apps within a site must share authentication cookies. To support this scenario, the data protection stack allows sharing Katana cookie authentication and ASP.NET Core cookie authentication tickets.

View or download sample code (how to download)

The sample illustrates cookie sharing across three apps that use cookie authentication:

  • ASP.NET Core 2.0 Razor Pages app without using ASP.NET Core Identity
  • ASP.NET Core 2.0 MVC app with ASP.NET Core Identity
  • ASP.NET Framework 4.6.1 MVC app with ASP.NET Identity

In the examples that follow:

  • The authentication cookie name is set to a common value of .AspNet.SharedCookie.
  • The AuthenticationType is set to Identity.Application either explicitly or by default.
  • CookieAuthenticationDefaults.AuthenticationScheme is used as the authentication scheme. The constant resolves to a value of Cookies.
  • The cookie authentication middleware uses an implementation of DataProtectionProvider. DataProtectionProvider provides data protection services for the encryption and decryption of authentication cookie payload data. The DataProtectionProvider instance is isolated from the data protection system used by other parts of the app.

Share authentication cookies among ASP.NET Core apps

When using ASP.NET Core Identity:

In the ConfigureServices method, use the ConfigureApplicationCookie extension method to set up the data protection service for cookies.

services.ConfigureApplicationCookie(options => {
    var protectionProvider = DataProtectionProvider.Create(
        new DirectoryInfo(GetKeyRingFolderPath()));

    options.Cookie.Name = ".AspNet.SharedCookie";
    options.DataProtectionProvider = protectionProvider;
    options.TicketDataFormat = 
        new TicketDataFormat(
            protectionProvider.CreateProtector(
                "Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationMiddleware", 
                "Cookies", 
                "v2"));
});

See the CookieAuthWithIdentity.Core project in the sample code (how to download).

When using cookies directly:

services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.Cookie.Name = ".AspNet.SharedCookie";
        options.DataProtectionProvider = DataProtectionProvider.Create(
            new DirectoryInfo(GetKeyRingFolderPath()));
    });

See the CookieAuth.Core project in the sample code (how to download).

Encrypting data protection keys at rest

For production deployments, configure the DataProtectionProvider to encrypt keys at rest with DPAPI or an X509Certificate. See Key Encryption At Rest for more information.

services.AddDataProtection()
    .ProtectKeysWithCertificate("thumbprint");

Sharing authentication cookies between ASP.NET 4.x and ASP.NET Core apps

ASP.NET 4.x apps which use Katana cookie authentication middleware can be configured to generate authentication cookies that are compatible with the ASP.NET Core cookie authentication middleware. This allows upgrading a large site's individual apps piecemeal while providing a smooth SSO experience across the site.

Tip

When an app uses Katana cookie authentication middleware, it calls UseCookieAuthentication in the project's Startup.Auth.cs file. ASP.NET 4.x web app projects created with Visual Studio 2013 and later use the Katana cookie authentication middleware by default.

Note

An ASP.NET 4.x app must target .NET Framework 4.5.1 or higher. Otherwise, the necessary NuGet packages fail to install.

To share authentication cookies among ASP.NET 4.x apps and ASP.NET Core apps, configure the ASP.NET Core app as stated above, then configure the ASP.NET 4.x apps by following the steps below.

  1. Install the package Microsoft.Owin.Security.Interop into each ASP.NET 4.x app.

  2. In Startup.Auth.cs, locate the call to UseCookieAuthentication and modify it as follows. Change the cookie name to match the name used by the ASP.NET Core cookie authentication middleware. Provide an instance of a DataProtectionProvider initialized to the common data protection key storage location.

app.UseCookieAuthentication(new CookieAuthenticationOptions
{
    AuthenticationType = "Identity.Application",
    CookieName = ".AspNet.SharedCookie",
    LoginPath = new PathString("/Account/Login"),
    Provider = new CookieAuthenticationProvider
    {
        OnValidateIdentity = 
            SecurityStampValidator
                .OnValidateIdentity<ApplicationUserManager, ApplicationUser>(
                    validateInterval: TimeSpan.FromMinutes(30),
                    regenerateIdentity: (manager, user) => 
                        user.GenerateUserIdentityAsync(manager))
    },
    TicketDataFormat = new AspNetTicketDataFormat(
        new DataProtectorShim(
            DataProtectionProvider.Create(new DirectoryInfo(GetKeyRingFolderPath()))
            .CreateProtector(
                "Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationMiddleware",
                "Cookies",
                "v2"))),
                CookieManager = new ChunkingCookieManager()
});

// If not setting http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier and 
// http://schemas.microsoft.com/accesscontrolservice/2010/07/claims/identityprovider,
// then set UniqueClaimTypeIdentifier to a claim that distinguishes unique users.
System.Web.Helpers.AntiForgeryConfig.UniqueClaimTypeIdentifier = 
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name";

See the CookieAuthWithIdentity.NETFramework project in the sample code (how to download).

When generating a user identity, the authentication type must match the type defined in AuthenticationType set with UseCookieAuthentication.

Models/IdentityModels.cs:

public class ApplicationUser : IdentityUser
{
    public async Task<ClaimsIdentity> GenerateUserIdentityAsync(UserManager<ApplicationUser> manager)
    {
        // Note the authenticationType must match the one defined in CookieAuthenticationOptions.AuthenticationType
        var userIdentity = await manager.CreateIdentityAsync(this, "Identity.Application");
        // Add custom user claims here
        return userIdentity;
    }
}

Use a common user database

Confirm that the identity system for each app is pointed at the same user database. Otherwise, the identity system produces failures at runtime when it attempts to match the information in the authentication cookie against the information in its database.