How to Use Wildcard Certificates in Caddy and Configure Reverse Proxies

Setting up wildcard certificates is crucial when you're managing multiple subdomains under the same domain. Instead of generating individual certificates for each subdomain, wildcard certificates simplify things by covering all subdomains with one certificate. In this post, we’ll explore how to configure Caddy to use wildcard certificates, including the setup of reverse proxies for multiple services and an explanation of Caddy’s handle and abort directives.

What is a Wildcard Certificate?

A wildcard certificate allows you to secure multiple subdomains under one certificate. For example, if you have a domain like example.com, a wildcard certificate for *.example.com will secure sub.example.com, api.example.com, and any other subdomain.

Caddy makes managing wildcard certificates easy because it integrates with ACME (Automated Certificate Management Environment), automatically handling certificate issuance, renewal, and storage. When using services like Cloudflare for DNS management, Caddy can even issue wildcard certificates by handling DNS-based validation behind the scenes.

Why Use Wildcard Certificates?

• Simplified Management: You only need one certificate for multiple subdomains, reducing the complexity of managing many certificates.
• Automatic Issuance and Renewal: Caddy automates the entire process, so you don't have to worry about manually renewing certificates.
• Secure Multiple Services: By using reverse proxies with wildcard certificates, you can securely route requests to different services hosted on different subdomains.

Setting Up Caddy with Wildcard Certificates

To configure wildcard certificates in Caddy, you need to ensure that Caddy can access your DNS provider’s API to verify domain ownership. We’ll be using Cloudflare as an example here, but you can use any supported DNS provider.

Step 1: API Access for DNS Validation

You'll need to get your API token from Cloudflare. Follow these steps:

1. Log in to Cloudflare.
2. Navigate to My Profile → API Tokens.
3. Create a new API token with DNS:Edit permissions.
4. Copy your API token for use in the Caddy configuration.

Note: You can use it without Cloudflare too. It would also work any other providers such as duckdns, dynu etc.

Step 2: Create Your Caddyfile

Here’s how to set up a basic Caddyfile for wildcard certificate usage and reverse proxying.

{
  acme_dns cloudflare {$CLOUDFLARE_API_TOKEN}
}

{$MY_DOMAIN} {
    reverse_proxy homer:8080
}

*.{$MY_DOMAIN} {
    encode gzip
    tls {
		protocols tls1.2 tls1.3
		ciphers TLS_AES_128_GCM_SHA256 TLS_CHACHA20_POLY1305_SHA256
	}
    @a host a.{$MY_DOMAIN}
    handle @a {
        reverse_proxy whoami:80
    }

    @b host b.{$MY_DOMAIN}
    handle @b {
        reverse_proxy nginx:80
    }

    handle {
        abort
    }
}

Step 3: Explanation of the Caddyfile

Let’s break down the Caddyfile step by step:

Global Options Block { ... }

The top-level block defines global settings for Caddy. Here, the key directive is acme_dns, which tells Caddy to use DNS-based validation with Cloudflare for issuing wildcard certificates. You pass the Cloudflare API token as an environment variable ({$CLOUDFLARE_API_TOKEN}).

Domain-Specific Configuration

The next two blocks are domain-specific:

1. Wildcard Certificate Block (*.{$MY_DOMAIN}):
   • This line tells Caddy to issue a wildcard certificate for the domain and all its subdomains (e.g., a.example.com, b.example.com).
   • Requests matching subdomains will be handled by the reverse proxy rules defined in the block.
2. Reverse Proxying Services:
   • Subdomain a.{$MY_DOMAIN}: The @a directive matches requests for a.{$MY_DOMAIN} and proxies them to the service running at whoami:80.
   • Subdomain b.{$MY_DOMAIN}: The @b directive matches requests for b.{$MY_DOMAIN} and proxies them to an Nginx service running at nginx:80.

The handle and abort Directives

The use of handle groups multiple directives under one match condition. For example, the handle @a block ensures that any request to a.{$MY_DOMAIN} is processed by the reverse proxy rule pointing to whoami:80.

Here’s where the abort directive comes into play. The final handle { abort } block serves as a catch-all for any requests that don’t match @a or @b. If someone tries to access an unsupported subdomain (e.g., c.{$MY_DOMAIN}), Caddy will immediately terminate the connection without responding, which could be useful for blocking unwanted requests.

• handle: This is a grouping directive that allows you to define how a request matching specific conditions should be handled.
• abort: This tells Caddy to drop the connection without responding. It’s useful to prevent access to undefined subdomains or for security reasons.

Step 4: Run Caddy

After configuring your Caddyfile, run the following command to start the Caddy server:

In cmd

caddy run --config Caddyfile

In Powershell:

./caddy run --config Caddyfile

Caddy will automatically issue and install the wildcard certificate, and the reverse proxies for a.{$MY_DOMAIN} and b.{$MY_DOMAIN} will be functional.

Conclusion

With Caddy, managing wildcard certificates and reverse proxies is incredibly simple. In this setup, you’ve not only secured multiple subdomains using a wildcard certificate but also routed traffic to different services based on the subdomain used. The handle and abort directives provide additional control, ensuring that only the intended subdomains are accessible while gracefully rejecting others.

Wildcard certificates are a powerful tool for anyone managing several services under one domain, and Caddy’s automation makes this process seamless.

If you have any questions or want to explore more advanced features of Caddy, feel free to leave a comment below!