{"id":11865,"date":"2018-02-27T10:01:19","date_gmt":"2018-02-27T18:01:19","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/webdev\/?p=11865"},"modified":"2018-02-27T10:01:19","modified_gmt":"2018-02-27T18:01:19","slug":"asp-net-core-2-1-https-improvements","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/asp-net-core-2-1-https-improvements\/","title":{"rendered":"ASP.NET Core 2.1.0-preview1: Improvements for using HTTPS"},"content":{"rendered":"

Securing web apps with HTTPS is more important than ever before. Browser enforcement of HTTPS is becoming increasingly strict<\/a>. Sites that don't use HTTPS are increasingly labeled as insecure. Browsers are also starting to enforce that new and existing web features must only be used from an secure context (Chromium<\/a>, Mozilla<\/a>). New privacy requirements like the Global Data Protection Regulation (GDPR) require the use of HTTPS to protect user data. Using HTTPS during development also helps prevent HTTPS related issues before deployment, like insecure links.<\/p>\n

ASP.NET Core 2.1 makes it easy to both develop your app with HTTPS enabled and to configure HTTPS once your app is deployed. The ASP.NET Core 2.1 project templates have been updated to enable HTTPS by default. To enable HTTPS in production simply configure the correct server certificate. ASP.NET Core 2.1 also adds support for HTTP Strict Transport Security (HSTS) to enforce HTTPS usage in production and adds improved support for redirecting HTTP traffic to HTTPS endpoints.<\/p>\n

HTTPS in development<\/h3>\n

To get started with ASP.NET Core 2.1 and HTTPS install the .NET Core SDK for 2.1.0-preview1<\/a>. The SDK will create an HTTPS development certificate for you as part of the first-run experience. For example, when you run dotnet new razor<\/code> for the first time you should see the following console output:<\/p>\n

ASP.NET Core\n------------<\/span>\nSuccessfully installed the<\/span> ASP.NET Core HTTPS Development Certificate.\nTo trust the<\/span> certificate (Windows and<\/span> macOS only) first<\/span> install the<\/span> dev-certs tool by<\/span> running 'dotnet install tool dotnet-dev-certs -g --version 2.1.0-preview1-final'<\/span> and<\/span> then<\/span> run 'dotnet-dev-certs https --trust'<\/span>.\nFor more information on<\/span> configuring<\/span> HTTPS<\/span> see<\/span> https<\/span>:\/\/go<\/span>.microsoft<\/span>.com<\/span>\/fwlink<\/span>\/?linkid<\/span>=848054<\/span>.\n<\/code><\/pre>\n
The ASP.NET Core HTTPS Development Certificate has now been installed into the local user certificate store, but it still needs to be trusted. To trust the certificate you need to perform a one-time step to install and run the new dotnet dev-certs<\/code> tool as instructed:<\/p>\n
C:WebApplication1>dotnet install tool dotnet-dev-certs -g --version 2.1.0-preview1-final<\/span>\n\nThe installation succeeded. If there are no further instructions, you can type the<\/span> following command<\/span> in<\/span> shell<\/span> directly<\/span> to<\/span> invoke<\/span>: dotnet-dev-certs<\/span>\n\nC:WebApplication1>dotnet dev-certs https<\/span> --trust<\/span>\nTrusting the<\/span> HTTPS development certificate was requested. A confirmation prompt will be displayed if<\/span> the<\/span> certificate was not<\/span> previously trusted. Click yes on<\/span> the<\/span> prompt<\/span> to<\/span> trust<\/span> the<\/span> certificate<\/span>.\nA valid HTTPS certificate is already present.\n<\/code><\/pre>\n
To run the dev-certs<\/code> tool both dotnet-dev-certs<\/code> and dotnet dev-certs<\/code> (without the extra hyphen) will work. Note: If you get an error that the tool was not found you may need to open a new command prompt if the current command prompt was open when the SDK was installed.<\/p>\n
On Windows a dialog will pop up to confirm that you want to trust the certificate. <\/p>\n
\"Trust<\/p>\n
Click Yes to trust the certificate.<\/p>\n
On macOS the certificate will get added to your keychain as a trusted certificate.<\/p>\n
On Linux there isn't a standard way across distros to trust the certificate, so you'll need to perform the distro specific guidance for trusting the development certificate.<\/p>\n
Run the app by running dotnet run<\/code>. The ASP.NET Core 2.1 runtime will detect that the development certificate is installed and use the certificate to listen on both http:\/\/localhost:5000<\/code> and<\/em> https:\/\/localhost:5001<\/code>:<\/p>\n
C:<\/span>WebApplication1>dotnet run\nUsing launch settings from C:<\/span>WebApplication1PropertieslaunchSettings.json...\nHosting environment:<\/span> Development\nContent root path:<\/span> C:<\/span>WebApplication1\nNow listening on:<\/span> https:<\/span>\/\/localhost:5001<\/span>\nNow listening on:<\/span> http:<\/span>\/\/localhost:5000<\/span>\nApplication started. Press Ctrl+C to shut down.\n<\/code><\/pre>\n
Close any open browsers and then in a new browser window browse to https:\/\/localhost:5001<\/code> to access the app via HTTPS.<\/p>\n
\"Razor<\/p>\n
If you didn't trust the ASP.NET Core development certificate then the browser will display a security warning:<\/p>\n
\"Untrusted<\/p>\n
You can still click on "Details" to ignore the warning and browse to the site, but you're better off running dotnet dev-certs --trust<\/code> to trust the certificate. Just run the tool once and you should be all set.<\/p>\n
HTTPS redirection<\/h3>\n
If you browse to the app via http:\/\/localhost:5000<\/code> you get redirected to the HTTPS endpoint:<\/p>\n
\"HTTPS<\/p>\n
This is thanks to the new HTTPS redirection middleware that redirects all HTTP traffic to HTTPS. The middleware will detect available HTTPS server addresses at runtime and redirect accordingly. Otherwise, it redirects to port 443 by default.<\/p>\n
The HTTPS redirection middleware is added in app's Configure<\/code> method:<\/p>\n
app.UseHttpsRedirection();<\/span>\n<\/code><\/pre>\n
You can configure the HTTPS port explicitly in your ConfigureServices<\/code> method:<\/p>\n
services.AddHttpsRedirection(options<\/span> => options<\/span>.HttpsPort = 5002<\/span>);\n<\/code><\/pre>\n
Alternatively you can specify the HTTPS port to redirect to using configuration or the ASPNETCORE_HTTPS_PORT<\/code> environment variable. This is useful for when HTTPS is being handled externally from the app, like when the app is hosted behind IIS. For example, the project template adds the ASPNETCORE_HTTPS_PORT<\/code> environment variable to the IIS Express launch profile so that it matches the HTTPS port setup for IIS Express:<\/p>\n
{\n  \"iisSettings\"<\/span>: {\n    \"windowsAuthentication\"<\/span>: false<\/span>,\n    \"anonymousAuthentication\"<\/span>: true<\/span>,\n    \"iisExpress\"<\/span>: {\n      \"applicationUrl\"<\/span>: \"http:\/\/localhost:51667\"<\/span>,\n      \"sslPort\"<\/span>: 44370<\/span>\n    }\n  },\n  \"profiles\"<\/span>: {\n    \"IIS Express\"<\/span>: {\n      \"commandName\"<\/span>: \"IISExpress\"<\/span>,\n      \"launchBrowser\"<\/span>: true<\/span>,\n      \"environmentVariables\"<\/span>: {\n        \"ASPNETCORE_ENVIRONMENT\"<\/span>: \"Development\"<\/span>,\n        \"ASPNETCORE_HTTPS_PORT\"<\/span>: \"44370\"<\/span>\n      }\n    }\n  }\n}\n<\/code><\/pre>\n
HTTP Strict Transport Security (HSTS)<\/h3>\n
HSTS<\/a> is a protocol that instructs browsers to access the site via HTTPS. The protocol has allowances for specifying how long the policy should be enforced (max age) and whether the policy applies to subdomains or not. You can also enable support for your domain to be added to the HSTS preload list.<\/p>\n
The ASP.NET Core 2.1 project templates enable support for HSTS by adding the new HSTS middleware in the app's Configure<\/code> method:<\/p>\n
if<\/span> (env.IsDevelopment())\n{\n    app<\/span>.UseDeveloperExceptionPage();\n}\nelse<\/span>\n{\n    app<\/span>.UseExceptionHandler(\"\/Error\"<\/span>);\n    app<\/span>.UseHsts();\n}\n<\/code><\/pre>\n
Note that HSTS is only enabled when running in a non-development environment. This is to prevent setting an HSTS policy for localhost when in development.<\/p>\n
You can configure your HSTS policy (max age, include subdomains, exclude specific domains, support preload) in your ConfigureServices<\/code> method:<\/p>\n
services.AddHsts(options<\/span> =>\n{\n    options<\/span>.MaxAge = TimeSpan.FromDays(100<\/span>);\n    options<\/span>.IncludeSubDomains = true<\/span>;\n    options<\/span>.Preload = true<\/span>;\n});\n<\/code><\/pre>\n
Configuring HTTPS in production<\/h3>\n
The ASP.NET Core HTTPS development certificate is only for development purposes. In production you need to configure your app for HTTPS including the production certificate that you want to use. Often this is handled externally from the app using a reverse proxy like IIS or NGINX. ASP.NET Core 2.1 adds support to Kestrel for configuring endpoints and HTTPS certificates.<\/p>\n
You can still configure server URLs (include HTTPS URLs) using the ASPNETCORE_SERVER_URLS<\/code> environment variable. To configure the HTTPS certificate for any HTTPS server URLs you configure a default HTTPS certificate.<\/p>\n
The default HTTPS certificate can be loaded from a certificate store:<\/p>\n
{\n  \"Kestrel\"<\/span>: {\n    \"Certificates\"<\/span>: {\n      \"Default\"<\/span>: {\n        \"Subject\"<\/span>: \"mysite\"<\/span>,\n        \"Store\"<\/span>: \"User\"<\/span>,\n        \"Location\"<\/span>: \"Local\"<\/span>,\n        \"AllowInvalid\"<\/span>: \"false\"<\/span> \/\/ Set to \"true\"<\/span> to allow invalid certificates (e.g. self-signed)\n      }\n    }\n  }\n}\n<\/code><\/pre>\n
Or from a password protected PFX file:<\/p>\n
{\n  \"Kestrel\"<\/span>: {\n    \"Certificates\"<\/span>: {\n      \"Default\"<\/span>: {\n        \"Path\"<\/span>: \"cert.pfx\"<\/span>,\n        \"Password\"<\/span>: \"<password>\"<\/span>\n      }\n    }\n  }\n}\n<\/code><\/pre>\n
You can also configure named endpoints for Kestrel that include both the URL for the endpoint and the HTTPS certificate:<\/p>\n
{\n  \"Kestrel\"<\/span>: {\n    \"EndPoints\"<\/span>: {\n      \"Http\"<\/span>: {\n        \"Url\"<\/span>: \"http:\/\/localhost:5005\"<\/span>\n      },\n\n      \"HttpsInlineCertFile\"<\/span>: {\n        \"Url\"<\/span>: \"https:\/\/localhost:5006\"<\/span>,\n        \"Certificate\"<\/span>: {\n          \"Path\"<\/span>: \"cert.pfx\"<\/span>,\n          \"Password\"<\/span>: \"<cert password>\"<\/span>\n        }\n      },\n\n      \"HttpsInlineCertStore\"<\/span>: {\n        \"Url\"<\/span>: \"https:\/\/localhost:5007\"<\/span>,\n        \"Certificate\"<\/span>: {\n          \"Subject\"<\/span>: \"mysite\"<\/span>,\n          \"Store\"<\/span>: \"My\"<\/span>,\n          \"Location\"<\/span>: \"CurrentUser\"<\/span>,\n          \"AllowInvalid\"<\/span>: \"false\"<\/span> \/\/ Set to true<\/span> to allow invalid certificates (e.g. self-signed)\n        }\n      }\n    }\n  }\n}\n<\/code><\/pre>\n
Summary<\/h3>\n
We hope these new features will make it much easier to use HTTPS during development and in production. Please give the new HTTPS support a try and let us know what you think!<\/p>\n","protected":false},"excerpt":{"rendered":"
Securing web apps with HTTPS is more important than ever before. Browser enforcement of HTTPS is becoming increasingly strict. Sites that don't use HTTPS are increasingly labeled as insecure. Browsers are also starting to enforce that new and existing web features must only be used from an secure context (Chromium, Mozilla). New privacy requirements like […]<\/p>\n","protected":false},"author":417,"featured_media":58792,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[197,7509],"tags":[],"class_list":["post-11865","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-aspnet","category-aspnetcore"],"acf":[],"blog_post_summary":"
Securing web apps with HTTPS is more important than ever before. Browser enforcement of HTTPS is becoming increasingly strict. Sites that don't use HTTPS are increasingly labeled as insecure. Browsers are also starting to enforce that new and existing web features must only be used from an secure context (Chromium, Mozilla). New privacy requirements like […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/11865","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/417"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=11865"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/11865\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/58792"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=11865"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=11865"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=11865"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}