Secure Net 5 Blazor Web Assembly with JWT and IdentityServer4 Admin UI

Man is a tool-using animal. Without tools he is nothing, with tools he is all. — Thomas Carlyle

Introduction

Blazor WebAssembly is Microsoft's newest UI framework for building Single Page Application (SPA), using C# rather than JavasScript. Like any other SPA, the Blazor WebAssembly App relies on JSON Web Tokens (JWT) for access control. The anatomy of JWT consists of ID token and Access token. The ID token confirms the user’s identity, while the Access token grants the user’s permission to access API Resources.

What would it take to integrate JWT into Blazor WebAssembly App? Are there tools or libraries out there to help developers with JWT coding? Thanks to Opensource communities, the answer is yes. By leveraging Opensource tools, developers can secure the Blazor WebAssembly App with as little as 14 lines of code.

Opensource Project Highlights

To develop this tutorial, I have reviewed and integrated tools and techniques from the following high-quality opensource projects:

IdentityServer4 — this project has 7.9K stars on Github. It is the #1 opensource project for securing enterprise ASP.NET WebAPI by Brock Allen.
IdentityModel/oidc-client-js — this project has 2.1K stars on Github. It is a library to provide OpenID Connect (OIDC) and OAuth2 protocol support for client-side, browser-based JavaScript client applications by Brock Allen.
IdentityServer4.Admin — this project has 2.7K stars on GitHub. It is the best Admin UI of the IdentityServer4 and Asp.Net Core Identity by Jan Škoruba.

Prerequisites

The following tools/skills are recommended.

Visual Studio 2019 Community — free code editor for C#.
Knowledge of Git such as cloning Github repository to local.
Familiar with OIDC and oAuth2 terminologies.

GitHub Repos in this tutorial

The source code for this tutorial is available on GitHub. You can clone/run these projects out of the box. Then, follow the instructions in this tutorial to configure the security.

workcontrolgit/TokenProject.AdminUI — this is a repository of IdentityServer4 Admin UI written in C#. The Visual Studio solution consists of three web projects Admin UI, Admin API, and IdentityServer4
workcontrolgit/BlazorWebAssemblyAppId4 — this repo contains a Blazor application pre-configured with OIDC client library to login IdentityServer4. The app provides login/logout features.

Tutorial Content

The content consists of three parts:

Part 1: Download the Blazor app and IdentityServer4 Admin UI Git-clone source code from GitHub repositories. Review application configuration settings and run both apps on localhost.

Part 2: Configure IdentityServer4 to secure Blazor app. Use the Admin UI to register Blazor app as a client in IdentityServer4. Configure PKCE code flow, URI redirect, and CORS. Specify claims such as email, openid, roles, and profile.

Part 3: Log in to the Blazor app and inspect the JWT Login to the Blazor app and view information inside the Id token and Access token using the jwt.ms website.

Figure 1 depicts the application architecture referenced in this tutorial. It shows the JWT interface and communication ports between application components running on localhost. The architecture consists of Clients, ApiResources, and Token Service (CAT).

Figure 1 — Application Architecture of Clients — ApiResources — Token Service (CAT)

The Clients (can be Blazor, Angular, React, etc.) request JWT from the Token Service, which runs an instance of IdentityServer4. The Token Service is responsible for issuing and validating JWT. When a given Client needs to access the API Resources, it will send the JWT via the browser header to the API Resources. The API Resources will validate the JWT prior to response with data. For more information about application architecture and security, see CAT architecture pattern for modern app SPA/Mobile.

Application Security Use Case

Imagine that you are working on a Blazor WebAssembly app to manage company Employee Profiles. There are three roles in the app:

employee — users in this role can view and update their own profile
manager — users in this role can view the profile of their subordinators and approve profile changes
HR admin — users in this role can enroll new employees and make administrative edits

In the Blazor application, when a user successfully logs in using the credentials, a JWT will be saved locally in the browser, typically in local or session storage. In Chrome Developer Tools (hit F12 when you are in Chrome), developers can see the JWT from the Application tab. Figure 2 depicts an example of JWT data such as access_token, id_token, and profile in Local Storage.

Figure 2 — Example of JWT in the Local Storage

When the user wants to access a protected WebAPI resource, the Blazor app will retrieve the JWT access_token from local storage and send the access_token in the Authorization header using the Bearer schema. The user’s roles should be included in the access_token, so the backend API can verify access based on roles.

Part 1: Git-Clone Blazor app and IdentityServer4 Admin UI

In this part of the tutorial, we will git-clone source code of a Blazor app and IdentityServer4 Admin UI repositories from GitHub and run them on localhost.

Task 1.1- Git clone Blazor WebAssembly App

Using Visual Studio, we are going to clone the Blazor WebAssembly App source code project from Github.

To access the Git clone screen (see Figure 3 for visual aids),

Start Visual Studio 2019
Select the option Clone a Repository

Figure 3— Visual Studio 2019, Get started options

On the Clone a repository screen (see Figure 4 for visual aids)

In Repository location field, enter https://github.com/workcontrolgit/BlazorWebAssemblyAppId4
In Path field, enter C:\apps\devkit\Clients
Click on Clone

Figure 4— Clone Blazor WebAssembly App source code from Github

Once the clone is done, you should see the Blazor app in Visual Studio > Solution Explorer. Open file Program.cs inside the project root folder. As shown in Figure 5, line 27 binds to the oidc configuration section in the appsettings.json to support login. We will go into detail of the oidc configuration to work with IdentityServer4 in Part 2 of the tutorial.

Figure 5 — Blazor WebAssembly App in Visual Studio Solution Explorer

Task 1.2- Git clone the IdentityServer4 Admin UI

Using Visual Studio, we are going to clone the IdentityServer4 Admin UI C# source code project from Github.

Follow the steps below to download the source code:

Start Visual Studio 2019 and select the option Clone a Repository
Clone the repo https://github.com/workcontrolgit/TokenProject.AdminUI to C:\apps\devkit\TokenService\v2\TokenProject (see Figure 6 for visual aids)

Figure 6 — Clone IdentityServer4 Admin UI source code from Github

In the Solution Explorer (see Figure 7 for visual aids), right mouse click on the solution name, select Properties, and set Multiple startup projects to three projects.

TokenProject.Admin
TokenProject.Admin.Api
TokenProject.STS.Identity

Figure 7 — Set Multiple startup projects in Visual Studio

Task 1.3 — Run Blazor and IdentityServer4 Admin UI on localhost

To run the application, start the IdentityServer4 Admin UI solution first and then the Blazor app.

1.3.1 Run IdentityServer4 Admin UI

In Visual Studio, run the solution by hitting F5. You should see three instances of the Chromes running. Refer to Figure 1 for the port numbers of three web projects in the Visual Studio solution.

1.3.2 Run the Blazor app

In Visual Studio, run the solution by hitting F5. You should see the app running in the browser with URL https://localhost:44369.

Part 2: Configure IdentityServer4 to secure Blazor app

This part of the tutorial will walk through the steps to:

Setup API Scopes
Register the Blazor app as a Client
Configure the Client with URI redirect, CORS, and claims (such as email, openid, roles, and profile)

In Part 1 of the tutorial, we cloned the Blazor app to local. The settings for the Blazor app to connect to the IdentityServer4 are in the file appsettings.json inside the wwwroot folder. See Figure 8 for detailed settings and values of Authority, ClientID, ResponsType, RedirectUri, etc. These settings must match the settings we are going to set up in IdentityServer4 using the Admin UI.

Figure 8— Settings inside appsettings.json file to work with IdentityServer4

Also in Part 1 of the tutorial, we have run the IdentifyServer4 Admin UI from Visual Studio. Locate the browser instance with the login screen as shown in Figure 9, and log in with the account (admin, Pa$$word123).

Figure 9— Admin UI login screen on localhost

Task 2.1 Set up API Scopes

To add an API scope (see Figure 10 for navigation aids), follow the steps below:

Click on Clients/Resources menu and select Api Scopes sub menu
Click on Add Api Scope

Complete the API Scope form with data as shown in Figure 11. Be sure to specify role in the User Claims field as this will include user’s roles in the Access Token. Then click on the Save Api Scope button.

Task 2.2 Register a client app

To register the Blazor app as a client (see Figure 12 for navigation aids), follow the steps below:

Click on Clients/Resources main menu
Select Clients sub menu
Click on Add Client

Figure 12— Menu and option to add a new client

On the client form (see Figure 13 for visual aids),

Enter Blazor.Spa in the ClientId
Enter Blazor WASM Client in the Client Name
Click on Single Page Application — Javascript Authorization Code Flow with PKCE tile
Click on Save Client

Figure 13— Form to register new SPA client

Task 2.3 Configure the client Blazor app

In this task, we will configure settings for the client Blazor app.

Task 2.3.1 Configure Allowed Scopes

On the client Basic tab, specify the claims in the Allowed Scopes field as shown in Figure 14.

Figure 14 — Screenshot of Basics tab > Allowed Scopes section

Task 2.3.2 Configure Redirect Uris

The redirect Uris values are authorized URLs that the IdentityServer4 can redirect to after login. Since the Blazor app will run on localhost port 44369, set up URLs as shown in Figure 15.

Figure 15 — Screenshot of Basics tab > Redirect Uris section

Task 2.3.3 Configure Post Logout Redirect Uris

On the Authentication/Logout tab, set up the Post Logout Redirect Uris as shown in Figure 16.

Figure 16 — Post Logout Redirect Uris setup

Task 2.3.4 Configure CORS

Cross-Origin Resource Sharing (CORS) is an HTTP-header based mechanism that allows a server to indicate any origins other (domain, scheme, or port) than its own from which a browser should permit loading of resources.

On the Token tab, set up the CORS as shown in Figure 17.

Part 3: Log in to the Blazor app and inspect JWT

The Blazor app is pre-wired with the OIDC library to login to the instance of IdentityServer4 running on localhost (as part of the IdentityServer4 Admin UI). Click on the Log in link (see Figure 18 for visual aids).

Figure 18— Blazor App with OIDC library integration

After clicking on the login button, it redirects to IdentityServer4. Log in with the account (admin, Pa$$word123). See Figure 19 for visual aids.

If you log in the first time, it will prompt for a consent screen. Click on Yes, Allow button. See Figure 20 for visual aids.

After login, it will redirect back to the Blazor app. You can view the JWT token from Chrome Developer Tools > Application > Session Storage. See Figure 21 for a screenshot of the access_token and id_token.

Figure 21— Screenshot of the Blazor app after login

You can copy and paste the signed id_token into the jwt.ms website and view the decoded Id Token as shown in Figure 22.

You can copy and paste the signed access_token into the jwt.ms website and view the decoded Access Token as shown in Figure 23. Notice the role claim contains value MyRole the scope includes app.api.employeeprofile.read.

Congratulations!!! You have successfully logged in to the Blazor app and the JWT will be saved in the local storage.

Bonus: The Admin UI provides screens to manage users and roles via the Users/Roles menu. See Figure 24 for navigation aids. You can add additional roles such as employee, manager, or HR Admin and assign those roles to the admin account. You can then verify that these roles are included in the AccessToken. Give that a try!

Figure 24 — Menu to manage users and roles

Online Demo

Developers love to see working source code. We all like to experiment with how something works, and then decide whether we want to spend our valuable time learning it. Check out the live demo. Log in with the account (janedoe, Pa$$word123).

Summary

In this tutorial, we learned:

How to use the Admin UI to configure a Blazor app as a Client to support login using PKCE flow.
The basics of client app registration and OIDC and oAuth2 configuration to support authentication and authorization.

The $64,000 Question: How many lines of code does it take to secure Blazor WebAssembly App with PKCE? The answer is 14 lines — one (1) in program.cs (see Figure 5) and thirteen (13) in appsettings.json (see Figure 8). There is little code to write because most of the work is configuration-related and can be done via the IdentityServer4 Admin UI. What is even more important is that the Blazor WebAssembly App is secured by the proven Opensource project IdentityServer4, which is written and maintained by the application security professional team and is recommended by Microsoft.