Docker & ASP.NET Core 9: Trust Self-Signed Certificates

Aug 29, 2025 by Marco 56 views

Introduction

Hey guys! Ever wrestled with getting your Dockerized ASP.NET Core 9 Web APIs to play nice with self-signed certificates? It's a common head-scratcher, especially when you're dealing with microservices that need to authenticate each other. Imagine you've got an Identity API (think OpenIddict server) dishing out JWT tokens, and a Voucher API that's all about validating those tokens using AddJwtBearer. But, uh oh, you're using self-signed certificates, and things aren't quite clicking. Don't worry, you're not alone! This article will walk you through the ins and outs of making your ASP.NET Core 9 Web API trust those self-signed certs when running in Docker. We'll break down the problem, explore the solutions, and get you up and running in no time. We will explore the intricacies of configuring your Docker containers and ASP.NET Core applications to seamlessly trust self-signed certificates. By understanding the underlying issues and implementing the appropriate solutions, you can ensure secure communication between your microservices, even in a development or testing environment where self-signed certificates are commonly used. So, grab your favorite beverage, fire up your IDE, and let's dive into the world of Docker, ASP.NET Core, and self-signed certificates! By the end of this guide, you'll be equipped with the knowledge and tools to confidently tackle this challenge and build secure, reliable microservices. So, let’s buckle up and dive deep into this intriguing topic. We'll cover everything from the basics of self-signed certificates to the nitty-gritty details of configuring your Docker environment and ASP.NET Core applications.

The Scenario: Identity API and Voucher API

Let's set the stage. We've got two ASP.NET Core 9 Web APIs chilling in Docker containers:

Identity API (OpenIddict server): This guy is the token master, issuing JWT tokens like they're going out of style. It's the gatekeeper, ensuring only authorized users and services can access your precious resources. Think of it as the bouncer at the coolest club in town, only letting in those with the right credentials. The Identity API is responsible for authenticating users and issuing JSON Web Tokens (JWTs), which are then used by other services to verify the identity of the user or application making the request. It leverages OpenIddict, a popular open-source library for implementing OpenID Connect and OAuth 2.0 flows in ASP.NET Core applications. This setup allows for a secure and standardized way to manage authentication and authorization across your microservices architecture.
Voucher API (protected resource): This one's a vault, guarding valuable resources. It's super picky, validating JWT tokens using AddJwtBearer to make sure only legit requests get through. It's the treasure chest, ensuring only those with the correct keys (JWT tokens) can access its contents. The Voucher API, on the other hand, acts as a protected resource, requiring valid JWT tokens to access its endpoints. It utilizes the AddJwtBearer authentication scheme to validate incoming tokens against the Identity API's configuration. This ensures that only authenticated users or services with valid tokens can access the resources exposed by the Voucher API. This architecture promotes a secure and decoupled system, where each service has a clear responsibility and can operate independently. The use of JWTs allows for efficient and stateless authentication, as the necessary information is contained within the token itself, eliminating the need for frequent database lookups. This also makes the system more scalable and resilient, as the Voucher API does not need to directly communicate with the Identity API for every request.

The kicker? Both APIs are using self-signed certificates for SSL/TLS. Great for development, not so great when you need them to trust each other!

The Problem: Trust Issues

Here's the deal: by default, your ASP.NET Core application running in Docker doesn't trust self-signed certificates. It's like trying to get into a VIP party without an invitation – the bouncer (in this case, the SSL/TLS handshake) is going to give you the side-eye. When the Voucher API tries to validate the JWT token issued by the Identity API, it encounters an SSL/TLS error because it doesn't trust the self-signed certificate used by the Identity API. This is a security measure to prevent man-in-the-middle attacks, where an attacker could intercept and modify the communication between the two services. However, in a development or testing environment, self-signed certificates are often used to avoid the cost and complexity of obtaining certificates from a trusted Certificate Authority (CA). This means we need to explicitly tell the Voucher API to trust the self-signed certificate used by the Identity API. There are several ways to achieve this, each with its own trade-offs in terms of security and complexity. The most common approach is to import the certificate into the trusted root certificate store within the Docker container running the Voucher API. This effectively tells the container that the self-signed certificate should be treated as if it were issued by a trusted CA. Another approach is to configure the HttpClient used by the Voucher API to bypass certificate validation for the specific endpoint of the Identity API. This is a less secure approach, as it disables certificate validation altogether, but it can be useful in certain situations where importing the certificate is not feasible. Choosing the right approach depends on the specific requirements of your application and the level of security you need to achieve.

Solution 1: Importing the Certificate into the Docker Container

One way to solve this trust issue is to import the Identity API's self-signed certificate into the trusted root certificate store within the Docker container running the Voucher API. Think of it as giving the Voucher API the secret handshake so it knows the Identity API is legit. This is a secure and recommended approach for development and testing environments. It involves copying the certificate file into the container and then using the update-ca-certificates command to add it to the trusted store. This ensures that the Voucher API will trust the certificate issued by the Identity API, allowing for secure communication between the two services. This method involves several steps, including extracting the certificate from the Identity API, copying it to the Voucher API's Dockerfile context, and then adding commands to the Dockerfile to import the certificate during the build process. While it may seem a bit involved at first, it's a robust and reliable solution that provides a good balance between security and ease of implementation. Once the certificate is imported, the Voucher API will be able to communicate with the Identity API without encountering SSL/TLS errors, allowing for seamless authentication and authorization.

Steps:

Export the certificate: Grab the Identity API's certificate (usually a .crt or .pem file). You might need to export it from your development environment or generate it if you haven't already. This typically involves using a tool like openssl or the certificate management features of your operating system. The specific steps will depend on how the certificate was originally created and stored. For example, if the certificate was generated using openssl, you can use the openssl x509 command to export it in PEM format. If the certificate is stored in the Windows Certificate Store, you can use the Certificate Manager (certmgr.msc) to export it. It's important to choose the appropriate format for the certificate file, as different systems and applications may have different requirements. PEM format is a common and widely supported format, but other formats like DER may also be used. Make sure to choose the format that is compatible with the tools and libraries you will be using to import the certificate into the Docker container.
Copy the certificate: Add the certificate to the Dockerfile context for the Voucher API. This means placing the certificate file in the same directory as your Dockerfile or in a subdirectory that will be included in the Docker image. This ensures that the certificate file is available during the Docker image build process. It's important to organize your Dockerfile context in a way that makes it easy to manage your files and dependencies. You can create separate directories for different types of files, such as certificates, configuration files, and application code. This will help to keep your Dockerfile clean and organized, making it easier to understand and maintain. When copying the certificate file, you can use the COPY instruction in the Dockerfile to add it to the image. You should also consider the security implications of storing sensitive files like certificates in your Docker image. It's generally recommended to avoid storing private keys in the image, as they could be exposed if the image is compromised. If you need to use a private key, you should consider using a more secure method, such as mounting it as a volume at runtime or using a secret management service.
Update the Dockerfile: Modify the Voucher API's Dockerfile to copy the certificate into the container and update the trusted certificates store. This is the crucial step where you tell the Docker container to trust the self-signed certificate. You'll typically use the COPY instruction to copy the certificate file into the container and then run the update-ca-certificates command to add it to the trusted store. The update-ca-certificates command is a standard Linux utility that updates the system's list of trusted Certificate Authorities. It reads the certificate files in the /usr/local/share/ca-certificates directory and adds them to the system's trust store. This ensures that applications running within the container will trust the certificates issued by these CAs. In your Dockerfile, you'll need to use the RUN instruction to execute the update-ca-certificates command. You should also specify the correct path to the certificate file within the container. For example, if you copied the certificate file to /usr/local/share/ca-certificates/identity-api.crt, the RUN instruction would look like this: RUN update-ca-certificates. This command will add the certificate to the trusted store, allowing the Voucher API to communicate with the Identity API without SSL/TLS errors. Remember to rebuild your Docker image after making these changes to the Dockerfile.
```
FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

COPY identity-api.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
...
```
Rebuild and run: Rebuild your Docker image for the Voucher API and run the container. This will incorporate the changes you made to the Dockerfile, including the certificate import. Once the container is running, the Voucher API should be able to communicate with the Identity API without any SSL/TLS errors. It's important to test the connection between the two services to ensure that the certificate import was successful. You can do this by sending a request from the Voucher API to the Identity API and verifying that the response is received without any errors. If you encounter any issues, you can check the logs for both services to see if there are any error messages related to certificate validation. You can also use tools like openssl to verify the certificate chain and ensure that the certificate is being trusted by the system. By following these steps, you can ensure that your Dockerized ASP.NET Core applications can communicate securely using self-signed certificates in a development or testing environment. This is a crucial step in building a secure and reliable microservices architecture.

Solution 2: Configuring HttpClient to Ignore Certificate Validation (Less Secure)

Okay, this method is like sneaking in through the back door. It involves telling the HttpClient in your Voucher API to basically ignore certificate validation. This is generally not recommended for production environments because it opens you up to potential security risks. However, it can be a quick and dirty fix for development purposes, so it's worth knowing about. The main risk with this approach is that it disables certificate validation, which means that your application will not be able to verify the identity of the server it is communicating with. This could allow an attacker to intercept the communication and impersonate the server, potentially stealing sensitive data or injecting malicious code. Therefore, it's crucial to use this approach only in controlled environments where the risks are well understood and mitigated. For example, you might use this approach in a local development environment where you are the only user and you are not communicating with any external services. In such a scenario, the risk of an attack is minimal. However, if you are deploying your application to a shared environment or communicating with external services, you should always use proper certificate validation to ensure the security of your application. This involves obtaining a valid certificate from a trusted Certificate Authority (CA) and configuring your application to verify the certificate of the server it is communicating with. There are several ways to configure the HttpClient to ignore certificate validation, each with its own trade-offs in terms of security and complexity. The most common approach is to use a custom HttpClientHandler that overrides the ServerCertificateCustomValidationCallback property. This allows you to specify a custom validation logic that always returns true, effectively disabling certificate validation. However, this approach should be used with caution, as it can create security vulnerabilities if not implemented correctly. Another approach is to use a SocketsHttpHandler and configure the SslOptions property to disable certificate validation. This approach is more modern and efficient than using HttpClientHandler, but it also requires more configuration. Regardless of the approach you choose, it's important to understand the risks involved and take appropriate measures to mitigate them. If you are unsure about how to configure your HttpClient securely, it's best to consult with a security expert.

Steps:

Create a custom HttpClientHandler: You'll need to create a custom handler that overrides the certificate validation logic. This is where the magic (or the potential danger) happens. The HttpClientHandler is a class in .NET that provides the underlying implementation for sending HTTP requests. It handles things like connection pooling, proxy settings, and certificate validation. By creating a custom handler, you can override the default behavior and customize how HTTP requests are sent and received. In this case, we're interested in overriding the certificate validation logic. The default HttpClientHandler validates the server's certificate against the list of trusted root certificates on the system. If the certificate is not trusted, the request will fail. By overriding the ServerCertificateCustomValidationCallback property, we can provide our own validation logic. This callback is invoked whenever the HttpClientHandler needs to validate a certificate. The callback receives the certificate, the certificate chain, and any SSL policy errors. It should return true if the certificate is valid and false otherwise. In our case, we want to disable certificate validation, so we'll create a callback that always returns true. This effectively tells the HttpClientHandler to trust any certificate, regardless of whether it's valid or not. While this is a quick way to disable certificate validation, it's important to understand the security implications. By disabling certificate validation, you are essentially trusting any server that you connect to, which could expose your application to man-in-the-middle attacks. Therefore, this approach should only be used in development or testing environments where the risks are well understood and mitigated.
```
var handler = new HttpClientHandler();
```

handler.ServerCertificateCustomValidationCallback = (message, cert, chain, errors) => { return true; }; ```

Create an HttpClient with the handler: Now, use this handler when creating your HttpClient instance. This ensures that the custom certificate validation logic is used for all requests made by this client. The HttpClient is a class in .NET that provides a high-level API for sending HTTP requests. It encapsulates the underlying details of the HTTP protocol and provides a simple and convenient way to interact with web services. When you create an HttpClient instance, you can optionally pass in an HttpClientHandler. This allows you to customize the behavior of the client, such as setting proxy settings, connection timeouts, and, in our case, certificate validation logic. By passing in our custom HttpClientHandler that disables certificate validation, we are telling the HttpClient to use our custom logic instead of the default validation logic. This means that the HttpClient will trust any certificate, regardless of whether it's valid or not. This is a powerful way to customize the behavior of the HttpClient, but it's important to use it with caution. As mentioned earlier, disabling certificate validation can create security vulnerabilities, so it should only be used in development or testing environments where the risks are well understood and mitigated. When creating the HttpClient with the handler, you can use the HttpClient constructor that takes an HttpMessageHandler as a parameter. The HttpClientHandler is a type of HttpMessageHandler, so you can pass it directly to the constructor.
```
var client = new HttpClient(handler);
```
Use the HttpClient: Make your requests using this HttpClient instance. Now your Voucher API will happily talk to the Identity API, even with the self-signed certificate. With the HttpClient configured to use the custom handler that ignores certificate validation, your application can now communicate with the Identity API without any SSL/TLS errors. This is because the HttpClient will no longer attempt to validate the server's certificate, effectively trusting any certificate presented by the server. While this may seem like a convenient solution, it's crucial to remember the security implications. By disabling certificate validation, you are essentially trusting any server that you connect to, which could expose your application to man-in-the-middle attacks. Therefore, this approach should only be used in development or testing environments where the risks are well understood and mitigated. In a production environment, you should always use proper certificate validation to ensure the security of your application. This involves obtaining a valid certificate from a trusted Certificate Authority (CA) and configuring your application to verify the certificate of the server it is communicating with. If you are using this approach in a development or testing environment, it's important to ensure that the environment is isolated and that there is no risk of external attacks. You should also consider using a more secure approach, such as importing the certificate into the trusted root certificate store, if possible. This will provide a higher level of security while still allowing you to communicate with the Identity API using a self-signed certificate. Remember, security should always be a top priority when developing and deploying applications.
```
var response = await client.GetAsync(
```