DEV Community: bN

Free Customer Identity Access Management with Azure AD B2C

bN — Fri, 08 Oct 2021 16:43:20 +0000

This article describes how to configure Azure AD B2C to manage identities and access to an application. Thanks to AAD B2C you can allow users to sign-up/sign-in to your application and leverage capabilities like SSO, MFA and email verification without a single line of code. You can also modify users flow to add customized steps on self-service customer registration.

What is a Customer Identity Access Management solution ?

According to Wikipedia, a CIAM is

a subset of the larger concept of identity access management (IAM) and is focused specifically on managing the identities of customers who need access to corporate websites, web portals and webshops. Instead of managing user accounts in every instance of a software application of a company, the identity is managed in a CIAM component, making reuse of the identity possible. The biggest differentiator between CIAM and regular (internal) IAM is that in CIAM the consumers of the service manage their own accounts and profile data.

Main advantages of using a CIAM are:

No need to create and maintain an custom identity server
Customers repository reuse accross multiple applications
Advanced scenarios like MFA, SSO
Last standard compliance in terms of security
Compatibility with many identity providers (Azure AD, Facebook, ...)
User monitoring to detect fraudulent access
GDPR compliance

Create an Azure Active Directory B2C tenant

The first step is to create a new tenant in which we'll register our application. If you don't have an Azure subscription yet, you can create a new one for free. Simply follow steps from this tutorial. Following a little summary:

Don't forget to make sure Microsoft.AzureActiveDirectory is registered as a resource provider in your subscription before creating the resource.

Then go to the home page, click on "Create a resource", find "Azure Active Directory B2C", click on "Create" and "Create a new Azure AD B2C Tenant". Fill the fields and click on "Create".

Once you clicked on the final "create" button, go grab a ☕ because it will take a while ;-)

It would appear quite weird but it seems that the tenant creation is synchronous. So after clicking on "Create", do not leave the page until the creation is finished. Otherwise the creation will be cancelled.

Register a web application

Next we need to register a web application. The registration process will generate an application ID (also known as "client ID") that'll use to uniquely identify our application.

Follow these steps to register a web application. During the process you will create a client secret. Keep it somewhere because we'll need it later.

Client secrets are useful during the development phase or for server-to-server communication when the server storing the secret is in a trusted private place. Please do not store client secrets on the client side (users computer, smartphone, etc.). If you do so, the secret would be exposed and from then should be considered public.

Create user flows and custom policies in Azure Active Directory B2C

Now we will create a user flow to enables a user to sign up and sign in with Facebook. To do this, I'm going to follow this tutorial from Microsoft. The first thing to do is to choose between a standard user flow and a custom policy. With a standard policy you can select a predefined flow. With The custom policy you can go further and personalize the flow as you wish. Let's choose the second option and follow the instructions.

At the time I'm writing this article, there is a certificate issue on www.contoso.com. The certificate is registered for *.oneroute.microsoft.com so it is considered invalid. Since Facebook check the certificate validity of the user data deletion URL, it is not possible to use the URL provided in the tutorial.

I didn't found any useful information concerning this issue on the web, so I created a new issue on azure-docs repo. I hope they will transmit the information to the team in charge of maintaining contoso.com

You can use any valid https URL instead, it doesn't matter for purpose of this tutorial because that URL is only here for legal reasons. For instance you could use https://httpbin.org/.

Tip: setup XML validation in VSCode

At one point of the tutorial, we have to get the custom policy starter pack and modify some XML files in it. In order to prevent dumb errors like typos, we could check the validity of the XML according to the corresponding schema (XSD file). It can be done automatically in VSCode IDE.

Install the XML extension from Red Hat

Open command palette (CTRL+SHIFT+P) and search "Open Settings (JSON)".

In the settings.json file opened, add the following sections:

"xml.symbols.showReferencedGrammars": true,
"xml.fileAssociations": [
{
    "pattern": "TrustFrameworkExtensions.xml",
    "systemId": "TrustFrameworkPolicy_0.3.0.0.xsd"
}

Now if you make a typo, VSCode will tell it to you:

Play with policies

Once you finished the tutorial, you should be able to sign-up using an (email, password) or using Facebook. It is now time to play with policies to see what we can get out of it.

Personaly I'm interested in user migration from a legacy system. After some research over the web I found a very interesting github repository containing dozens of Azure AD B2C samples. And in the list the one I'm interested in: User migration.

Clone the above repository on your computer. To deploy and run this sample we'll need 2 things:

1) An Azure Blob Storage account.
2) A docker image to host the application on Azure. Because the sample is under aspnetcore 2.0.

If you don't have an Azure account yet, your can create one for free and get 200 USD of Azure credits.

Create a storage account

Connect to your Azure account and create a new storage account. Go to "Access keys" menu, click on "Show keys" and copy one of the connection strings.

Open appsettings.json and paste the connection string in the appropriate AppSettings:

"AppSettings": {
    "BlobStorageConnectionString": "<Your connection string to Azure Table that stores your identities to be migrated>"

  }

Create a docker image to publish the sample to Azure

The sample application won't work if you publish it as-is to an Azure Web App because the minimum runtime version is aspnetcore 3.1 and the sample targets 2.0. Hopefully there is Docker to the rescue.

Open the sample in Visual Studio 2019, right-click on the project name in solution explorer and click on "Add docker support". Visual Studio then scaffold a Dockerfile for your project, but there is a little issue. You should see this error message when building the image:

ERROR: pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed

This is because the aspnetcore images have been renamed, so the names of the "base" and "build" image are wrong in Dockerfile. Open Dockerfile and replace microsoft/aspnetcore:2.0 with mcr.microsoft.com/dotnet/core/aspnet:2.2 and microsoft/aspnetcore-build:2.0 with mcr.microsoft.com/dotnet/core/sdk:2.2

Now the image should build normally. If not, check you run the docker build command in the parent folder of the .csproj file. For instance:

~/user-migration/jit-migration-v2/source-code $ docker build -f "AADB2C.JITUserMigration/Dockerfile" .

Right-click on the project in solution explorer and select "Publish...".

Create a new profile targetting Azure App Service Container.

Create a new webapp and a new registry container.

Then click "Publish" and after a few minutes your application is online.

You can now populate the fake database by calling api/test/PopulateMigrationTable on you freshly published API. The endpoint respond with 200 OK and a JSON body content containing the list of users with passwords.

Modify and publish the custom policy

As stated in the sample instructions:

Open the policies files, change the tenant name, client_id and IdTokenAudience for Local Account sign-in, and upload the policies to Azure portal.

There is a little omission here: we also need to modify the URL to the REST API in order to use the webapp we just published instead of the default one.

Open "TrustFrameworkExtensions.xml" and replace http://aadb2cjitusermigrationv2.azurewebsites.net with the URL of your webapp. You can find the URL on the Overview page of your App Service on the Azure portal.

You also have to remove the Google provider from "TrustFrameworkBase.xml" because we do not have registered a Google App, we only have registered a Facebook App.

Switch to your AAD B2C account, go to "Identity Experience Framework" and delete the custom policies we created earlier. Then upload the new ones. The order in which you add them matters because some files depends on the others. So add them in this order.

Test the sign-up/sign-in policy

Select "B2C_1A_JITMIGRAION_SIGNUP_SIGNIN" and click on "Execute now". Enter one of the email address contained in the Azure Table, for instance jeff@contoso.com. Enter the associated password (1234 by default). Then click on "Sign-in".

Our REST API is called to validate the user identity and if it is OK the user is migrated to AAD B2C

and removed from Azure Table.

Request for additional information on sign-up screen

It is not possible to request for additional information on the sign-in screen because SSO requires only 2 informations:

A user unique ID (can be a unique user name, an email or a phone number)
A password

But it is possible to request for additional information during the sign-up process. Imagine you want to add a nickname on the sign-up page. First we have to declare a new claim. Open SocialAndLocalAccounts/TrustFrameworkExtensions.xml and add the following declaration in BuildingBlocks/ClaimsSchema:

<ClaimType Id="nickname">
  <DisplayName>Your nickname</DisplayName>
  <DataType>string</DataType>
  <UserInputType>TextBox</UserInputType>
</ClaimType>

In the same file, find the LocalAccountSignUpWithLogonEmail technical profile and add the following OutputClaim:

<OutputClaim ClaimTypeReferenceId="nickname"/>

If you want to include the nickname in the token's claims, open SocialAndLocalAccounts/SignUpOrSignIn.xml and add the following output claim:

<OutputClaim ClaimTypeReferenceId="nickname" />

Upload the 2 modified policies in IEF and execute the sign-in/sign-up policy. Click on "sign-up" button. You should see a new field "nickname". Fill the fields and create a new account. Once the local account created, you should see the nickname in the returned token claims:

Problem: if you re-execute the sign-in/sign-up policy and now sign-in using your new account, the nickname is not present anymore in the token's claims because it has not been persisted. The question is: how can I make the nickname persistent so it would be added automatically on each sign-in?

You have 2 solutions to handle this:

Store the nickname on you own during sign-up and enrich tokens with claims from external sources using API connectors during sign-in.
Define custom attributes in Azure Active Directory B2C and let AAD B2C store the custom attribute for you.

Just follow the steps described in one of the above article, sign-up a new user, then sign-in and now you should see the nickname in the claims.

Conclusion

AAD B2C is a comprehensive CIAM solution and can allow you to save a lot of time by avoiding you to implement your own identity and SSO provider. Thanks to this, you can focus on your business and deliver more functionalities to your customers while still offering a premium authentication experience.

I am discovering AAD B2C and wrote this article at the same time I was learning about it. I found they were some omission or imprecision in the official documentation. Moreover, the documentation is very intimidating because it is huge. So I thought it could be useful for someone to have a summary of a few AAD B2C features with tips to avoid pitfalls. I barely scratched the surface of what it has to offer and have yet many things to learn. Maybe It'll be worth it to write a second article on this subject when I'll be more experimented on it.

Serve a Single Page Application along with its backend API thanks to NGINX reverse proxy

bN — Sat, 25 Sep 2021 16:42:17 +0000

Thanks to Mudassar Iqbal de Pixabay for the illustration image

In this article, I describe how you can build and host a full website on your own server. The website is composed of an Angular SPA for the front part and an ASP.NET web API for the backend. Everything is described from A to Z and you can find a full working example on my github repository.

If you already know how to setup a SPA with a backend API, feel free to skip the first sections and go directly to Deploy to production.

Prerequisites

Angular CLI
ASP.NET (5+ or core) SDK
A machine with Linux installed (WSL should be OK but not tested)
NGINX
VSCode

You can use whatever version of Angular and .NET core you prefer. You could also scaffold a React web site with a GO backend if you wish. The website and API we'll build are just here for the sake of the demonstration.

Web API

First we need a backend. Let's create a new ASP.NET web api.

$ mkdir webapi
$ cd webapi
$ dotnet new webapi

Let's build and run it.

$ dotnet build
$ dotnet run

Open a web browser and navigate to https://localhost:5001/weatherforecast. You should see a JSON result similar to:

[{"date":"2021-09-26T10:15:16.6511246+02:00","temperatureC":-7,"temperatureF":20,"summary":"Mild"},{"date":"2021-09-27T10:15:16.6512592+02:00","temperatureC":41,"temperatureF":105,"summary":"Freezing"},{"date":"2021-09-28T10:15:16.6512606+02:00","temperatureC":29,"temperatureF":84,"summary":"Scorching"},{"date":"2021-09-29T10:15:16.6512609+02:00","temperatureC":-17,"temperatureF":2,"summary":"Hot"},{"date":"2021-09-30T10:15:16.6512612+02:00","temperatureC":-14,"temperatureF":7,"summary":"Bracing"}]

Dotnet automatically created a controller which returns fake data for us, perfect!

We need a little modification here: for the reverse proxy to be able to distinguish requests intended for the back from requests intended for the front, let's add an "api" segment in the route. Open the project with VSCode:

$ code .

Find WeatherForecastController.cs file and change the route like this:

[Route("api/[controller]")]

Now the route to weather forecast is https://localhost:5001/api/weatherforecast

We need one last modification: in the final version of the website, front and back will be served from the same URL thanks to the reverse proxy. But during the development phase, the backend will be served on port 5001 and the front on port 4200. This will endup with a CORS error.

Access to XMLHttpRequest at 'https://localhost:5001/api/weatherforecast' from origin 'http://localhost:4200' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

So, in order to be able to debug our website locally we need to add CORS headers on the backend side. Hopefully, .NET has a middleware which permits to do it easily. Open the Startup class and add the following at the beginning of ConfigureServices method:

#if DEBUG
    services.AddCors(options =>
    {
        options.AddPolicy("corsPolicy", builder =>
        {
            builder.AllowAnyHeader();
            builder.AllowAnyMethod();
            builder.AllowAnyOrigin();
        });
    });
#endif

The code above registers the CORS middleware and create a policy called "corsPolicy". Now it is registered we can add it to the pipeline. Open the Configure method and add:

app.UseCors("corsPolicy");

Allowing anything could be dangerous, so don't use this configuration in production. You should only allow trusted origins in production. Note the #if pragma which I use to add CORS middleware only in DEBUG configuration.

That's it for the API, now let's build the website.

Website

Let's quickly scaffold a new SPA thank to Angular CLI.

$ ng new website

Here we tell Angular to create a new application called "website".

Follow the instructions and wait for Angular to scaffold the website for you.

? Do you want to enforce stricter type checking and stricter bundle budgets in the workspace?
  This setting helps improve maintainability and catch bugs ahead of time.
  For more information, see https://angular.io/strict Yes
? Would you like to add Angular routing? No
? Which stylesheet format would you like to use? SCSS   [ https://sass-lang.com/documentation/syntax#scss
 ]

Once finished, build the website and launch it to ensure it works.

$ cd website
$ npm install
$ ng build
$ ng serve -o

You should see a page similar to this one:

Now we want our website to call the web API and show the weather forecast. First we need a new constant to store the backend URL. Open environment.ts and add the following:

export const environment = {
  production: false,
  baseUrl: 'https://localhost:5001'
};

Also add baseUrl to environment.prod.ts but keep it empty for now.

We will need the HttpClientModule to call the backend so let's add it. Open app.module.ts and add the import:

import { HttpClientModule } from '@angular/common/http'

Don't forget to register it in the imports section:

imports: [
    BrowserModule,
    HttpClientModule
  ],

Open app.component.ts and modify the content like this:

import { HttpClient } from '@angular/common/http';
import { Component, OnInit } from '@angular/core';
import { environment } from 'src/environments/environment';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {
  forecasts: any;

  constructor(private http: HttpClient) { }

  ngOnInit(): void {
    this.http.get(environment.baseUrl + '/api/weatherforecast')
      .subscribe(data => this.forecasts = data);
  }  
}

Finally, open app.component.html, drop all its content and replace it with:

<div *ngFor="let forecast of forecasts">
 <h1>{{ forecast.date | date }}</h1> 
 <h2>{{ forecast.summary }}</h2>
 <h3>{{ forecast.temperatureC }} celcius degrees</h3>
</div>

Yeah, that's ugly I know, but making a beautiful front is not the purpose of this article. It is just for the sake of the demonstration :)

Deploy to production

Now that we have a "beautiful" website, we're so proud of it that we want to put it on production. So people everywhere in the world could view it. And because we can publish and host it on our own, why wouldn't we do it? So let's start.

Firstly, we'll need a machine with Linux installed on it. If you don't have a machine with Linux on it and don't have time to install one, don't worry: you can install a linux distro directly on windows and leverage Windows Subsystem for Linux. I didn't tested it but that theoretically should work as well. Personally I'm going to host the website on my Raspberry Pi 3 (Debian Stretch).

Create a domain name

In order to make your website easily accessible, you'll need a domain name. It will be very more convenient than typing the public IP address of you server. Moreover, there will be a single static entry point for your website. If your IP address change you'll just have to update it on the DNS et voilà. But it is preferable to request a static IP if you can.

There are plenty of domain name providers, some paid, other free. Choose the one you prefer. Personally I'm going to use Duck DNS.

The setup is pretty easy. First you need to get your public IP. You can grab it very easily, just type "what is my ip" on Microsoft Bing.

Note your public IP and go to Duck DNS. You need to create a free account if you don't have one yet. Choose a domain name, type it and click "add domain".

Then enter your IP address and click "update ip".

Bind you public IP to the local IP of your server

Now every request sent to <your_domain>.duckdns.org will be routed to your public IP address, but there is still a missing piece : you didn't tell your router where to redirect the TCP stream. So the packets are lost because your router do not know where to reroute them.

This part is maybe the trickier one because the setup depends on your internet provider and local network configuration tool supplied by him. So I can't tell you the detailed steps for your specific case. You have to find where to create port redirection rules, also known as "NAT & PAT".

Once you found it, create two rules:

1) One to redirect port 443 from public IP to port 443 on the local server IP (the one that'll host the website, raspberry PI in my case)
2) Another one to redirect port 80 from public IP to port 80 on the same local server. This second one will be useful to automatically setup SSL using Certbot.

Build and publish the web api

Return to webapi folder and type:

$ dotnet publish --configuration=Release

Go to /bin/Release/net5.0/publish/ and copy every files from there to the destination server. You can use ssh and scp for example:

$ ssh pi@192.168.1.25 mkdir /home/pi/fullwebsitedemo-api
$ scp -r ./bin/Release/net5.0/publish/* pi@192.168.1.25:/home/pi/fullwebsitedemo-api/

Microsoft.OpenApi.dll                                                                 100%  170KB   4.2MB/s   00:00
Swashbuckle.AspNetCore.Swagger.dll                                                    100%   16KB 937.5KB/s   00:00
Swashbuckle.AspNetCore.SwaggerGen.dll                                                 100%   79KB   1.6MB/s   00:00
Swashbuckle.AspNetCore.SwaggerUI.dll                                                  100% 3231KB   5.1MB/s   00:00
appsettings.Development.json                                                          100%  162    10.0KB/s   00:00
appsettings.json                                                                      100%  192    12.0KB/s   00:00
web.config                                                                            100%  492    23.7KB/s   00:00
webapi.deps.json                                                                      100%  109KB   2.0MB/s   00:00
webapi.dll                                                                            100%   11KB 609.2KB/s   00:00
webapi.exe                                                                            100%  123KB   2.2MB/s   00:00
webapi.pdb                                                                            100%   20KB   1.1MB/s   00:00
webapi.runtimeconfig.json                                                             100%  304    29.6KB/s   00:00

You can create an RSA key pair and use -i flag instead of typing your password, but it is beyond the scope of this article.

Now that binaries are on the server, we can serve them using Kestrel. The first step is to install .NET5 runtime because it is not installed by default on Debian Stretch. It is pretty straightforward, simply follow the instructions here. You don't need to install the SDK. Unless you plan to compile on the server, the runtime is sufficient.

Next we'll use systemd to create and manage the service, so it will be automatically run at startup and restarted in case of failure.

Create a file named fullwebsitedemo-api.service in your home folder and put this inside:

[Unit]
Description=Full website demo API
After=network-online.target

[Service]
WorkingDirectory=/home/pi/fullwebsitedemo-api
ExecStart=/home/pi/dotnet/dotnet /home/pi/fullwebsitedemo-api/webapi.dll
Restart=always
RestartSec=30
SyslogIdentifier=fullwebsitedemo-api
User=pi
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=ASPNETCORE_URLS=http://0.0.0.0:5002

[Install]
WantedBy=multi-user.target

I'm using port 5002 because I already have another application listening on port 5000 on my Raspberry. You can use any port as soon as it is free and not reserved.

Install and start the service with these commands:

$ sudo systemctl enable /home/pi/fullwebsitedemo-api.service
$ sudo systemctl start fullwebsitedemo-api

To make sure the web api is responding correctly you can test it from the web browser:

http://<local_server_ip>:5002/api/weatherforecast

Build and publish the frontend

Remember the baseUrl constant in our environment.prod.ts file? We left it empty because we didn't had a domain name yet. Now we have to set it before publication. Open the file and fill baseUrl:

export const environment = {
  production: true,
  baseUrl: 'https://<your_domain>.duckdns.org'
};

Then go to website directory and build the application:

$ ng build --prod

And copy files from dist folder to fullwebsitedemo folder on the server:

$ ssh pi@192.168.1.25 mkdir /home/pi/fullwebsitedemo
$ scp -r ./dist/* pi@192.168.1.25:/home/pi/fullwebsitedemo/

Setup NGINX

We are now ready to setup NGINX to serve our website. NGINX will have a few responsibilities:

1) It will serve static files of the frontend and redirect automatically to index.html when a page is not found, ensuring the SPA will work well and refresh correctly (F5).
2) It will act as a reverse proxy allowing us to have only one domain name and a single SSL certificate for both frontend and backend. And moreover: no more CORS issues.
3) It will load the SSL certificate allowing website to work properly over HTTPS.
4) It will enforce SSL by redirecting HTTP to HTTPS automatically.

First you need to install NGINX. Follow the instructions depending on your Linux distro.

Once installed, open nginx.conf file:

$ sudo nano /etc/nginx/nginx.conf

Inside the http section, add a first server section that'll handle SSL redirection:

# ssl redirection
server {
    listen 80 default_server;
    server_name fullwebsitedemo.duckdns.org;
    return 301 https://$host$request_uri;
}

Add a second server section that'll configure the reverse proxy:

server {              
    server_name fullwebsitedemo.duckdns.org;

    # reroute "api" segment to asp.net webapi hosted by Kestrel
    location /api {
        proxy_pass http://localhost:5002;
        proxy_set_header Host $host;
    }

    # serve static files of the SPA
    location / {
        root /home/pi/fullwebsitedemo/website;
        try_files $uri $uri/ /index.html;
        index index.html;
    }
}

Save and close nginx.conf.

Remove the default nginx website otherwise it will conflict with the new default_server you've just defined.

$ rm -f /etc/nginx/sites-enabled/default

Don't be afraid of hardly removing it. There is a copy under /etc/nginx/sites-available.

Setup SSL

The last step is to install an SSL certificate to allow secure (encrypted) communication over HTTPS. It is absolutely mandatory if you want your website to provide some advanced features such as push notifications. Hopefully we can obtain a free SSL certificate thanks to Let's encrypt and set it up automatically thanks to Certbot.

First install Certbot

Certbot will temporarily rewrite nginx.conf to serve a file containing random data (acme challenge) in order to prove you are in control of the domain name for which you want to obtain a certificate. This file will be served statically on http port 80, that's why we had to create a NAT rule above in this article.

When there is no more doubt on the fact you are the owner of the domain, an SSL certificate is issued for your domain name and installed on the server. nginx.conf is automatically modified to load the certificate associated with your website.

Finally restart NGINX:

$ sudo systemctl restart nginx

And after a few seconds your website is up with SSL.

Automatic certificate renewal

Let's encrypt certificate is free but it is valid for only 3 months. So you have to renew it quite regularly if you don't want to encounter issues with your website.

Manually renew each 3 months can be boring and there is a risk of human error with every manual operation.

So there is an ultimate step if you don't want to bother with renewal: automate it. The simpler way to do it is by creating a CRON task.

$ sudo crontab -e

Add the following line at the end of the file:

3 3 * * * certbot renew

With the line above, the command certbot renew will be executed every day at 03:03 AM. If the certificate is about to expire, then a new one will be issued and installed. If not, the command will just do nothing.

Conclusion

If you've made it this far, you should have a better understanding of NGINX, SSL and Certbot. If you have questions, see some mistakes or have any remarks or suggestions, please comment bellow. I hope you've found this article useful and I thank you for reading it.

You can find the full working example at https://github.com/bNobo/FullWebsiteDemo.

Free certified SSL certificate in ASP.NET 5 Kestrel application

bN — Sat, 10 Apr 2021 19:23:04 +0000

Image par skylarvision de Pixabay

As part of a little side project I'm working on, I want to host an ASP.NET Web API on my own server at home. The purpose of this API is to send push notifications to an Angular client application. It is the main reason why I had to set up SSL communication for my web site: service worker needs the communication to be secured by TLS with a valid certificate in order to allow push notications. But that's not the subject of this article. Here I will focus on creating the certificate and loading it into Kestrel.

For the development phase I used a self-signed certificate, but now that I want to deploy it I need a real certificate certified by a certification authority. Because it is not a commercial but personal project I want to keep it entirely free. So I decided to generate a certificate with Let's Encrypt. Until recently, ASP.Net core was only supporting .PFX files and not .PEM files provided by Let's Encrypt. But .NET 5 has rectified the situation in version 5.0.0-preview8.

I could use a reverse-proxy like nginx or haproxy and let it handle the SSL stuff, but I wanted to keep it as simple as possible, so I decided to directly serve it using Kestrel.

Prerequisites

A domain name that you own. Personally I registered to Duck DNS to get a free one.
An ASP.NET web site binded to your domain (to prove you are the owner of the domain)
A bash, preferably Linux ;) but Windows is OK too

Most of Internet providers allow you to configure NAT/PAT and DynDNS, so it should not be a problem to bind your DNS to an open port on a machine in your local network.

Obtain a free certificate

Most of certification authorities sell their certificates and they are expensive. This is because the process of registering often inquires verification made by a human. Hopefully there is Let's Encrypt to the rescue. Let's Encrypt is also a certificate authority but it is nonprofit. It aims to create a more secure and privacy-respecting Web.

The first thing you have to do is to install Certbot. There are many ways to do so depending on your system so I won't go into details. The recommanded way is to use snap. Personnaly I simply made a

$ sudo apt-get install certbot

and it did the job.

Now that you have certbot installed you can generate a new certificate and a private key. Once again there are many ways to do this depending on your server and certbot can be configured to automatically renew your certificate before it expires. Personnaly I used the manual way and will configure autorenew later:

$ sudo certbot certonly --manual

Certbot first ask you what is your domain name and then request you to prove you are in control of it:

Create a file containing just this data:

eZ4dZ4xUrIn7Fkyuy0Vd9giY5FoEPnm5cfGQXs_EDy0.gj7wCMjUoSpRopo7wvqqw5spi23jZdjLjtlCa00Cf2c

And make it available on your web server at this URL:

http://ssldemo.dev.to/.well-known/acme-challenge/eZ4dZ4xUrIn7Fkyuy0Vd9giY5FoEPnm5cfGQXs_EDy0

Modify your website to make the file available at the requested URL and then press ENTER. Certbot will download the file and verify that the content matches with what was requested. It will then issue a new certificate associated with your domain name and the private key used to sign the certicate. Files are created under

/etc/letsencrypt/live/ssldemo.dev.to/fullchain.pem
/etc/letsencrypt/live/ssldemo.dev.to/privkey.pem

Copy these two files in a secure place on the machine hosting your website and make sure no one can access them except your web application.

Kestrel configuration

Make sure your website application target at least .NET 5.0. You should have <TargetFramework>net5.0</TargetFramework> in your .csproj file.

You now have to instruct Kestrel how to load your certificate. Open appsetting.json file and add a Kestrel section :

  "Kestrel": {
    "Certificates": {
      "Default": {
        "Path": "path/to/fullchain.pem",
        "KeyPath": "path/to/privkey.pem"
      }
    }
  }

You could also use environment variables if you prefer

And that's it ! The method ConfigureWebHostDefaults uses Kestrel as the web server so it will use the Kestrel section to configure itself. Just make sure you load appsettings.json at startup (it is the case by default when you use CreateDefaultBuilder). Thus, the provided SSL certificate and the private key will be loaded and used by your server. If you don't use ConfigureWebHostDefaults then ensure that you have UseKestrel on your webBuilder and it should be OK.

Now when you request your web API via HTTPS you should see a valid certificate in the address bar of your web browser:

Conclusion

I wrote this article because I didn't find many documentation on how to configure Kestrel to load PEM SSL certificate. It is my first article and I hope you will find it interesting, maybe even usefull.

If you are interested in, you can find the source code of my current side-project for which I had to load PEM SSL certificate in Kestrel.

https://github.com/bNobo/wind-forecast-api : the web API
https://github.com/bNobo/wind-forecast-website : the Angular client