Understanding dotnet dev-certs https: Local HTTPS for .NET Development

The dotnet dev-certs https command creates and manages local development certificates for HTTPS in .NET applications. If you’ve ever seen “Your connection is not private” warnings when running ASP.NET Core apps locally, or struggled with gRPC services refusing to connect over HTTP, this tool solves those problems.

HTTPS isn’t optional anymore, even in local development. Modern browsers enforce stricter security policies, gRPC requires TLS by default, and many third-party services reject HTTP connections. The dev-certs tool bridges the gap between localhost development and production security requirements by creating a trusted certificate that your machine recognizes as legitimate.

What the Tool Does Under the Hood

When you run dotnet dev-certs https --trust, the CLI creates a self-signed certificate specifically for localhost development and adds it to your machine’s trusted certificate store. This eliminates browser warnings and allows secure connections to your local applications.

The certificate includes Subject Alternative Names (SANs) for localhost, 127.0.0.1, and ::1, covering the most common ways you’ll access your local apps. Your operating system’s certificate store treats it as a trusted root certificate, so browsers and HTTP clients accept it without complaints.

Essential Commands and Usage

Here are the core commands you’ll use:

# Check if you have a valid dev certificate
dotnet dev-certs https --check

# A valid certificate was found: A35FA47C1EBA63B150A4D905D91777F79913A7F2 - CN=localhost - Valid from 2025-01-30 13:03:48Z to 2026-01-30 13:03:48Z - IsHttpsDevelopmentCertificate: true - IsExportable: true
# Run the command with both --check and --trust options to ensure that the certificate is not only valid but also trusted.


# Trust the certificate (creates one if missing)
dotnet dev-certs https --trust

# List existing certificates
dotnet dev-certs https --check --verbose

# [1] Listing certificates from CurrentUser\My
# [2] Found certificates: 1 certificate
#     1) A35FA47C1EBA63B150A4D905D91777F79913A7F2 - CN=localhost - Valid from 2025-01-30 13:03:48Z to 2026-01-30 13:03:48Z - IsHttpsDevelopmentCertificate: true - IsExportable: true
# [3] Checking certificates validity
# [4] Valid certificates: 1 certificate
#     1) A35FA47C1EBA63B150A4D905D91777F79913A7F2 - CN=localhost - Valid from 2025-01-30 13:03:48Z to 2026-01-30 13:03:48Z - IsHttpsDevelopmentCertificate: true - IsExportable: true
# [5] Invalid certificates: no certificates
# [6] Finished listing certificates.
# A valid certificate was found: A35FA47C1EBA63B150A4D905D91777F79913A7F2 - CN=localhost - Valid from 2025-01-30 13:03:48Z to 2026-01-30 13:03:48Z - IsHttpsDevelopmentCertificate: true - IsExportable: true
# Run the command with both --check and --trust options to ensure that the certificate is not only valid but also trusted.


# Clean up old/expired certificates
dotnet dev-certs https --clean

# Cleaning HTTPS development certificates from the machine. A prompt might get displayed to confirm the removal of some of the certificates.
# HTTPS development certificates successfully removed from the machine.


# Export certificate for sharing (not recommended)
dotnet dev-certs https --export-path ./dev-cert.pfx --password YourPassword

The --check command shows whether you have a valid certificate:

A valid HTTPS certificate is already present.

If no certificate exists or it’s expired, you’ll see:

No valid certificate found.

How ASP.NET Core Uses Development Certificates

ASP.NET Core automatically configures Kestrel to use your development certificate when running in Development environment. Your launchSettings.json typically includes an HTTPS profile:

{
  "profiles": {
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

When you run dotnet run, Kestrel automatically finds and uses the development certificate for the HTTPS endpoint. No additional configuration required.

Common Issues and Solutions

Browser Still Shows Security Warnings

If you’re getting certificate errors after running --trust, the certificate might be expired or corrupted:

# Clean old certificates and create a fresh one
dotnet dev-certs https --clean
dotnet dev-certs https --trust

macOS Trust Prompt Not Working

On macOS, you might need to manually trust the certificate in Keychain Access if the automatic trust fails:

1. Run dotnet dev-certs https --trust
2. When the system dialog appears, enter your admin password
3. If that fails, open Keychain Access, find “localhost” certificate, and set it to “Always Trust”

gRPC Services Failing with TLS Errors

gRPC requires HTTPS by default. If your gRPC client can’t connect:

# Ensure you have a trusted certificate
dotnet dev-certs https --check --verbose
dotnet dev-certs https --trust

Then configure your gRPC client to use the HTTPS endpoint:

var channel = GrpcChannel.ForAddress("https://localhost:7001");

Certificate Expired After Long Development Break

Development certificates expire after one year. If you see trust errors after not developing for a while:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Available Commands Summary

Troubleshooting Checklist

When HTTPS isn’t working in local development:

1. Check certificate status: dotnet dev-certs https --check --verbose
2. Clean and recreate: dotnet dev-certs https --clean && dotnet dev-certs https --trust
3. Restart browser: Close all browser instances after trusting certificate
4. Verify URL: Make sure you’re using https://localhost:port, not http://
5. Check launchSettings.json: Confirm HTTPS profile is configured correctly

Best Practices for Development Teams

Trust Once Per Machine: Each developer should run dotnet dev-certs https --trust on their local machine. Don’t share certificates between team members.

Don’t Commit Certificates: Never commit development certificates to source control. They’re machine-specific and contain private keys.

Document for New Team Members: Include certificate setup in your project’s README:

## Setup
1. Clone the repository
2. Run `dotnet dev-certs https --trust`
3. Run `dotnet run`

Use Environment-Specific Configuration: Keep HTTPS configuration in launchSettings.json for development, and use proper certificates in production environments.

The dev-certs tool eliminates the friction between local development and HTTPS requirements. When certificate issues arise, the clean-and-trust approach (--clean followed by --trust) resolves most problems. Keep it simple: trust the certificate once per machine, and recreate it when things go wrong.

Frequently Asked Questions

Related Posts

• EF Core Interceptors for Secure, Per-Tenant Audit Logging
• 5 ASP.NET Core DI Scope Mistakes Developers Must Avoid
• SaaS Middleware Anti-Patterns: What Not to Do in ASP.NET Core
• ASP.NET Core: Auth with Middleware or Filters?
• Why Middleware Beats DI for SaaS Extension Points