7.9 KiB
title | author | description | monikerRange | ms.author | ms.custom | ms.date | no-loc | uid | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Share authentication cookies among ASP.NET apps | rick-anderson | Learn how to share authentication cookies among ASP.NET 4.x and ASP.NET Core apps. | >= aspnetcore-2.1 | riande | mvc | 09/05/2019 |
|
security/cookie-sharing |
Share authentication cookies among ASP.NET apps
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.
In the examples that follow:
- The authentication cookie name is set to a common value of
.AspNet.SharedCookie
. - The
AuthenticationType
is set toIdentity.Application
either explicitly or by default. - A common app name is used to enable the data protection system to share data protection keys (
SharedCookieApp
). Identity.Application
is used as the authentication scheme. Whatever scheme is used, it must be used consistently within and across the shared cookie apps either as the default scheme or by explicitly setting it. The scheme is used when encrypting and decrypting cookies, so a consistent scheme must be used across apps.- A common data protection key storage location is used.
- In ASP.NET Core apps, xref:Microsoft.AspNetCore.DataProtection.DataProtectionBuilderExtensions.PersistKeysToFileSystem* is used to set the key storage location.
- In .NET Framework apps, Cookie Authentication Middleware uses an implementation of xref:Microsoft.AspNetCore.DataProtection.DataProtectionProvider.
DataProtectionProvider
provides data protection services for the encryption and decryption of authentication cookie payload data. TheDataProtectionProvider
instance is isolated from the data protection system used by other parts of the app. DataProtectionProvider.Create(System.IO.DirectoryInfo, Action<IDataProtectionBuilder>) accepts a xref:System.IO.DirectoryInfo to specify the location for data protection key storage.
DataProtectionProvider
requires the Microsoft.AspNetCore.DataProtection.Extensions NuGet package:- In ASP.NET Core 2.x apps, reference the Microsoft.AspNetCore.App metapackage.
- In .NET Framework apps, add a package reference to Microsoft.AspNetCore.DataProtection.Extensions.
- xref:Microsoft.AspNetCore.DataProtection.DataProtectionBuilderExtensions.SetApplicationName* sets the common app name.
Share authentication cookies with ASP.NET Core Identity
When using ASP.NET Core Identity:
- Data protection keys and the app name must be shared among apps. A common key storage location is provided to the xref:Microsoft.AspNetCore.DataProtection.DataProtectionBuilderExtensions.PersistKeysToFileSystem* method in the following examples. Use xref:Microsoft.AspNetCore.DataProtection.DataProtectionBuilderExtensions.SetApplicationName* to configure a common shared app name (
SharedCookieApp
in the following examples). For more information, see xref:security/data-protection/configuration/overview. - Use the xref:Microsoft.Extensions.DependencyInjection.IdentityServiceCollectionExtensions.ConfigureApplicationCookie* extension method to set up the data protection service for cookies.
- The default authentication type is
Identity.Application
.
In Startup.ConfigureServices
:
services.AddDataProtection()
.PersistKeysToFileSystem("{PATH TO COMMON KEY RING FOLDER}")
.SetApplicationName("SharedCookieApp");
services.ConfigureApplicationCookie(options => {
options.Cookie.Name = ".AspNet.SharedCookie";
});
Note: The preceding instructions don't work with ITicketStore
(CookieAuthenticationOptions.SessionStore
). For more information, see this GitHub issue.
Share authentication cookies without ASP.NET Core Identity
When using cookies directly without ASP.NET Core Identity, configure data protection and authentication in Startup.ConfigureServices
. In the following example, the authentication type is set to Identity.Application
:
services.AddDataProtection()
.PersistKeysToFileSystem("{PATH TO COMMON KEY RING FOLDER}")
.SetApplicationName("SharedCookieApp");
services.AddAuthentication("Identity.Application")
.AddCookie("Identity.Application", options =>
{
options.Cookie.Name = ".AspNet.SharedCookie";
});
Share cookies across different base paths
An authentication cookie uses the HttpRequest.PathBase as its default Cookie.Path. If the app's cookie must be shared across different base paths, Path
must be overridden:
services.AddDataProtection()
.PersistKeysToFileSystem("{PATH TO COMMON KEY RING FOLDER}")
.SetApplicationName("SharedCookieApp");
services.ConfigureApplicationCookie(options => {
options.Cookie.Name = ".AspNet.SharedCookie";
options.Cookie.Path = "/";
});
Share cookies across subdomains
When hosting apps that share cookies across subdomains, specify a common domain in the Cookie.Domain property. To share cookies across apps at contoso.com
, such as first_subdomain.contoso.com
and second_subdomain.contoso.com
, specify the Cookie.Domain
as .contoso.com
:
options.Cookie.Domain = ".contoso.com";
Encrypt data protection keys at rest
For production deployments, configure the DataProtectionProvider
to encrypt keys at rest with DPAPI or an X509Certificate. For more information, see xref:security/data-protection/implementation/key-encryption-at-rest. In the following example, a certificate thumbprint is provided to xref:Microsoft.AspNetCore.DataProtection.DataProtectionBuilderExtensions.ProtectKeysWithCertificate*:
services.AddDataProtection()
.ProtectKeysWithCertificate("{CERTIFICATE THUMBPRINT}");
Share authentication cookies between ASP.NET 4.x and ASP.NET Core apps
ASP.NET 4.x apps that use Katana Cookie Authentication Middleware can be configured to generate authentication cookies that are compatible with the ASP.NET Core Cookie Authentication Middleware. For more information, see Share authentication cookies between ASP.NET 4.x and ASP.NET Core apps (dotnet/AspNetCore.Docs #21987).
Use a common user database
When apps use the same Identity schema (same version of Identity), 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.
When the Identity schema is different among apps, usually because apps are using different Identity versions, sharing a common database based on the latest version of Identity isn't possible without remapping and adding columns in other app's Identity schemas. It's often more efficient to upgrade the other apps to use the latest Identity version so that a common database can be shared by the apps.