Forward Client Certificate to .net Core App through Nginx

When dotnet core app is deployed in Linux with Kestrel, nginx works in front as a proxy. Usually, Nginx will handle all https related issue and forward a plain http request to core app. Some app may require clients to use certificate for authentication. In this case, client certificate need to be transferred to core app.

Core App

First, the core app need to be prepared to receive and check the client certificate.

public class StartUp
{
    ...
    public void ConfigureServices(IServiceCollection services)
    {
        ...
        //Add code here
        services.AddCertificateForwarding(options => "X-ARR-ClientCert");
        //PointA - for later reference
    }
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        ...
        //Add code here
        app.UseAuthorization();
        app.UseCertificateForwarding();
        ...
    }
}

Note: UseHttpsRedirection() cannot be used because the core app is set to use http only. UseCertificateForwarding() may expose a security issue, you could set a switch to open it only when required. The header name X-ARR-ClientCert can be changed as your wish.

By default, core app will validate client certificate with local trusted CA. For additional tuning, add this code to the PointA position above.

services.AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme)
    .AddCertificate(options =>
    {
        options.Events = new CertificateAuthenticationEvents
        {
            OnCertificateValidated = aMethod,
            OnAuthenticationFailed = anotherMethod
        };

It is not required to present OnCertificateValidated and OnAuthenticationFailed at the same time. Check this doc for details.

Nginx

Now, in the Nginx setting, some lines need to be added.

Check Certificate with Nginx

When need to check the client certificate by Nginx,

ssl_client_certificate file;
ssl_verify_client on;

is required. The file should contain trusted CA certificates in PEM format. When using multiple CA certificates, write all of them into the same file. When client certificate is not forcible, change on to optional.

Not Check Certificate with Nginx

If we need Nginx to leave the certificate checking to core app, simply use the code

ssl_verify_client optional_no_ca;

in site file. This will let Nginx transfer the client certificate to proxy without touch.

Pass to Proxy

After processing one of those above, the client certificate is ready to be passed into the proxy app — core app. This code below will do that.

proxy_set_header X-ARR-ClientCert $ssl_client_escaped_cert;

If you changed the name X-ARR-ClientCert above, use the same value here. This code can be placed into location block too.

Now you can enjoy your dirty job by checking everything about client certificate in your core app. 😀

Deploy a dotnet core site on nginx and systemd

This article is about how to deploy an ASP.Net core 3.1 site on nginx and systemd.

Preparation:

  • Prepare a server with nginx and systemd.
  • Install dotnet core support on server. Please check Microsoft site for details.
  • Build the binary files of the site to be deployed.

Step 1: Upload files

Make a folder in the server to be used to store site files. This folder will be marked as <SITEPATH> in all files below.

Upload your site files into this folder.

Give the permission to this folder.

sudo chown -R www-data:www-data <SITEPATH>
sudo chmod -R 755 <SITEPATH>

Step 2: Create systemd service

Create a service file. I suggest to put this file in the same folder of the site, aka <SITEPATH>. Let’s name it as myapp. You could change the name.
nano <SITEPATH>/myapp.service and enter this text below:

[Unit]
Description=<A_DESCRIPTION_TEXT_HERE>

[Service]
Environment=ASPNETCORE_URLS=http://localhost:<PORT_NUMBER>
Environment=ASPNETCORE_ENVIRONMENT=Production
WorkingDirectory=<SITEPATH>
ExecStart=/usr/bin/dotnet <SITEPATH>/<ENTRY_FILE>.dll
SyslogIdentifier=<A_NAME_HERE>
Restart=always
RestartSec=10
KillSignal=SIGINT
User=www-data

[Install]
WantedBy=multi-user.target

You should specify the description, port number, site path, entry file (main file), and the name to be used in syslog. Port number need to be different than all used by other services.

Link the file to systemd folder by ln -s <SITEPATH>/myapp.service /etc/systemd/system, reload systemd by systemctl daemon-reload, then start the service by systemctl start myapp.service. If everything goes will, you can see the port is listed in lsof -i -P -n | grep LISTEN. At last, set this service to start with system by systemctl enable myapp.service.

Step 3: Create nginx site.

Create the site file in sites-available folder by nano /etc/nginx/sites-available/<YOUR_SITE_NAME>, and enter this text below:

server {
    listen 80;
    listen [::]:80;
    server_name <SERVER_DOMAIN>;
    
    location / {
        proxy_pass http://localhost:<PORT_NUMBER>;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

You should specify the server domain name and the port number which is chosen for this app.

Link the file to enabled sites by ln -s /etc/nginx/sites-available/<YOUR_SITE_NAME> /etc/nginx/sites-enabled. Test config by nginx -t. If there is nothing wrong, apply the setting by systemctl reload nginx.

Further: Certbot

If you want to use certbot to apply a free ssl certificate to this site, the nginx plugin shipped with certbot can handle that without any problem. Use certbot with the nginx parameter to finish this job: certbot --nginx.