DEV Community: Robin van der Knaap

How to deploy a static website to a $4 Droplet at DigitalOcean

Robin van der Knaap — Wed, 23 Oct 2024 15:19:19 +0000

This guide describes how to deploy a static website to a $4 Droplet at DigitalOcean. We will be using Nginx to serve our website and Certbot to manage TLS certificates issued by Let's Encrypt. Finally, we setup GitHub Actions to automate the deployment of the website.

Easier alternatives to deploy and host static websites are available of course, most notably Cloudflare Pages, Netlify, Vercel and Render. But sometimes you want to have close control over your webserver, or you don't want these parties to manage your DNS, which is usually required. In that case, managing your own server at is a great solution. I like DigitalOcean for hosting my virtual machines (called Droplets), but with a little imagination you can apply this guide to any other provider of virtual machines.

Prerequisites

DigitalOcean account.
GitHub account, if you want to automatically deploy your website using GitHub Actions.
SSH client, which is usually already available in your OS.
Domain name and access to DNS.

Setup Droplet

SSH key pair

Droplets can be accessed using SSH. Before we create a Droplet in the DigitalOcean Control Panel, we need to make sure we have a valid SSH key pair installed on our local machine and upload the public key to DigitalOcean.

It is also possible to access the Droplet using username and password, but this is not recommended, access via SSH is much more secure.

Use this article to create a SSH key-pair if you don't already have one and make sure it is added to your SSH agent (which is described in the same article). For this guide I use a SSH key-pair without a passphrase.

Use the Add SSH Key button:

You need to add the public key of your SSH key-pair. You can get the content of the public key like this in your terminal:

cat ~/.ssh/name-of-your-key.pub

Copy-paste the output inside the Public Key field and give the key a proper name, so you can identify it later on.

Create Droplet

Now we are ready to create a new Droplet using the 'Create' button in the header of the Control Panel. Select the following properties:

Region and datacenter: Select the region and datacenter that's nearest to your customers
Use the default VPC
Image: Ubuntu latest version
Droplet type: Basic
CPU options:
- Regular, Disktype SSD
- $4 per month instance (scroll to the left to make it visible)
Authentication method: SSH Key
- Pick the SSH key you have just uploaded
Add improved metrics monitoring and alerting (it's free)
Advanced options (expand to reveal the IPv6 option)
- Enable IPv6 (doing this later requires manual configuration)
Quantity: 1 Droplet
Specify a proper host name so you can easily identify the Droplet in your Control Panel

Use the 'Create Droplet' button to start the provisioning of the Droplet.

Reserved IP

When the Droplet is created, it is assigned an IPv4 address automatically. In case our Droplet becomes unstable and we want to create a new one, we want to have a fixed IPv4 address so we don't have to update our DNS.

DigitalOcean offers this service in the form of Reserved IP addresses. This is a free service as long as your reserved IP is assigned to a Droplet. Due to shortages in IPv$ addresses, DigitalOcean wants to prevent holding on to unused IPv4 addresses, and makes you pay for a reserved IP when you don't use it.

Visit your Droplet in the Control Panel and select enable now next to the Reserved IP label.

Follow the instructions. Once the reserved ip is created, we can use it to update the DNS.

Reserved IPv6 addresses are not supported by DigitalOcean, in case of a change we need to manually update the DNS for IPv6 addresses.

Update DNS

Visit your DNS provider and add the following records to the DNS (you can skip the records for the www sub-domain if you want, especially if you are deploying to a sub-domain instead of a root domain):

A record for your-domain pointing to the reserved IPv4 address
A record for www.your-domain pointing to the reserved IPv4 address
AAAA record for your-domain pointing to the IPv6 address
AAAA record for www.your-domain pointing to the IPv6 address

The A records are for IPv4 traffic, this will be the bulk of your visitors and AAAA records are for IPv6 traffic.

You could also add CAA records for making sure only Let's Encrypt is allowed to issue certificates for this domain. I'll skip this for now, because adding the correct values of CAA records differ per DNS provider. I don't want you to get stuck later on in this guide when we setup a certificate, due to incorrect CAA DNS records.

Access Droplet using SSH

To access your droplet, you can now use SSH to connect:

ssh root@your-reserved-ip-address

or when the DNS changes are propagated:

ssh root@your-domain

Firewall

After accessing the Droplet, the first thing we need to do is enable the firewall. We could use DigitalOcean's firewall, but we'll be using the UFW firewall that is installed with Ubuntu. It's not recommended to use both.

Before we enable the firewall, we need to allow OpenSSH access, otherwise we lock ourselves out:

ufw allow OpenSSH

Now we can enable the firewall:

ufw enable

Unattended upgrades

Make sure Unattended upgrades is enabled in order to automatically retrieve and install security patches and other essential upgrades for your server.

systemctl status unattended-upgrades.service

If you want to allow reboots after updates, you need to edit the configuration file of the Unattended Updates Service to enable reboots when required. This is usually the case when the kernel is updated:

nano /etc/apt/apt.conf.d/50unattended-upgrades

Find the line Unattended-Upgrade::Automatic-Reboot, uncomment and set to true:

// Automatically reboot *WITHOUT CONFIRMATION* if
//  the file /var/run/reboot-required is found after the upgrade
Unattended-Upgrade::Automatic-Reboot "true";

Save and close the file by pressing Ctrl+X to exit, then when prompted to save, Y and hit Enter.

Restart the Unattended Updates service:

systemctl restart unattended-upgrades.service

More information on the Unattended Upgrades Service: https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/

Install and configure Nginx

Install

Make sure you are connected to your Droplet via SSH and use the following commands to install Nginx:

apt update
apt install nginx

Update firewall

We need to allow Nginx to pass through the firewall. Applications can register their profiles with UFW upon installation. These profiles allow UFW to manage these applications by name. Nginx also registers its profile upon installation. You can list the available applications like this:

ufw app list

We will allow Nginx Full, which contains both HTTP and HTTPS connections:

ufw allow 'NGINX Full'

Use the following command to view the current status of the firewall

ufw status

The status should show that OpenSSH and Nginx FULL are allowed on the firewall for both IPv4 and IPv6 addresses.

If you browse to http://your-domain you should see the Nginx welcome message.

Sometimes the browser forces you to use HTTPS, and you cannot view the website yet. Don't worry, when the certificate is installed, it will work. In the mean time you can use curl to view the HTML:

curl your-domain

Configuration

With the Nginx web server, server blocks can be used to host more than one domain from a single server.

We leave the default server block in place to be served if a client request does not match any other site. We will set up a new server block for our domain.

Make you sure you are logged into your server and create a folder for your domain which will contain the the website's content:

mkdir -p /var/www/your-domain/html

Create a sample index.html file:

nano /var/www/your-domain/html/index.html

Add some content:

<html>
    <head>
        <title>Yes</title>
    </head>
    <body>
        <p>It's working</p>
    </body>
</html>

Save and close the file by pressing Ctrl+X to exit, then when prompted to save, Y and hit Enter.

In order for Nginx to serve this content, we also need to create a configuration file containing the server block:

nano /etc/nginx/sites-available/your-domain

Configuration is almost the same as the default server block, except for the root directory and the server name:

server {
    listen 80;
    listen [::]:80;

    root /var/www/your-domain/html;
    index index.html;

    server_name your-domain www.your-domain;

    location / {
        try_files $uri $uri/ =404;
    }
}

Don't forget to update the configuration with the correct domain name. I've included a variant with the www subdomain, if your are not using the www sub-domain, you can leave it out of the configuration file.

Enable the server block by creating a symlink of the configuration file to the sites-enabled directory, which Nginx reads from during startup:

ln -s /etc/nginx/sites-available/your-domain /etc/nginx/sites-enabled/

Nginx uses a common practice called symbolic links, or symlinks, to track which of your server blocks are enabled. Creating a symlink is like creating a shortcut on disk, so that you could later delete the shortcut from the sites-enabled directory while keeping the server block in sites-available if you wanted to enable it.>

Now restart Nginx to apply the new configuration

systemctl restart nginx

Check http://your-domain with your browser or curl, you should see the 'it's working' message.

Certbot

We haven't installed a TLS certificate yet. We'll be using Certbot to provision a certificate from Let's Encrypt.

Install Certbot

We install Certbot using snap, this is the recommended way. Snap automatically updates Certbot. Source: https://certbot.eff.org/.

snap install --classic certbot

Execute the following instruction in the terminal of the server to ensure that the certbot command can be run.

ln -s /snap/bin/certbot /usr/bin/certbot

Provision certificate

Certbot needs to be able to find the correct server block in our Nginx configuration for it to be able to automatically configure TLS. Specifically, it does this by looking for a server_name directive that matches the domain you request a certificate for. The server_name is defined in our server configuration file, it's called your-domain and www.your-domain.

Use Certbot to provision the certificate (skip the www domain if you are not using it):

certbot --nginx -d your-domain -d www.your-domain

Enter the email address at which you want to receive urgent renewal and security notices from Letsencrypt. Accept the terms and the provisioning of the certificate starts.

Visit https://your-domain in the browser, you should be able to connect via HTTPS now.

You can test the certificate at https://www.ssllabs.com/ssltest/. You should receive an A grade, which is nice for a change.

Auto renew cert

Let’s Encrypt’s certificates are only valid for ninety days. This is to encourage users to automate their certificate renewal process. The Certbot packages on your system come with a cron job or systemd timer that will renew your certificates automatically before they expire. You will not need to run Certbot again, unless you change your configuration. You can test automatic renewal for your certificates by running this command:

certbot renew --dry-run

Security headers

To tighten security we can add some response headers to our server configuration file. We will add the following headers:

Strict-Transport-Security: Forces a web browser to connect directly via HTTPS when revisiting your website. This helps preventing man-in-the-middle attacks. Also known as HSTS.
X-Content-Type-Options: Avoids mime sniffing
Referrer-Policy: Controls how much referrer information (sent with the Referer header) should be included with requests.
X-Frame-Options: Used to indicate whether a browser should be allowed to render a page in a frame.
Content-Security-Policy: Helps to detect and mitigate certain types of attacks, including Cross-Site Scripting (XSS) and data injection attacks.

Edit the server configuration file for you domain:

nano /etc/nginx/sites-available/your-domain

You may notice the config has been altered by Certbot to allow for HTTPS traffic.

Add the following headers in the server section where the root is specified, you can add it after the location block:

add_header Strict-Transport-Security "max-age=31536000" always;
add_header X-Content-Type-Options "nosniff";
add_header Referrer-Policy "same-origin";
add_header X-Frame-Options "DENY";
add_header Content-Security-Policy "default-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action none;";

Restart Nginx for the changes to take effect:

systemctl restart nginx

Use a tool like internet.nl to test the configuration of your web server for security issues.

With a real website, you will probably have to alter the Content-Security-Policy (CSP) to allow for loading assets from certain external sources.

Content

Now that the web server is up-and-running and correctly configured, you can copy the content of your static site from your local machine. We will automate this later with GitHub Actions, but for now we do it manually.

Let's create an example website on your local machine. Start with creating a folder which will contain the content. Make sure you are working on you local machine, exit the ssh session if you are still working on the server.

mkdir my-awesome-website

Create the index.html as welcome message

touch ./my-awesome-website/index.html

Add the following content to your index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My awesome website</title>
  </head>
  <body>
    <h1>This is where the magic happens</h1>
  </body>
</html>

Our website is ready, we can copy the content from the folder to the server like this (run this command from your local machine, not when logged into your server):

rsync -a ./my-awesome-website/ root@your-domain:/var/www/your-domain/html

If you visit your domain in the browser, you should see your site now.

Instead of using the example website, you can point rsync to the folder with your own content to send it to the server. Make sure you have all the content you want to deploy in one folder. Most static site generators have an output folder which you can use.

Custom error pages

Nginx includes some default error pages, usually you want to serve your own error pages.

First create a custom error page on your local machine

touch ./my-awesome-website/404.html

Add some content

<h1>404 - You are definitely in the wrong place</h1>

Update your website with the same rsync command we used before:

rsync -a ./my-awesome-website/ root@your-domain:/var/www/your-domain/html

For Nginx to use your custom error page, you need to change the server configuration of your domain to point to the 404 page in your content. Make sure you logged into the server and edit the configuration:

nano /etc/nginx/sites-available/your-domain

Add the following to the server configuration in the same block as the security headers (don't forget to use your own domain):

error_page 404 /404.html;
location = /404.html {
    root /var/www/your-domain/html;
    internal;
}

Restart Nginx

systemctl restart nginx

The 404 page should be showing now. You can repeat this process for other status codes, like 500 - Internal Server Error.

GitHub Actions

Instead of copying the content manually every time we want to update the site, it's better to automate the deployment. We can use GitHub Actions for this, if your code is hosted at GitHub.

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate all kinds of software tasks, like building and deploying your website. You can create workflows that are triggered whenever you push a change to your repository.

First, we will to add our code to GitHub. If you already host your code at GitHub you can skip this part. We will add our private SSH key to the repository secrets to enable GitHub Actions to access your server. Finally we will create a workflow that deploys our website.

Create repository

Create a repository at https://github.com. Create a public or private repository. Decide if you want to create a .gitignore, licence or README.md file, it doesn't matter for the example website.

The default branch of the GitHub repository is called main. The name of the default branch in the local repository should be the same. Git uses master by default, but you can override this default. Initialize the local GIT repository with the following command to use main as the default branch name from within your website's folder:

cd my-awesome-website
git init --initial-branch=main

Now, you can add the remote repository to your local repository:

git remote add origin git@github.com:robinvanderknaap/my-awesome-website.git

Make sure to use the correct git URL of your repository, you can't use mine :)

Pull the files from the remote repository if you addedREADME.md, license or .gitignore file during the creation of your GitHub repository:

git pull origin main

Now commit the changes to the local repository:

git add .
git commit -m "My awesome website"

And push the changes to the remote repository and set the upstream branch:

git push --set-upstream origin main

Add private SSH key as repository secret

For GitHub to deploy to your site, it needs to have access to the private key of the SSH key-pair we created at the beginning of this guide. We will store the key in a repository secret called SSH_KEY_DEPLOY.

Browse to your repository at GitHub and navigate to the repository settings. Select Secrets and variables -> Actions.

Use the New repository secret button to create a new secret called SSH_KEY_DEPLOY. Paste the contents of your private key into the secret field.

You can get the content of your private key like this (don't accidentally use the public key with the .pub extension):

cat ~/.ssh/name-of-your-key

Create workflow file for deployment

GitHub Actions are triggered by adding workflow files to your repository:

mkdir -p ./.github/workflows

Workflows are declared using YAML files:

touch ./.github/workflows/deploy.yaml

Add the following workflow:

on:
  push:
    branches:
      - main
name: Deploy website
jobs:
  web-deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
    - name: Get latest code
      uses: actions/checkout@v4

# Uncomment if you need Node.js to build your site
#   - name: Use Node.js
#      uses: actions/setup-node@v2
#      with:
#        node-version: '20'

    - name: Build Project
      run: |
        # Add steps here to build you website
        # npm install
        # npm run build
        mkdir ./public
        mv index.html ./public
        mv 404.html ./public

    - name: Rsync
      uses: burnett01/rsync-deployments@7.0.1
      with:
        switches: -avzr --delete
        path: public/
        remote_path: /var/www/your-domain/html
        remote_host: your-domain
        remote_user: root
        remote_key: ${{ secrets.SSH_KEY_DEPLOY }}

This is a pretty straightforward workflow. The script will trigger only when commits are pushed to the main branch and contains the following steps:

Pull code from repository
Build website. You can add commands here to build your site. If you need Node.js to build your site, uncomment the Use Node.js step. For the example website, we just copy our two html files to a public folder.
A plugin is used to rsync the contents to our server
- Make sure to use the correct path from which to deploy content
- Don't forget to specify the correct domain at remote-path and remote-host properties.
- Notice the SSH Key is retrieved from the repository secrets.

The workflow script is triggered every time you push a commit to the main branch of the remote repository. and the website will automatically be deployed.

Commit and push the build script

git add .
git commit -m "Added deploy workflow"
git push

You can view the progress of your deployment in the Actions tab of your repository at GitHub.

That's it! Happy coding!

Used articles

Setup HUGO using Docker

Robin van der Knaap — Sat, 11 Mar 2023 17:48:50 +0000

In this article I'm going to describe how to setup HUGO without installing a local version of HUGO on your machine by using a Docker image instead.

When choosing a specific Docker image, be aware that HUGO comes in two editions, standard and extended. The extended edition supports Sass and encoding WebP images, it is recommended by the HUGO team to use the extended edition, and that's what we will do in this article.

We will be using a Docker image from this repository: https://hub.docker.com/r/klakegg/hugo. All Docker images containing ext in its name use the extended edition of HUGO. We will use the Alpine based image.

The Docker image contains the HUGO CLI and exposes the hugo command as the ENTRYPOINT. Running the container and specifying the arguments for the hugo command, gives you all the options you would have when you have HUGO installed locally.

For example, the following command would show the version of HUGO when HUGO is installed locally:

hugo version

The same command can be run using the Docker container:

docker run --rm klakegg/hugo:0.107.0-ext-alpine version

The --rm flag indicates the container is immediately disposed after finishing.

NEW SITE

The following command will generate a new HUGO site called 'test':

docker run --rm -v $(pwd):/src klakegg/hugo:0.107.0-ext-alpine new site test --format yaml

A new folder 'test' will be created, which contains the generated site. The -v flag is used to create a volume from the present working directory (pwd). The --format yaml at the end enables yaml config files instead of toml.

To serve the site, you first need to navigate to the root of the site:

cd test

Run the following command to serve the new site. (notice the added -p flag containing the port numbers):

docker run --rm -p 1313:1313 -v $(pwd):/src klakegg/hugo:0.107.0-ext-alpine server

The site is built in-memory and will be hosted at http://localhost:1313.

You will see a 'Page not found' message when you visit the URL. Let's create an initial page by adding index.html to the layouts folder.

layouts/index.html

<!doctype html> 
<html lang="en"> 
  <head> 
    <meta charset="utf-8"> 
    <meta name="viewport" content="width=device-width, initial-scale=1"> 
    <title>HUGO & Docker demo</title>  
  </head> 
  <body> 
    <h1>Hello, world!!!</h1> 
  </body> 
</html>

You might need to restart the server to view the changes if your are working on Windows (I have a solution for that in a bit using docker-compose).

docker run --rm -p 1313:1313 -v $(pwd):/src klakegg/hugo:0.107.0-ext-alpine server

And now you will be greeted with 'Hello World' when you visit http://localhost:1313.

DOCKER-COMPOSE

Now instead of running the server each time using Docker run, we can add the server to a docker-compose.yml file and spin up the server with docker compose up. File changes are automatically picked up:

docker-compose.yml

services:
  server:
      image: klakegg/hugo:0.107.0-ext-alpine
      command: server -D --poll 700ms
      volumes:
        - ".:/src"
      ports:
        - "1313:1313"

The -D argument makes sure drafts are also build and served, this is what you usually want during development.
The poll flag is added for Windows users. In cases where Hugo CLI is running in a shared directory on a Linux VM on a Windows host the server is not detecting file changes from the host environment. The polling fixes this problem on Windows. More information here.

EXPOSE HUGO CLI VIA PACKAGE.JSON

Now that we have a convenient way of serving the site, we need a better way to access the HUGO CLI instead of calling Docker run each time. We will create a package.json file for that, and use the scrips section to make the HUGO CLI more accessible.

Create a package.json:

npm init -y

Expose the HUGO CLI by adding the following command to the scripts section:

"scripts": { 
    "hugo": "cross-env-shell docker run --rm -v $INIT_CWD:/src klakegg/hugo:0.107.0-ext-alpine" 
}

'cross-env-shell' is needed for a platform independent way of reading environments variables, such as the $INIT_CWD to get the current working directory.

npm i cross-env -D

Now you call the HUGO CLI like this:

npm run hugo -- --help

CLI arguments are placed after the --.

To build the website you can use the hugo command without arguments.

npm run hugo

The server command as used earlier, builds the site in memory. The build command builds the site and stores the output in the ./public folder.

CONCLUSION

Now you are able to get started with HUGO without installing it on your machine. Hope this helps someone, it took me a few hours to figure this out, especially to get it to work on Windows.

Setting up an Authorization Server with OpenIddict - Part VI - Refresh tokens

Robin van der Knaap — Fri, 11 Dec 2020 13:14:13 +0000

This article is part of a series called Setting up an Authorization Server with OpenIddict. The articles in this series will guide you through the process of setting up an OAuth2 + OpenID Connect authorization server on the the ASPNET Core platform using OpenIddict.

robinvanderknaap / authorization-server-openiddict

Authorization Server implemented with OpenIddict.

Access tokens typically have a short lifetime for security reasons. In this part we will enable the usage of refresh tokens. A refresh token allows an application to obtain a new access token without prompting the user.

Enable refresh tokens

First we need to enable the refresh token flow in Startup.cs:

options
    .AllowAuthorizationCodeFlow()
        .RequireProofKeyForCodeExchange()
    .AllowClientCredentialsFlow()
    .AllowRefreshTokenFlow();

In the token endpoint in the AuthorizationController we need to handle refresh token requests, just like we handled client credentials requests, and requests to exchange authorization codes for access tokens:

[HttpPost("~/connect/token")]
public async Task<IActionResult> Exchange()
{
    ...

    else if (request.IsAuthorizationCodeGrantType())
    {
        ...
    }

    else if (request.IsRefreshTokenGrantType())
    {
        // Retrieve the claims principal stored in the refresh token.
        claimsPrincipal = (await HttpContext.AuthenticateAsync(OpenIddictServerAspNetCoreDefaults.AuthenticationScheme)).Principal;
    }

    ...
}

Basically, we only need to retrieve the ClaimsPrincipal from the refresh token, and sign in again, which will return a new access token.

Finally, we need to allow the client to use refresh tokens:

Permissions =
{
    OpenIddictConstants.Permissions.Endpoints.Authorization,
    OpenIddictConstants.Permissions.Endpoints.Token,

    OpenIddictConstants.Permissions.GrantTypes.AuthorizationCode,
    OpenIddictConstants.Permissions.GrantTypes.ClientCredentials,
    OpenIddictConstants.Permissions.GrantTypes.RefreshToken,

    OpenIddictConstants.Permissions.Prefixes.Scope + "api",

    OpenIddictConstants.Permissions.ResponseTypes.Code
}

If a client wants to use refresh tokens, it needs to request the offline_access scope. Just like we requested the openid scope for identity tokens. Now, if we request a new access token with Postman, we will receive a refresh token together with the access token.

After that, we can use the refresh token to request a new access token with Postman. Send a POST request to /connect/token with a body containing the client credentials, grant type and of course the refresh token.

In the response you will find a new access token and also a new refresh token. So, refresh tokens are automatically rotated, which is more secure than reusing the same refresh token.

Setting up an Authorization Server with OpenIddict - Part V - OpenID Connect

Robin van der Knaap — Fri, 11 Dec 2020 13:14:04 +0000

This article is part of a series called Setting up an Authorization Server with OpenIddict. The articles in this series will guide you through the process of setting up an OAuth2 + OpenID Connect authorization server on the the ASPNET Core platform using OpenIddict.

robinvanderknaap / authorization-server-openiddict

Authorization Server implemented with OpenIddict.

OpenIddict implements the OpenID Connect protocol, which is an identity layer on top of the OAuth2 protocol.
The implementation of the OpenID Connect protocol issues an extra token to the client application, called the identity token. This token contains user profile information which can be used by client applications to identify the end-user.

It's wise to keep your tokens small. Therefore, the OpenID Connect protocol offers the possibility to expose an userinfo endpoint from which clients can retrieve extra information about the end-user which is not stored in the identity token.

In this part we will see how to leverage the OpenID Connect protocol and how to add an endpoint for querying extra user information.

Enable OpenID Connect

As said, OpenIddict has implemented the OpenID Connect protocol. You can test this by requesting an extra scope called openid with Postman:

In the response you will find an identity token together with the access token.

To store extra profile information in the identity token, you can add claims in the Authorize method in the AuthorizationController when using the authorization code flow or add claims in the token endpoint if you are using the client credentials flow. Make sure to set the destination to IdentityToken. Here's an example using a default claim called email:

public async Task<IActionResult> Authorize()
{
    ...

    var claims = new List<Claim>
    {
        // 'subject' claim which is required
        new Claim(OpenIddictConstants.Claims.Subject, result.Principal.Identity.Name),
        new Claim("some claim", "some value").SetDestinations(OpenIddictConstants.Destinations.AccessToken),
        new Claim(OpenIddictConstants.Claims.Email, "some@email").SetDestinations(OpenIddictConstants.Destinations.IdentityToken)
    };

    ...
}

It is also possible for a claim to have multiple destinations, so we can add a claim to the access token and the identity token if we want.

You can view the content of the identity token on jwt.io:

{
  "sub": "Robin van der Knaap",
  "email": "some@email",
  "oi_au_id": "e5e12b78-ddea-42df-8350-5b7bda36b07b",
  "azp": "postman",
  "at_hash": "iuzdujyas1p_1XjUuxtw9A",
  "oi_tkn_id": "7f0ae652-c997-4425-bda5-6d024ea3acb3",
  "aud": "postman",
  "exp": 1607684956,
  "iss": "https://localhost:5001/",
  "iat": 1607683756
}

Userinfo endpoint

Besides the identity token, the OpenID Connect protocols also allows for an url to get information about the user. To leverage the userinfo endpoint, we need to enable the endpoint and set the url in Startup.cs first:

options
    .SetAuthorizationEndpointUris("/connect/authorize")
    .SetTokenEndpointUris("/connect/token")
    .SetUserinfoEndpointUris("/connect/userinfo");

options
    .UseAspNetCore()
    .EnableTokenEndpointPassthrough()
    .EnableAuthorizationEndpointPassthrough()
    .EnableUserinfoEndpointPassthrough();

Now if you restart the authorization server and navigate to https://localhost:5001/.well-known/openid-configuration. You will see that the userinfo endpoint is added to public configuration file:

Next step is to implement the userinfo endpoint. We can decide for ourselves which user info we want to share with clients. We will add the method to the AuthorizationController:

[Authorize(AuthenticationSchemes = OpenIddictServerAspNetCoreDefaults.AuthenticationScheme)]
[HttpGet("~/connect/userinfo")]
public async Task<IActionResult> Userinfo()
{
    var claimsPrincipal = (await HttpContext.AuthenticateAsync(OpenIddictServerAspNetCoreDefaults.AuthenticationScheme)).Principal;

    return Ok(new
    {
        Name = claimsPrincipal.GetClaim(OpenIddictConstants.Claims.Subject),
        Occupation = "Developer",
        Age = 43
    });
}

The user info endpoint can only be accessed when the client has a valid access token. This is why we added the Authorize attribute. For this to work, we have to enable authorization in Startup.cs:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...

    app.UseAuthentication();

    app.UseAuthorization();

    ...
}

Now if we do a GET request to /connect/userinfo and use a valid access token, the response looks something like this:

Next up, we will enable the usage of refresh tokens.

Setting up an Authorization Server with OpenIddict - Part IV - Authorization Code Flow

Robin van der Knaap — Fri, 11 Dec 2020 13:13:55 +0000

This article is part of a series called Setting up an Authorization Server with OpenIddict. The articles in this series will guide you through the process of setting up an OAuth2 + OpenID Connect authorization server on the the ASPNET Core platform using OpenIddict.

robinvanderknaap / authorization-server-openiddict

Authorization Server implemented with OpenIddict.

In this part we will implement the Authorization Code Flow with PKCE extension. This flow is the recommended flow for Single Page Applications (SPA's) and native/mobile applications.

Configure OpenIddict

First we need to enable the Authorization Code Flow in Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddOpenIddict()

        ...

        .AddServer(options =>
        {
            options.AllowAuthorizationCodeFlow().RequireProofKeyForCodeExchange();

            ...

            options
                .SetAuthorizationEndpointUris("/connect/authorize")
                .SetTokenEndpointUris("/connect/token");

            ...

            options
                .UseAspNetCore()
                .EnableTokenEndpointPassthrough()
                .EnableAuthorizationEndpointPassthrough(); 
        });

        ...
}

The call AllowAuthorizationCodeFlow enables the flow, RequireProofKeyForCodeExchange is called directly after that, this makes sure all clients are required to use PKCE (Proof Key for Code Exchange).

The authorization code flow dictates that the user first authorizes the client to make requests in the user's behalf. Therefore, we need to implement an authorization endpoint which returns an authorization code to the client when the user allows it.

The client can exchange the authorization code for an access token by calling the token endpoint we already created for the client credentials flow.

First, we will create the authorization endpoint, the call to EnableAuthorizationEndpointPassthrough in Startup.cs allows us to implement the endpoint within a controller.

After that we will make some minor adjustments to our token endpoint to allow clients to exchange authorization codes for access tokens.

Authorization endpoint

We'll implement the authorization endpoint in the Authorization Controller, just like the token endpoint:

[HttpGet("~/connect/authorize")]
[HttpPost("~/connect/authorize")]
[IgnoreAntiforgeryToken]
public async Task<IActionResult> Authorize()
{
    var request = HttpContext.GetOpenIddictServerRequest() ??
        throw new InvalidOperationException("The OpenID Connect request cannot be retrieved.");

    // Retrieve the user principal stored in the authentication cookie.
    var result = await HttpContext.AuthenticateAsync(CookieAuthenticationDefaults.AuthenticationScheme);

    // If the user principal can't be extracted, redirect the user to the login page.
    if (!result.Succeeded)
    {
        return Challenge(
            authenticationSchemes: CookieAuthenticationDefaults.AuthenticationScheme,
            properties: new AuthenticationProperties
            {
                RedirectUri = Request.PathBase + Request.Path + QueryString.Create(
                    Request.HasFormContentType ? Request.Form.ToList() : Request.Query.ToList())
            });
    }

    // Create a new claims principal
    var claims = new List<Claim>
    {
        // 'subject' claim which is required
        new Claim(OpenIddictConstants.Claims.Subject, result.Principal.Identity.Name),
        new Claim("some claim", "some value").SetDestinations(OpenIddictConstants.Destinations.AccessToken)
    };

    var claimsIdentity = new ClaimsIdentity(claims, OpenIddictServerAspNetCoreDefaults.AuthenticationScheme);

    var claimsPrincipal = new ClaimsPrincipal(claimsIdentity);

    // Set requested scopes (this is not done automatically)
    claimsPrincipal.SetScopes(request.GetScopes());

    // Signing in with the OpenIddict authentiction scheme trigger OpenIddict to issue a code (which can be exchanged for an access token)
    return SignIn(claimsPrincipal, OpenIddictServerAspNetCoreDefaults.AuthenticationScheme);
}

Unlike the Clients Credentials Flow, the Authorization Code Flow involves the end user for approval. Remember that we already implemented authentication in our project. So, in the authorize method we just determine if the user is already logged in, if not, we redirect the user to the login page.

When the user is authenticated, a new claims principal is created which is used to sign in with OpenIddict authentication scheme.

You can add claims to principal which will be added to the access token if the destination is set to AccessToken. The subject claim is required and is always added to the access token, you don't have to specify a destination for this claim.

The scopes requested by the client are all given with the call claimsPrincipal.SetScopes(request.GetScopes()), because we don't implement a consent screen in this example to keep things simple. When you do implement consent, this would be the place to filter the requested scopes.

The SignIn call triggers the OpenIddict middleware to send an authorization code which the client can exchange for an access token by calling the token endpoint.

We need to alter the token endpoint also since we now support the Authorization Code Flow:

[HttpPost("~/connect/token"), Produces("application/json")]
public async Task<IActionResult> Exchange()
{
    ...

    if (request.IsClientCredentialsGrantType())
    {
        ...
    }

    else if (request.IsAuthorizationCodeGrantType())
    {
        // Retrieve the claims principal stored in the authorization code
        claimsPrincipal = (await HttpContext.AuthenticateAsync(OpenIddictServerAspNetCoreDefaults.AuthenticationScheme)).Principal;
    }

    else
    {
        throw new InvalidOperationException("The specified grant type is not supported.");
    }

    ...
}

The claims principal we created in the authorize method is stored in the authorization code, so we only need to grab the claims principal from the request and pass it to the SignIn method. OpenIddict will respond with an access token.

Now, let's see if we can request an access token with the Authorization Code Flow using Postman:

This won't work because the client is not allowed to use the Authorization Code Flow and also we did not specify the RedirectUris of the client.

The redirect URI in the case of Postman is https://oauth.pstmn.io/v1/callback. The authorization code is sent here after successful authentication.

After updating, the Postman client in TestData.cs should look like this:

ClientId = "postman",
ClientSecret = "postman-secret",
DisplayName = "Postman",
RedirectUris = { new Uri("https://oauth.pstmn.io/v1/callback") },
Permissions =
{
    OpenIddictConstants.Permissions.Endpoints.Authorization,
    OpenIddictConstants.Permissions.Endpoints.Token,

    OpenIddictConstants.Permissions.GrantTypes.AuthorizationCode,
    OpenIddictConstants.Permissions.GrantTypes.ClientCredentials,

    OpenIddictConstants.Permissions.Prefixes.Scope + "api",

    OpenIddictConstants.Permissions.ResponseTypes.Code
}

If everything is working correctly, you should be able to obtain an access token with Postman after authenticating yourself.

Note. A client secret is optional when configuring a client with OpenIddict, this is useful for public clients which aren't able to securely store a client secret. When the client secret is omitted from the configuration, you can also omit it from the request.
The PKCE-enhanced Authorization Code Flow introduces a secret created by the calling application that can be verified by the authorization server (source). However, PKCE doesn't replace client secrets. PKCE and client secrets are complementary and you should use them both when possible (typically, for server-side apps). (Explained to me by the author of OpenIddict)

Congratulations, you have implemented the Authentication Code Flow with PKCE with OpenIddict! Next up, we will demonstrate how to leverage the OpenID Connect protocol.

Setting up an Authorization Server with OpenIddict - Part III - Client Credentials Flow

Robin van der Knaap — Fri, 11 Dec 2020 13:13:50 +0000

This article is part of a series called Setting up an Authorization Server with OpenIddict. The articles in this series will guide you through the process of setting up an OAuth2 + OpenID Connect authorization server on the the ASPNET Core platform using OpenIddict.

Part I: Introduction
Part II: Create ASPNET project
Part III: Client Credentials Flow
Part IV: Authorization Code Flow
Part V: OpenID Connect
Part VI: Refresh tokens

robinvanderknaap / authorization-server-openiddict

Authorization Server implemented with OpenIddict.

In this part we will add OpenIddict to the project and implement out first authorization flow: The Client Credentials Flow.

Add OpenIddict packages

First, we need to install the OpenIddict NuGet packages:

dotnet add package OpenIddict
dotnet add package OpenIddict.AspNetCore
dotnet add package OpenIddict.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.InMemory

Besides the main library we also installed the OpenIddict.AspNetCore package, this package enables the integration of OpenIddict in an ASPNET Core host.

OpenIddict.EntityFrameworkCore package enables Entity Framework Core support. For now we will work with an in-memory implementation, for which we use the package Microsoft.EntityFrameworkCore.InMemory.

Setup OpenIddict

We will start with what is minimal required to get OpenIddict up and running. At least one OAuth 2.0/OpenID Connect flow must be enabled. We choose to enable the the Client Credentials Flow, which is suitable for machine-to-machine applications. In the next part of this series we will implement the Authorization Code Flow with PKCE which is the recommended flow for Single Page Applications (SPA) and native/mobile applications.

Start to make the following changes to Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddDbContext<DbContext>(options =>
    {
        // Configure the context to use an in-memory store.
        options.UseInMemoryDatabase(nameof(DbContext));

        // Register the entity sets needed by OpenIddict.
        options.UseOpenIddict();
    });

    services.AddOpenIddict()

        // Register the OpenIddict core components.
        .AddCore(options =>
        {
            // Configure OpenIddict to use the EF Core stores/models.
            options.UseEntityFrameworkCore()
                .UseDbContext<DbContext>();
        })

        // Register the OpenIddict server components.
        .AddServer(options =>
        {
            options
                .AllowClientCredentialsFlow();

            options
                .SetTokenEndpointUris("/connect/token");

            // Encryption and signing of tokens
            options
                .AddEphemeralEncryptionKey()
                .AddEphemeralSigningKey();

            // Register scopes (permissions)
            options.RegisterScopes("api");

            // Register the ASP.NET Core host and configure the ASP.NET Core-specific options.
            options
                .UseAspNetCore()
                .EnableTokenEndpointPassthrough();            
        });
}

First, the DbContext is registered in the ConfigureServices method. OpenIddict natively supports Entity Framework Core, Entity Framework 6 and MongoDB out-of-the-box, and you can also provide your own stores.
In this example, we will use Entity Framework Core, and we will use an in-memory database. The options.UseOpenIdDict call registers the entity sets needed by OpenIddict.

Next, OpenIddict itself is registered. The AddOpenIddict() call registers the OpenIddict services and returns a OpenIddictBuilder class with which we can configure OpenIddict.

The core components are registered first. OpenIddict is instructed to use Entity Framework Core, and use the aforementioned DbContext.

Next, the server components are registered and the Client Credentials Flow is enabled. For this flow to work, we need to register a token endpoint. We need to implement this endpoint ourselves. We'll do this later.

For OpenIddict to be able to encrypt and sign tokens we need to register two keys, one for encrypting and one for signing. In this example we'll use ephemeral keys. Ephemeral keys are automatically discarded when the application shuts down and payloads signed or encrypted using these key are therefore automatically invalidated. This method should only be used during development. On production, using a X.509 certificate is recommended.

RegisterScopes defines which scopes (permissions) are supported. In this case we have one scope called api, but the authorization server can support multiple scopes.

The UseAspNetCore() call is used to setup AspNetCore as a host for OpenIddict. We also call EnableTokenEndpointPassthrough otherwise requests to our future token endpoint are blocked.

To check if OpenIddict is properly configured we can start the application and navigate to: https://localhost:5001/.well-known/openid-configuration, the response should be something like this:

{
  "issuer": "https://localhost:5001/",
  "token_endpoint": "https://localhost:5001/connect/token",
  "jwks_uri": "https://localhost:5001/.well-known/jwks",
  "grant_types_supported": [
    "client_credentials"
  ],
  "scopes_supported": [
    "openid",
    "api"
  ],
  "claims_supported": [
    "aud",
    "exp",
    "iat",
    "iss",
    "sub"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "subject_types_supported": [
    "public"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post"
  ],
  "claims_parameter_supported": false,
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false
}

In this guide, we will be using Postman to test the authorization server, but you could just as easily use another tool.

Below you find an example authorization request using Postman. Grant Type is the Client Credentials Flow. We specify the access token url, a client id and secret to authenticate our client. We also request access to the api scope.

If we request the token, the operation will fail: The client_id is invalid. This makes sense, because we haven't registered any clients yet with our Authorization Server.
We can create a client by adding it to the database. For that purpose we create a class called TestData. The test data implements the IHostedService interface, which enables us to execute the generation of test data in Startup.cs when the application starts.

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using OpenIddict.Abstractions;

namespace AuthorizationServer
{
    public class TestData : IHostedService
    {
        private readonly IServiceProvider _serviceProvider;

        public TestData(IServiceProvider serviceProvider)
        {
            _serviceProvider = serviceProvider;
        }

        public async Task StartAsync(CancellationToken cancellationToken)
        {
            using var scope = _serviceProvider.CreateScope();

            var context = scope.ServiceProvider.GetRequiredService<DbContext>();
            await context.Database.EnsureCreatedAsync(cancellationToken);

            var manager = scope.ServiceProvider.GetRequiredService<IOpenIddictApplicationManager>();

            if (await manager.FindByClientIdAsync("postman", cancellationToken) is null)
            {
                await manager.CreateAsync(new OpenIddictApplicationDescriptor
                {
                    ClientId = "postman",
                    ClientSecret = "postman-secret",
                    DisplayName = "Postman",
                    Permissions =
                    {
                        OpenIddictConstants.Permissions.Endpoints.Token,
                        OpenIddictConstants.Permissions.GrantTypes.ClientCredentials,

                        OpenIddictConstants.Permissions.Prefixes.Scope + "api"
                    }
                }, cancellationToken);
            }
        }

        public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
    }
}

A client is registered in the test data. The client id and secret are used to authenticate the client with the authorization server. The permissions determine what this client's options are.
In this case we allow for the client to use the Client Credentials Flow, access the token endpoint and allow the client to request the api scope.

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddHostedService<TestData>();
}

If we try to obtain an access token with Postman again, the request will still fail. This is because we haven't created the token endpoint yet. We'll do that now.

Create a new controller called AuthorizationController, we will host the endpoint here:

using System;
using System.Security.Claims;
using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Mvc;
using OpenIddict.Abstractions;
using OpenIddict.Server.AspNetCore;

namespace AuthorizationServer.Controllers
{
    public class AuthorizationController : Controller
    {
        [HttpPost("~/connect/token")]
        public IActionResult Exchange()
        {
            var request = HttpContext.GetOpenIddictServerRequest() ??
                          throw new InvalidOperationException("The OpenID Connect request cannot be retrieved.");

            ClaimsPrincipal claimsPrincipal;

            if (request.IsClientCredentialsGrantType())
            {
                // Note: the client credentials are automatically validated by OpenIddict:
                // if client_id or client_secret are invalid, this action won't be invoked.

                var identity = new ClaimsIdentity(OpenIddictServerAspNetCoreDefaults.AuthenticationScheme);

                // Subject (sub) is a required field, we use the client id as the subject identifier here.
                identity.AddClaim(OpenIddictConstants.Claims.Subject, request.ClientId ?? throw new InvalidOperationException());

                // Add some claim, don't forget to add destination otherwise it won't be added to the access token.
                identity.AddClaim("some-claim", "some-value", OpenIddictConstants.Destinations.AccessToken);

                claimsPrincipal = new ClaimsPrincipal(identity);

                claimsPrincipal.SetScopes(request.GetScopes());
            }

            else
            {
                throw new InvalidOperationException("The specified grant type is not supported.");
            }

            // Returning a SignInResult will ask OpenIddict to issue the appropriate access/identity tokens.
            return SignIn(claimsPrincipal, OpenIddictServerAspNetCoreDefaults.AuthenticationScheme);
        }
    }
}

One action is implemented, Exchange. This action is used by all flows, not only the Client Credentials Flow, to obtain an access token.

In the case of the Client Credentials Flow, the token is issued based on the client credentials. In the case of Authorization Code Flow, the same endpoint is used but then to exchange an authorization code for a token. We'll see that in part IV.

For now, we need to focus on the Client Credentials Flow. When the request enters the Exchange action, the client credentials (ClientId and ClientSecret) are already validated by OpenIddict. So we don't need to authenticate the request, we only have to create a claims principal and use that to sign in.

The claims principal is not the same as we used in the Account controller, that one was based on the Cookie authentication handler and is only used within the context of the Authorization server itself to determine if the user has been authenticated or not.

The claims principal we have to create is based on the OpenIddictServerAspNetCoreDefaults.AuthenticationScheme. This way, when we call SignIn at the end of this method, the OpenIddict middleware will handle the sign in and return an access token as response to the client.

The claims defined in the claims principal are included in the access token only when we specify the destination. The some-value claim in the example will be added to the access token.
The subject claim is required and you don't need to specify a destination, it will be included in the access token anyway.

We also grant all the requested scopes by calling claimsPrincipal.SetScopes(request.GetScopes());. OpenIddict has already checked if the requested scopes are allowed (in general and for the current client). The reason why we have to add the scopes manually here is that we are able to filter the scopes granted here if we want to.

One token to rule them all

Let's try to obtain an access token with Postman again, this time it should work.

As of v3 of OpenIddict, the access token is in Jason Web Token (JWT) format by default. This enables us to examine the token with jwt.io. (Thanks Auth0, for hosting that service!)

One problem, the token is not only signed, but also encrypted. OpenIddict encrypts the access token by default. We can disable this encryption when configuring OpenIddict in Startup.cs:

// Encryption and signing of tokens
options
    .AddEphemeralEncryptionKey()
    .AddEphemeralSigningKey()
    .DisableAccessTokenEncryption();

Now, when we restart our authorization server and request a new token. Paste the token to jwt.io and view the content of the token:

As you can see the client id postman is set as subject sub. Also the some-claim claim is added to the access token.

Congratulations, you have implemented the Client Credentials Flow with OpenIddict!

As you may have noticed, the login page is unused by the Client Credentials Flow. This flow exchanges the client credentials for a token immediately, which is suitable for machine-to-machine applications.

Next up, we will implement the Authorization Code Flow with PKCE, which is the recommended flow for single page applications (SPA) and mobile apps. This flow will involve the user, so our login page will come in to play.

Setting up an Authorization Server with OpenIddict - Part II - Create ASPNET project

Robin van der Knaap — Fri, 11 Dec 2020 13:13:44 +0000

This article is part of a series called Setting up an Authorization Server with OpenIddict. The articles in this series will guide you through the process of setting up an OAuth2 + OpenID Connect authorization server on the the ASPNET Core platform using OpenIddict.

robinvanderknaap / authorization-server-openiddict

Authorization Server implemented with OpenIddict.

In this part we will create an ASPNET Core project which serves as a minimal setup for our authorization server. We will use MVC to serve pages and we will add authentication to the project, including a basic login form.

Create a new empty ASPNET project.

As was said in the previous article, an authorization server is just another web application. The following content will guide you through setting up an ASPNET Core application with a username-password login. I choose not to use ASPNET Core Identity to keep things really simple. Basically every username-password combination will work.

Let's start with creating a new web application called AuthorizationServer using the ASP.NET Core Empty template:

dotnet new web --name AuthorizationServer

We will work with just this project, and we will not add a solution file in this guide.

OpenIddict requires us to work with the https protocol, even when developing locally. To make sure the local certificate is trusted, you will have to run the following command:

dotnet dev-certs https --trust

On Windows the certificate will be added to the certificate store and on OSX to the keychain. On Linux there isn't a standard way across distros to trust the certificate. Read more about this subject in Hanselman's blog article.

Start the application to see if everything works as expected

dotnet run --project AuthorizationServer

Visit https://localhost:5001. You should see the Hello World! in your browser.

MVC

We have created a project based on the ASPNET Core Empty template. This is a very minimal template. I have done this intentionally, because I like to have as little 'noise' in my project as possible to keep things clear and simple.

Downside of using this template is we have to add MVC ourselves. First, we need to enable MVC by altering the Startup.cs class:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace AuthorizationServer
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllersWithViews();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseStaticFiles();

            app.UseRouting();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapDefaultControllerRoute();
            });
        }
    }
}

MVC is configured by calling services.AddControllersWithViews(). Endpoints are setup to use default routing. We also enabled the serving of static files, we need this to serve our style sheets out of the wwwroot folder.

Now, let's create the controllers, views and view models. Start with adding the following folder structure inside the project folder (mind the casing):

/Controllers
/Views
/Views/Home  
/Views/Shared
/ViewModels
/wwwroot
/wwwroot/css

Layout

The first item we add is a layout file called _Layout.cshtml to the Views/Shared folder. This file defines the general layout of the application, and also loads Bootstrap and jQuery from a CDN. jQuery is a dependency of Bootstrap.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, shrink-to-fit=no"/>

    <title>OpenIddict - Authorization Server</title>

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@4.5.3/dist/css/bootstrap.min.css" crossorigin="anonymous">
    <link rel="stylesheet" href="~/css/site.css"/>
</head>
<body>
<div class="container-sm mt-3">
    <div class="row mb-3">
        <div class="col text-center">
            <h1>
                Authorization Server
            </h1>
        </div>
    </div>
    <div class="row">
        <div class="col-xs-12 col-md-8 col-xl-4 offset-md-2 offset-xl-4 text-center mb-3">
            @RenderBody()
        </div>
    </div>
</div>
<script src="https://code.jquery.com/jquery-3.5.1.slim.min.js" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@4.5.3/dist/js/bootstrap.bundle.min.js" crossorigin="anonymous"></script>
</body>
</html>

For the layout and views to work, we need to add two files to the \Views folder:

_ViewStart.cshtml

@{
  Layout = "_Layout";
}

_ViewImports.cshtml

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Home page

Add a basic HomeController to the /Controllers folder, which has the sole purpose of serving our home page:

using Microsoft.AspNetCore.Mvc;

namespace AuthorizationServer.Controllers
{
    public class HomeController : Controller
    {
        public IActionResult Index()
        {
            return View();
        }
    }
}

Add Index.cshtml to the Views/Home folder, which is served by the HomeController:

<h2>MVC is working</h2>

Style sheet

Last but not least, we need some styling. Add a style sheet called site.css to the wwwroot\css folder:

:focus {
  outline: 0 !important;
}
.input-validation-error {
  border: 1px solid darkred;
}
form {
  width: 100%;
}
.form-control {
  border:0;
  border-radius: 0;
  border-bottom: 1px solid lightgray;
  font-size:0.9rem;
}
.form-control:focus{
  border-bottom-color: lightgray;
  box-shadow: none;
}
.form-control.form-control-last {
  border-bottom: 0;
}
.form-control::placeholder {
  opacity: 0.6;
}
.form-control.input-validation-error {
  border: 1px solid darkred;
}

Some style rules are already added to the style sheet anticipating the login form we are going to create later.

If you want to use SASS, or customize Bootstrap with SASS, check my article about setting up Bootstrap SASS with ASPNET.

Let's run the application and see if everything is working, you should see something like this in your browser:

Enable authentication

In ASP.NET Core, authentication is handled by the IAuthenticationService. The authentication service uses authentication handlers to complete authentication-related actions.

The authentication handlers are registered during startup and their configuration options are called "schemes". Authentication schemes are specified by registering authentication services in Startup.ConfigureServices.

For this project we will use cookie authentication, so we need to register the Cookie authentication scheme in the ConfigureServices method in Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();

    services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
        .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme, options =>
        {
            options.LoginPath = "/account/login";
        });
}

The login path is set to /account/login, we will implement this endpoint shortly.

The authentication middleware, which uses the registered authentication schemes, is added by calling the UseAuthentication extension method on the app's IApplicationBuilder:

app.UseRouting();

app.UseAuthentication();

app.UseEndpoints(endpoints =>
{
    endpoints.MapDefaultControllerRoute();
});

The call to UseAuthentication is made after the call to UseRouting, so that route information is available for authentication decisions, but before UseEndpoints, so that users are authenticated before accessing the endpoints.

Login page

Now that we have authentication enabled, we will need a login page to authenticate users.

First, create the Login view model containing the information we need to authenticate the user. Make sure to put this file in the ViewModels folder:

using System.ComponentModel.DataAnnotations;

namespace AuthorizationServer.ViewModels
{
    public class LoginViewModel
    {
        [Required]
        public string Username { get; set; }
        [Required]
        public string Password { get; set; }
        public string ReturnUrl { get; set; }
    }
}

Create a folder named Account in the Views folder and add the login view, Login.cshtml, containing the login form:

@model AuthorizationServer.ViewModels.LoginViewModel
<form autocomplete="off" asp-route="Login">
    <input type="hidden" asp-for="ReturnUrl"/>
    <div class="card">
        <input type="text" class="form-control form-control-lg" placeholder="Username" asp-for="Username" autofocus>
        <input type="password" class="form-control form-control-lg form-control-last" placeholder="Password" asp-for="Password">
    </div>
    <p>
        <button type="submit" class="btn btn-dark btn-block mt-3">Login</button>
    </p>
</form>

Finally we add the AccountController:

using System.Collections.Generic;
using System.Security.Claims;
using System.Threading.Tasks;
using AuthorizationServer.ViewModels;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace AuthorizationServer.Controllers
{
    public class AccountController : Controller
    {
        [HttpGet]
        [AllowAnonymous]
        public IActionResult Login(string returnUrl = null)
        {
            ViewData["ReturnUrl"] = returnUrl;
            return View();
        }

        [HttpPost]
        [AllowAnonymous]
        [ValidateAntiForgeryToken]
        public async Task<IActionResult> Login(LoginViewModel model)
        {
            ViewData["ReturnUrl"] = model.ReturnUrl;

            if (ModelState.IsValid) 
            {
                var claims = new List<Claim>
                {
                    new Claim(ClaimTypes.Name, model.Username)
                };

                var claimsIdentity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme);

                await HttpContext.SignInAsync(new ClaimsPrincipal(claimsIdentity));

                if (Url.IsLocalUrl(model.ReturnUrl))
                {
                    return Redirect(model.ReturnUrl);
                }

                return RedirectToAction(nameof(HomeController.Index), "Home");
            }

            return View(model);
        }

        public async Task<IActionResult> Logout()
        {
            await HttpContext.SignOutAsync();

            return RedirectToAction(nameof(HomeController.Index), "Home");
        }
    }
}

So, what happens here?
We have two login actions (GET and POST) on the account controller, both allow anonymous requests, otherwise nobody would be able to login.

The GET action serves the login form we just created. We have an optional query parameter returlUrl which we store in ViewData, so we can use this to redirect the user after a successful login.

The POST action is more interesting. First the ModelState is validated. That means that a username and a password are required. We do not check the credentials here, any combination is valid in this example. Normally, this would be the place where you check the credentials against your database.

When the ModelState is valid, a claims identity is constructed. We add one claim, the name of the user. Beware, we specify the cookie authentication scheme (CookieAuthenticationDefaults.AuthenticationScheme) when creating the claims identity. This is basically a string, and maps to the authentication scheme we defined in the Startup.cs class when setting up the cookie authentication.

The SignInAsync method is an extension method which calls the AuthenticationService which calls the CookieAuthenticationHandler because that's the scheme we specified when creating the claims identity.

After signing in we need to redirect the user. If a return url is specified, we check if it's a local url to prevent open redirect attacks before redirecting. Otherwise the user is redirected to the home page.

The last action, Logout, calls the authentication service to sign out the user. The authentication service will call the authentication middleware, in our case the cookie authentication middleware, to sign out the user.

Update home page

Update the home page (Views/Home/Index.cshtml):

@using Microsoft.AspNetCore.Authentication

@if (User.Identity.IsAuthenticated)
{
    var authenticationResult = await Context.AuthenticateAsync();
    var issued = authenticationResult.Properties.Items[".issued"];
    var expires = authenticationResult.Properties.Items[".expires"];
    <div>
        <p>You are signed in as</p>
        <h2>@User.Identity.Name</h2>
        <hr/>
        <dl>
            <dt>Issued</dt>
            <dd>@issued</dd>
            <dt>Expires</dt>
            <dd>@expires</dd>
        </dl>
        <hr/>
        <p><a class="btn btn-dark" asp-controller="Account" asp-action="Logout">Sign out</a></p>
    </div>
}

@if (!User.Identity.IsAuthenticated)
{
    <div>
        <p>You are not signed in</p>
        <p><a class="btn btn-sm btn-dark" asp-controller="Account" asp-action="Login">Sign in</a></p>
    </div>
}

If the user is authenticated we display the user name, information about the current session and a sign-out button. When the user is not authenticated, we show a sign-in button which navigates the user to the login form.

Start the application, you should see a sign-in button on the home page:

When you click Sign in you should navigate to the login form:

To sign in, just fill in random credentials, everything but an empty value is fine.
If everything works correctly you should be redirected to the home page which shows you are signed in:

Currently, we have a basic ASPNET Core project running with authentication implemented, nothing fancy so far. Next up, we will add OpenIddict to the project and implement the Client Credentials Flow.

Setting up an Authorization Server with OpenIddict - Part I - Introduction

Robin van der Knaap — Fri, 11 Dec 2020 13:13:29 +0000

This article is part of a series called Setting up an Authorization Server with OpenIddict. The articles in this series will guide you through the process of setting up an OAuth2 + OpenID Connect authorization server on the the ASPNET Core platform using OpenIddict.

robinvanderknaap / authorization-server-openiddict

Authorization Server implemented with OpenIddict.

Setting up an authorization server allows you to support token-based authentication and authorization. It also allows you to authenticate users for all your applications in one central place, Single Sign-On(SSO).

An authorization server can offer one or multiple authentication methods simultaneously, like local username-password but also external identity providers such as Google, Facebook or ADFS.

By implementing OAuth2 and OpenID Connect you are able to facilitate multiple authorization scenario's: Web applications, desktop applications, machine-to-machine communication and even authorization for living room devices. Both Oauth2 and OpenID Connect are industry standards.

IdentityServer

For over a decade the go-to project in .NET for implementing a secure token service and later OAuth2 + OpenID Connect was IdentityServer. Lately, the creators/maintainers of IdentityServer decided to dual license future versions of IdentityServer. Now unless you are working on an open-source project you will have to pay for a commercial license.

Although, paying for good software shouldn't be an issue for a lot of projects or companies, I went out to look for an alternative anyway.

OpenIddict

An alternative for IdentityServer is OpenIddict. OpenIddict provides a solution to implement an OpenID Connect server in any ASP.NET Core 2.1, 3.1 and 5.0 application, and starting with OpenIddict 3.0, any ASP.NET 4.x or OWIN application too.

OpenIddict is little bit more low-level than IdentityServer. Identity Server gives you a running solution out-of-the-box, where for OpenIddict to work you need to implement some details yourself, like creating claim identities and setting up the correct endpoints.

In this article we will use OpenIddict to implement our Authorization Server. We will implement the Client Credentials Flow, the Authorization Code Flow and setup refresh tokens as an example. We will also demonstrate how to leverage OpenID Connect to retrieve user information.

OAuth2 and OpenID Connect

OAuth2 and OpenID Connect can be confusing at times, at least to me it is.

It helped me to view an Authorization Server as just another web application. It's an application where you can login with a username-password combination or with some other external provider. Up to this point, nothing is different from any other web applications we have build.

After setting up authentication we can implement OAuth2 and OpenID Connect flows (this is where OpenIddict comes into play). These flows are leveraged by other applications (clients), basically asking 'can I do some stuff on behalf of this user?'.

To answer this question, users are first redirected to the Authorization Server by the clients. The user will authenticate himself if not already authenticated (SSO). After that, the user is asked if the client is allowed to make requests on behalf of the user. If yes, the external application receives an access token to make requests in the user's behalf.

Besides the access token (OAuth2), a separate identity token (OpenID Connect) can be issued. The identity token can be used by clients to extract user information.

In the next article we will start by creating a new ASPNET Core project and implement authentication as the first step toward a full-blown Authorization Server.

Setting up Bootstrap 4 SASS with ASPNET Core

Robin van der Knaap — Sat, 17 Oct 2020 14:15:31 +0000

The default ASPNET MVC template comes with Bootstrap 4 out-of-the-box. This is an already compiled version of Bootstrap. To customize the look and feel of Bootstrap elements, you need be able to override the default values of Bootstrap and compile Bootstrap from the SASS source.

Setting up Bootstrap with ASPNET Core was not that obvious to me. I've tried using the Bootstrap.sass package, but this wasn't working for me. NuGet is not equipped as a Frontend Package manager so it seems.

This articles describes how to setup Bootstrap 4 SASS in your ASPNET Core project using the following techniques:

NPM as package manager for frontend packages
Webpack for compiling SASS files and creating and minifying the CSS and JS bundles.
Setup Webpack as build task in .csproj file.

New ASPNET MVC project

Create a new ASPNET MVC project with your favorite IDE or use terminal/cmd/powershell:

dotnet new mvc --name AspNetBootstrapSass

Run the project from your IDE or from the commandline

cd AspNetBootstrapSass
dotnet run

If everything is working correctly you should see the default ASPNET welcome page in your browser.

Remove distribution version of Bootstrap

A distribution version of Bootstrap is already included in the template. However, we want to compile Bootstrap ourselves from the SASS source. Therefore, we will first remove Bootstrap (and also jquery) from the project.

Remove wwwroot/lib/bootstrap.
Remove wwwroot/lib/jquery.

Remove the links to all stylesheets in Views/Shared/_Layout.cshtml:

<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css" />
<link rel="stylesheet" href="~/css/site.css" />

Replaced them with a link to our CSS bundle, which we will create later:

<link rel="stylesheet" href="~/dist/bundle.css" />

Remove Bootstrap, jQuery and site.js scripts:

<script src="~/lib/jquery/dist/jquery.min.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
<script src="~/js/site.js" asp-append-version="true"></script>

Replace them with our yet to be created javascript bundle:

<script src="~/dist/bundle.js" asp-append-version="true"></script>

Add frontend packages with NPM

We will be using NPM to import the packages we need. I'm assuming NodeJS and NPM are already installed on your system. Add the following package.json to the project root folder.

Package.json contains two dependencies: Bootstrap and jQuery, jQuery is a dependency of Bootstrap. Webpack and a number of SASS related preprocessors are included as dev dependencies. We will need those to compile the SASS sources.

Package.json also contains some scripts, build and production, which we will use later to start the Webpack build process.

Run npm install to install all packages.

npm install

We now have bootstrap in the node_modules folder (never add this folder to version control). We can now reference the bootstrap.scss file from our custom SCSS file.

Setup SASS files

We already have a css folder in our wwwroot. Let's rename this to scss. Also rename site.css to site.scss. Remember, a CSS file is always a valid SCSS file.

Also create a file called _variables.scss. This will contain our Bootstrap overrides (the background color and some theme colors are overridden as an example). It needs to be imported before Bootstrap is imported.

Add the following at the top of site.scss

What is happening here? We are importing _variables.scss containing our Bootstrap overrides. After that we are importing Bootstrap itself. Everything below that is our own custom CSS/SCSS.

Configure Webpack

To create the CSS and JS bundles we referenced in _Layout.cshtml we need to configure Webpack. Add the following webpack.config.js to the project root folder

I'm not going to dive into the specific Webpack details here. Important is that in production mode, CSS and JS bundles are minified, in development mode the bundles are still readable.

To run Webpack, we can call one of the scripts we defined in package.json

npm run build

The result can be found in wwwroot\dist. We find 2 files: bundle.css and bundle.js. We have referenced these files already in _Layout.cshtml.

For production mode with minified bundles run:

npm run production

Adding Webpack build to project file

If you don't want run npm build every time you make a change to your SASS files, you can automate this step by adding the command to your project file.

Add the following snippet to AspNetBootstrapSass.csproj

Conclusion

Above setup enables you to customize your Bootstrap distribution to your likings and also enables you to use SASS within your MVC project. You can find the example project here:

robinvanderknaap / aspnet-bootstrap-sass

Example project showing how to setup Bootstrap SASS in a ASPNET Core project

Cover photo by Alexander Sinn on Unsplash

Create EML file from System.Net.Mail.MailMessage

Robin van der Knaap — Sat, 23 Nov 2013 08:00:00 +0000

For a project I was working on, I needed to create an EML file from the standard MailMessage class which exists in the System.Net.Mail namespace. I came across an article which describes how to extend the save functionality on the MailMessage class. Using the same technique I created an extension method which is able to save the MailMessage class as EML.

With this extension method in your solution you can create an EML file like this:

The extension method is implemented like this:

Conclusion

EML files are perfect for storing the email message on your file system or in the database. The EML file contains all the data from the email, including attachments. You can open the EML in most mail clients and view the email.

Bookreview Instant jqGrid by Gabriel Manricks

Robin van der Knaap — Sun, 29 Sep 2013 07:00:00 +0000

JqGrid is an ajax enabled jQuery plugin for showing and editing data in a grid. I’ve been using jqGrid extensively throughout my projects, and created an Html Helper to ease the implementation in ASP.NET MVC. Because of my experience with jqGrid, Packt publishing asked me to review one of their latest books, Instant jqGrid by Gabriel Manricks.

The book is mainly focused on people starting with jqGrid, experienced users will probably know most of the stuff that is written in the book and is of no added value to them.

The book can be divided in two parts. The first part teaches the jqGrid basic concepts, installation and walks you through the steps of creating your first grid. The second and biggest part is called ‘Top 7 features you need to know about’ and takes a deep dive in the most important features of jqGrid.

Covered in the second part are formatters, adding controls, editing data, connecting to a backend server and a description of some common methods and events of the jqGrid API. I especially liked the the example of connecting jqGrid to the backend. The backend code is written in PHP, but should easily be understood by developers of other platforms. The example shows how to retrieve data from the server, and page, search and edit data on the server, which are the core features of jqGrid. The author describes every step thoroughly and in a clear and simple form.

What I missed in the book is how to deal with custom styling. It is mentioned you can use jQuery UI themeroler, but doesn’t give any information or example how to further customize the styling of the grid. Also I thought it was too bad the author did not mention the option of virtual scrolling when describing the pager, which I like very much and is easy to implement.

The book is very easy to read and to follow. After going through the book, and the examples, a developer should have a sound knowledge of jqGrid, and be able to customize the grid to their needs. I remember the pain going through the online documentation and examples when I first started with jqGrid, this book is a real time-saver for people who want to start working with jqGrid. Not every feature or option is covered in the book, it only counts 58 pages, but I think gives you enough baggage to get started and explore more features, like subgrids, treegrids and data grouping, on your own using the online documentation and examples.

Presenting iDeal.NET

Robin van der Knaap — Mon, 04 Jun 2012 07:00:00 +0000

iDeal is the leading online payment platform in the Netherlands. Last year when working on bidfortickets.nl I had to create an API to interact with our iDeal provider (Rabobank) to handle all online payments. I noticed that a lot of examples existed out there especially for PHP, but nothing really usable for the .NET ecosystem. So I decided to open source the API on GitHub and call it iDeal.NET. The API takes care of all communications with the iDeal provider and is easily integrated into a .NET (web)application.

Supported iDeal versions

iDeal.NET is aimed at iDeal Professional (Rabobank), iDeal Zelfbouw (ABN Amro), iDeal Integrated and iDeal Advanced (ING Bank). These versions allow for real-time feedback on transactions.

iDeal.NET does not yet support iDeal Basic (ING Bank), iDeal Hosted , iDeal Lite (Rabobank) and iDeal Zakelijk which are easily implemented in applications but do not allow for real-time feedback on transactions.

Source, samples and documentation

The source code is hosted on GitHub, this is where you also find the documentation. The solution includes a sample ASP.NET MVC application which shows the basis usage of iDeal.NET. The sample application uses www.ideal-simulator.nl to simulate the entire process of paying and retrieving status of payments. A live version of the example can be found here.

Usage

Implementation of iDeal is basically about three types of requests: directory requests, transaction requests and status requests. iDeal.NET provides an easy to use API to send the requests and handle the responses.

A directory request for example, which retrieves a list of bank (issuers), is as easy as:

You can find detailed information about the usage of the API on GitHub

Enjoy!