That has changed in the meantime. The community has grown considerably and so has the range of libraries and tools that can be used for unit tests. While Asp.Net Core is the absolute standard for a REST API, there is hardly any software project that uses the same setup for unit tests.

The choice of a unit test project setup is also often very much driven by developer preference and opinions. I have even seen developers insisting on a specific unit test framework at the customer site.

Even though no project has ever failed with the selection of the unit test framework, it does have an impact on the productivity, maintainability, and readability of the code. And of course, I also have my preferences, which I would like to describe here.

The test framework

Let's first discuss the unit test framework we use.

I started using XUnit during the early days of .Net Core. At that time there was no framework besides XUnit that ran on .Net Core. The MSTest framework was ported later, but I like the ability of XUnit to write simple data-driven tests. Also, XUnit provides an easy way to share context between tests with the fixtures. This also makes it easy to write database and integration tests. There would also be NUnit in the field, but I never like NUnit, since it is quite heavyweight compared to XUnit.

The mocking library

Mocking is also an important aspect of unit testing. I have used NSubstitute and Moq in the past. I like Moq a bit more since it is a bit more powerful about mocking protected members and most of the projects I joined used Moq, so it is quite popular.

But I don't use Moq alone, I always use it in combination with Moq.AutoMocker. AutoMocker creates an instance of a target class and automatically mocks all its dependencies. When I introduce a new constructor parameter in a service I want only touch the tests that test some specific aspects of a new dependency and not all tests. AutoMocker helps with this approach since it adds the ability to create an instance of a class and automatically mocks all dependencies.

Example from the Moq.AutoMocker documentation:

var mocker = new AutoMocker();
var car = mocker.CreateInstance<Car>();

car.DriveTrain.ShouldNotBeNull();
car.DriveTrain.ShouldImplement<IDriveTrain>();
Mock<IDriveTrain> mock = Mock.Get(car.DriveTrain);

The fake data generator

In a project with large entities, it is a big effort to provide the test data. In various projects we implemented so-called entity generators. Entity generators are simple and configurable classes to create entity instances.

public class AgendaItemBuilder : EntityBuilder<AgendaItem>
{
    private string _title;

    public AgendaItemBuilder WithTitle(string title)
    {
        _title = title;
        return this;
    }

    protected override async Task<AgendaItem> EnhanceEntityAsync(AgendaItem entity)
    {
        entity.Title = string.IsNullOrEmpty(_title) ? $"Title of {nameof(AgendaItem)} {unique}" : _title;

        return await Task.FromResult(entity);
    }
}

This can be used for following:

var builder = new AgendaItemBuilder()
    .WithTitle("My Title");
var entity = builder.Build();

The advantage of those builders is, that you have a shared class preparing the test data for a specific entity. But it is still a big effort to write and maintain them. Another drawback is that the test data contains static data which are always the same until it is specified otherwise.

A while ago I came across a library called Bogus. Bogus uses a random generator to generate test data. The test data is context-specific, e.g. addresses, names, phone numbers, etc. Bogus has a huge list of data generators. We can inherit from a Bogus faker and share its configuration.

public sealed class AgendaItemFaker : Faker<AgendaItemFaker>
{
    public AgendaItemFaker()
    {
        RuleFor(c => c.Name, f => f.Random.String(1, 10));
    }
}

A fake can be used like the following snippet:

var faker = new AgendaItemFaker();
var item = faker.Generate();

I don't use Bogus alone, I always use it in combination with AutoBogus. AutoFaker is a wrapper of the Bogus Faker class and provides conventions and integration into Moq which makes everything fit together.

Our fake looks like this now:

public sealed class AgendaItemFaker : Faker<AgendaItemFaker>
{
    public AgendaItemFaker()
    {
        Configure(builder =>
                {
                        builder.WithConventions();
                });
    }
}

With this, the effort to write and maintain my test data generators are reduced to a minimum.

Summary

Here we are, at the end of the article. Testing code should be as clean and well-maintained as our productive code. My tech stack has been built with the goal of reducing boilerplate code and the maintainability effort of the tests to a minimum.

I'm using the following libraries in combination:

• XUnit

• Moq

• Moq.AutoMocker

• Bogus

• AutoBogus

What is your opinion? Do you use a different tech stack? Did I forget something?

Pagination is one of the major mechanisms to reduce page loading time and is widely adopted. It is a good practice to do pagination when you have many rows, resp. an unknown amount of rows. It can help to improve the performance with three aspects:

1. It reduces the query time on the database

2. It reduces the payload size returned to the client

3. It reduces the amount of elements the browser needs to render

Especially the third point can help a lot when there are some expensive elements such as images per data row.

How does pagination generally work

The mechanism is actually quite simple. The data as a whole needs to be split into junks of the same size. These junks we call pages.

Every page has a page number, a size , and an offset. In order to get a reliable result the data needs to be sorted.

We now can translate this into a database query. Usually, the databases don't know the concept or pages. But they have a syntax to skip and take a certain amount of rows. In terms of SQL, it would be offset and fetch. We can translate the page number into this syntax. Assuming the pages start with 1 we can do following query skip = (page - 1) * size, take = size.

A full SQL query loading page 2 could look like this:

SELECT * FROM [Posts]
ORDER BY [Published]
OFFSET 10 ROWS
FETCH NEXT 10 ROWS ONLY;

If we know the total amount of rows, we can calculate the total page count as well Math.Ceil(totalRowCount / size).

Implementing pagination with NextJS server-side rendering

Since I have a database, concrete MongoDB, for storing my articles in place I need to use the SSR mechanism of NextJS to pre-render the articles on the server side.

Assuming I have a UI which is illustrated in the next image. It contains a table of data and controls for navigating through the pages. In my case, I allow only navigation forward and backwards. In some implementations, there are controls for a dedicated page. But in the end, this does not matter.

Having the design in place we need a way to tell the server-side rendering which page to load. We do that by passing it with the URL as a query parameter https://domain/blog?page=2.

I'm on a project with a completely different topic now. However, the software architecture and the way business entities are getting processed are quite similar. So I remembered this architectural pattern from those times. Since I consider that a very good fit, it might be worth an article.

Pipes and filters

Task-based UI is a special kind of micro frontend architecture pattern invented for a very specific use case.

Imagine we have a business entity that follows a well-defined business process during its lifetime. We can model that with the well-known pipes and filter architecture pattern.

This pattern is quite flexible. It can enforce the sequential flow of the business process. But it is not necessary. Certain process steps can also be handled in parallel.

It fits very well into a microservice architecture where every task along the business process gets handled by its own microservice. But what about the UI for such an application? We don't want to lose the benefit of the decoupling gained through the microservice architecture. I wrote a few articles about this topic. It basically leads us to go in the direction of micro frontends or self-contained systems.

We can actually go a step further and introduce an SCS per process step. Every SCS has its own UI and is responsible for handling the process step it is responsible for in its own UI.

The idea behind a task-based UI

There is actually nothing new until now. Anything I described so far we do in an SCS system as well. The idea of the task-based UI starts with the need for an overview of the entities describing their status along the process. This is not a simple thing since the processing of the entities is now distributed.

We could build an SCS gathering all the data from the process-related data over an API and build a UI that aggregates this data. This will build up a strong dependency on those SCS and this is something we actually want to avoid. We have a loose coupling through the asynchronous nature of the pipes and filter architecture and destroy it more or less with an aggregation.

What is, when we would leverage the micro frontend approach? Every SCS can provide a frontend snippet showing their piece of status from the corresponding entity. This is will return the responsibility of displaying its own data to its origin and we can loosely couple it in the frontend. This UI composition pattern is called task-based UI.

How we can implement this technically?

Task-based UI's are a special kind of micro frontends. Basically, every technical approach of the micro frontend architecture pattern also works for task-based UIs. A modern way to build micro frontends will leverage the new standard of web components. I will not explain how to build micro frontends and web components in this article. But give you a small example of how it could look like using them. Important is, that we pass in only the identifier of the processed entity. The rest is the responsibility of the corresponding microservice or SCS:

<script src="...../financial-instruments.js" />
<script src="...../suitability-check.js" />
<script src="...../document-handover.js" />
<script src="...../contact-notes.js" />

<fi-transaction-proposal>
    <financial-instruments order-id="1" />
    <suitability-check order-id="1" />
    <document-handover order-id="1" />
    <contact-notes order-id="1" />
</fi-transaction-proposal>

Summary

Entities that will go through several steps of a business process can be distributed with the pipes and filter architecture pattern. Aggregating and displaying the data from the different services/steps will break the benefits of the distributed and loosely coupled architecture. We can mitigate this problem by introducing the task-based UI architecture pattern. This is a special type of micro frontends dedicated to displaying the status(es) of entities that go through a distributed business process.

What do you think about this architectural pattern? Did you already have some experience with something similar? Leave a comment and discuss it with me.

According to Medium the reading time is based on the average reading speed of an adult (roughly 265 words per minute).

To get a basic implementation of this I could get rid of the Markdown markings and count the words by splitting the string by spaces. Images add additional time to the reading time and this approach would not consider that.

Luckily I found a nice npm package reading-time that does this for me. It can handle plain text, HTML, and markdown.

All I need to do is install the package.

npm install reading-time --save-dev

And use it to convert my markdown content to an estimated reading time

import readingTime, { ReadTimeResults } from 'reading-time';

const result = readingTime(post.content)

The result contains several properties. I can get the text 3 min read by accessing result.text or alternatively the reading time as a time result.time, in minutes result.minutes and the word count result.words.

In the end, it was very simple for me to integrate an estimated reading time into my blog.

This applies not only to the backend but also to the frontend. For a long time, front-end applications were somewhat neglected. Often the frontend was developed by the designer and cross-directional beginners or was done by the developers on the side. After all, pixel pushing was not so popular with the developers. The "real" work, namely in the backend, was given more attention and done seriously. This inevitably led to the front end being more or less a patchwork. But user interfaces in general have become very important in recent times. Hardly any application can be brought to the people these days without an appealing user interface. And that makes it all the more important that the above-mentioned attributes are also taken into account in the frontend.

I have worked on several, very large, projects in my career. I have seen and helped develop several types of modularization in the frontend. The community has also moved forward. Topics such as microservice architecture have also an impact on the frontend architecture with new practices and patterns.

In this article, I am going to discuss some of these modularization patterns.

The monolith

I would like to start with traditional monolithic architecture. What used to be the standard is somewhat unpopular today, but it has its justification.

Especially for smaller software projects, it is still common to fall back onto this architecture. Using a certain architecture is always associated with compromises. In the case of smaller projects, this is definitely in favor of a monolith. The advantages are clearly in the simplicity of a monolithic architecture. There is only one system that needs to be developed and maintained. And the communication between the components, apart from a SPA frontend, takes place exclusively in memory.

But this does not mean that a monolith is completely un-modularized. There are many software architecture patterns such as layered architecture, onion architecture, ports, and adapters, or the popular Clean Architecture pattern from Uncle Bob helping structure a software application.

However, these have in common that they modularize an application in horizontal layers. This horizontal orientation of, not only the presentation layer but of the whole application makes certain problems more complicated. I am talking about issues such as working in several teams, the independent deployment of each component, and long-term maintenance, including the transition to new technologies.

At some point, the compromises become too painful and it is worth moving on. But at what point, or at what size of software application is this point? Personally, I always use the single responsibility principle as a guideline. I am not talking about all the infrastructure plumbing that is always involved. But as soon as an application has several responsibilities in terms of business features, it is time to consider an expansion of the architecture.

Modularized monolith

To mitigate these problems, the application must be modularized vertically. This means that the application is divided into modules across all horizontal layers. A module in each layer has its own, more or less independent, part. From the frontend down to the database.

The boundaries of a module are usually defined by a business feature or a group of features. For this purpose, the methodologies of Domain Driven Design are often utilized and the application is subdivided into so-called bounded contexts. Then a module is generated for each bounded context.

Modularization also raises the question of how far to go. We have a wide range of options, from simple folder structures to distributed systems. But as soon as communication goes beyond the process boundary, the complexity of the system increases considerably. Because then, topics such as API versioning, service availability, service discovery, network instabilities, authentication, and authorization have to be dealt with.

Again, the trade-offs of the available options need to be weighed. You want to make your application better structured, more maintainable, and more accessible for several teams. However, people often fear the costs of a distributed system. This brings us to the compromise where simple approaches such as folder structures are used to split an application into modules within the application boundaries. We are talking here about modularized monoliths.

As mentioned above, there are many technical possibilities to modularize an application within the application boundaries. The simplest way is to organize the code into a specific folder structure. In some projects, they even go a step further. The code can also be organized in its own libraries (jar, dll, npm, etc.). This works in the backend as well as in the frontend. And with a little extra effort, an independent deployment can even be achieved via drop-in replacement.

However, a modularized monolith also has its limitations. First of all, it is difficult to enforce the design and module boundaries. Violations creep in very quickly. This has a lot to do with the discipline of the developers. So you have to be careful not to accumulate a lot of technical debt over time. On the other hand, the modules are highly interdependent. Technology selection, deployments, and maintenance cannot be chosen independently at all, or only to a very limited extent. Even in the frontend, a decision is made for a technology that is used for the entire application. Upgrades or even a migration to newer technologies are difficult and can be very expensive.

I have seen many modularized monoliths in my career. 10-20 years ago this was simply the standard architecture used for web applications. There was early talk about service-oriented architecture (SOA). Of course, this alleviates the problem, but only in the backend. The user interface is still mostly a monolith.

We are often asked to revitalize such systems, i.e. modernize them. In most of cases, we fall back on a more modern architecture that is related to microservices and micro frontends - the Self-Contained System (SCS). Read my article about application revitalization.

Self-contained systems

There is a lot going on in the development community about microservices. Microservices solve exactly the problems I mentioned earlier and bring even more advantages, such as independent scaling. But also with microservices, we tend to have a UI monolith. The community has an answer ready for that as well, micro frontends. Before we get into this topic, I would like to talk about self-contained systems, a special kind of micro frontend architecture.

I have already mentioned that you can cut a monolithic system along its domains and wrap it into modules. Taking the approach further and wrapping each domain into separate, replaceable web applications, we refer to this application as a Self-Contained System (SCS).

An SCS contains its own user interface, specific business logic, and separate data storage. They communicate with other systems via hyper links, RESTful services, or asynchronous messaging. An SCS is responsible for its core domain and master of its own data. Data and logic can be shared via a well-defined API. An SCS can consume microservices to solve domain-specific problems.

You see, this way every SCS can be developed with its own platform, frameworks, and release cycles. This enables a future-proof and maintainable system. Of course, this comes with a price. Every application needs to have its own CI/CD pipeline and its own deployment procedure. We need to think about how certain constraints, such as common layouts, styles, and components can be guaranteed.

This problem can be solved with different approaches as well. A pragmatic solution would be to do nothing at all and leave design and layout to the SCS. In certain cases, this may even be desirable.

A step further is the introduction of UI guidelines, which are not enforced, but provide a strict framework. This still gives the applications a lot of freedom and maximum independence. Each system must ensure that it adheres to the guidelines. Accordingly, different interpretations and adaptation speeds occur quickly. Under certain circumstances, the system may not appear to be made from a single mold.

If you want to enforce a design, you cannot avoid sharing something. However, there is always the risk that the individual SCSs will experience a technology lock. For example, if you make a library with Angular components, the SCSs are forced to implement their frontend in Angular. And that is exactly what we want to avoid. I have had good experiences with extracting style sheets with colors, spacing, typography, etc. into a library and integrating them into the applications. It is also a good idea to make a technology-agnostic component library with WebComponent. There are frameworks like StencilJS that are specialized for such use cases.

What has also worked well for me is using the microfrontend approach for layout and components like headers and footers. This is done by using web components that are compiled into a single file bundle and hosted in a CDN. An SCS can dynamically include these components at runtime via <script> tag. By the way, this also works very well when an SCS needs to render concrete content of another SCS. We name it widgets. This ensures that the responsibilities of the SCS focused on its own domain. I wrote an article about this topic a while ago.

This way we achieve maximum independence for shared components. But still, don`t forget that everything that is shared hurts and you want to avoid this!

Micro frontend

The last UI composition pattern I want to cover is the microfrontend architecture pattern.

This pattern has its origin in the microservice architecture. Microservices solve many of the problems already discussed. But with microservices, we still end up with a monolithic UI.

This means that the advantages we gain from the microservice architecture are lost in the frontend. But we actually want independent teams, technology selection, deployment, scaling, and release cycles in the frontend as well. Microfrontends address this problem.

The idea is that each microservice also has its own frontend. Compared to a self-contained system, however, this is not an independent application. In a microfrontend architecture, a so-called shell is needed. The shell is a very lean web application that combines the frontends of the individual microservices into one application. The communication of the microservice is preferably done via microfrontend. That means, via hyperlinks or HTML properties and events.

An example could be a shop selling video games. Team product is responsible for the product page and everything that needs to be included here. Team checkout is responsible for everything regarding the purchase process and team marketing manages the product recommendations on this page.

Again, there are many technical ways to implement this, some of them are:

• Manually load and embed an HTML file via JavaScript

• The micro frontends can be integrated via iFrames

• Compose your frontend with WebComponents

As you see, the technical support for this pattern isn't that great. There is still a lot of manual work involved. Nobody wants to manually load and embed HTML via JavaScript and iFrames are troubleson concerning scaling of its content. The most promising approach is to compose your frontend with modern web components. There are a lot of frameworks that are specialized in authoring web components such as Angular Elements, StencilJS, or LitComponent. This works the same way I used to integrate a header into a Self-Contained System. Web Components get compiled to a single file bundle, deployed to a CDN, and consumed via <script> tag.

We also have the same problem with sharing styles and layouts across the micro frontends. We can rely on guidelines or develop a framework-agnostic UI library with web components.

I want to mention at this point, that there are also JavaScript frameworks emerging which are specialized in microfrontends. One of those is Single SPA. I never tried it out so far, but it could be a big help in doing microfrontends.

Summary

I covered the 4 most used UI composition patterns I am aware of. It starts with a monolithic system, breaking it into modules and Self-Contained Systems. At the end of the line, I covered the microfrontend architecture.

One of the key points here is considering trade-offs. Mostly between simplicity and the advantage of independent teams, technology stacks, deployments, and release cycles.

And one thing to mention again: it hurts to share code!

What do you think about those UI composition patterns? What is your experience? Leave a comment and discuss it with me.

This can be very frustrating and we even haven't talked about repeating this when you are working on a micro-service-based project or want to flush your dev env setup.

I'm working on lots of self-contained systems and micro-service-based projects. And it can happen that I need to switch those projects several times a week. So it is crucial for me to avoid such wasted time. I automate the dev env setup as much as possible and keep improving it. With this approach, you can get up and running within minutes!

Use docker to install your infrastructure

First of all, we can avoid installing a huge list of software infrastructure, such as SQL Server, Message Broker, SMTP Client, Identity Provider, etc. All this can be set up by using docker.

Using docker has several advantages:

• You don't pollute your operating systems with these applications. Even when you uninstall them, some relics are left in your system.

• Everyone on the team has exactly the same versions of the infrastructure.

• Everyone in the team automatically gets additional infrastructure, without installing them manually.

• You can get and run this software within minutes, it actually only needs one command to start them all.

Using docker reduces the list of software to install to the following and this is something that will be the same for all of your projects, so you do it only once:

• GIT (or your preferred source version control system)

• Docker Desktop

• SDK's (Usually .Net Core and Node)

• IDE (In my case Visual Studio, Rider, or whatever)

And then I prepare a docker-compose file, containing all required infrastructure, in the root of the SVC repository:

version: "3.8"

services:
  mssql:
    container_name: mssql
    image: mcr.microsoft.com/azure-sql-edge:1.0.6
    ports:
      - 1433:1433
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=<any password>
      - TZ=Europe/Zurich
    volumes:
      - local-dev-sql:/var/opt/mssql

  azurite:
    container_name: azurite
    image: mcr.microsoft.com/azure-storage/azurite:1.4.2-linux-amd64
    ports:
      - 10000:10000
      - 10001:10001
      - 10002:10002
    volumes:
      - local-dev-azurite:/data mcr.microsoft.com/azure-storage/azurite

  smtp-mock:
    container_name: smtp
    image: rnwood/smtp4dev:v3.1
    ports:
      - "6200:80"
      - "2525:25"

volumes:
  local-dev-sql:
  local-dev-azurite:

And it will require only one command to start up everything:

docker-compose -f docker-compose.dev-env -p my-app up

You can flush your infrastructure with only one command as well:

docker-compose -f docker-compose.dev-env -p my-app down -v

Script application-specific configurations and setups with Nuke

The first part of your dev env setup is done with that. Usually, there needs to be additional things done. Things like local configurations, database setup, etc.

A few years ago, I stumbled over Nuke. A build scripting engine running plain .Net code and is fully integrated into your .Net development IDE. Everyone in our teams is used to writing C# code, so everyone is comfortable in using this tool. And this is the reason why I love this great tool so much. Kudos to Matthias Koch for it!

As you might guess, I'm using Nuke scripts to set up everything else which usually has to be done manually. I'm not going to write a tutorial for nuke at this place, but just as much as need to get you a picture of it.

A nuke script can be initialized with the following commands:

dotnet tool install Nuke.GlobalTool --global
nuke :setup

This will guide you through a wizard and set up a Nuke project including some startup scripts for you. Then you can start to implement your automation script with it.

class Build : NukeBuild
{
    public static int Main() => Execute<SetupDevEnv>();

    Target SetupDevEnv => _ => _
            .DependsOn(CreateOrUpgradeDatabase)
        .Executes(() =>
        {
             // This one usually has no implementation, but calls other targets which are doing their jobs
        });

    Target CreateOrUpgradeDatabase => _ => _
        .Executes(() =>
        {
            // Create or upgrade databasae implementation
        });
}

And afterward you can execute the script with the following command:

nuke.sh --target SetupDevEnv

And with that your dev env is ready and you can start hacking.

Final dev env setup steps

With all this in place, your dev env setup will be reduced to the following steps.

Dev Env Setup Instruction

Required software:

• GIT

• Docker Desktop

• DotNet Core SDK

• NodeJS

• Rider or Visual Studio

Clone the repo:

git clone <repor-url> my-app

Startup infrastructure:

docker-compose -f docker-compose.dev-env -p my-app up

Setup dev env:

nuke.sh --target SetupDevEnv

Great, that's it! You can open your IDE and hit F5.

This helped us a lot because it reduced the coupling of the shared code to the applications in our system. However, we started to struggle with it again after an inconsistent navigation in the header due to an update in the shared header component. Let's be serious, this is bad and should not happen! It is ok when some little CSS styling is not up to date in the application. Most likely nobody will recognize that. However, the navigation must be consistent in a self-contained system. It is bad when the navigation to an application suddenly disappears when the user navigates through the system. Even worse, when there is a dead link in the navigation.

Dynamically rendered Layout

We discussed two options to solve that problem:

• Extracting the header and footer into its own shared library. All the infrastructure for this approach already exists. It would be easy to build and would make it easier to automatically integrate and update it in all applications. But it still has a dependency on certain npm package versions which can turn an update into a bigger exercise.

• Deploy the header and footer separately and integrate it into the applications during runtime. This is clearly a step towards a micro-frontend architecture. We initially decided against micro-frontends because it would increase the complexity and our project is not large enough that it would be worth using that pattern. But for the current problem, it seemed to be a good fit.

We decided, obviously, to deploy the header and footer separately and integrate it at runtime into our applications. That we would implement it by using WebComponents, was also clear from the beginning. Still open was the Framework we wanted to use. We are using Angular. Angular Elements could be a fit but has some drawbacks.

Our goal was to create a single js file, deploy it to Azure Blob Storage, and dynamically include it via <script> tag. Let's have a look at the options we evaluated:

• Angular Elements, obviously. It is possible to create a single file with ngx-build-plus which is what we would like to have. But Angular Elements is building a complete Angular application into the WebComponent, hence it will be a rather large bundle.

• StencilJS, developed by the Ionic team to make their UI components independent of the UI framework.

• LitElement, just another lightweight framework to write WebComponents.

We decided to use StencilJS. We think it is a better option than Angular Elements, even though it is actually designed for compile-time integration. We want to have a fast application and the bundle size of Angular Element is way larger than any output from StencilJS.

Create and Stencil project

Let's have a look at our setup with StencilJS and the integration in our Angular applications. We are using NX for our UI workspaces. Let's create an NX workspace with a StencilJS project.

First, we create the NX workspace with typescript presets:

npx create-nx-workspace my-workspace --preset=ts

Afterwards, we are going to create a Stencil project in our freshly created NX workspace by using the NX plugin from Nnext:

npm install @nxext/stencil --save-dev
nx g @nxext/stencil:library my-lib

The Nnext plugin provides a generator that allows to create our first component:

nx g @nxext/stencil:component my-header --project my-lib

This outputs a component skeleton like this:

@Component({
  tag: 'my-header',
  styleUrl: 'my-header.scss',
  shadow: true,
})
export class MyHeader {
  @Prop() first: string;
  @Prop() middle: string;
  @Prop() last: string;

  private getText(): string {
    return (this.first || '') + (this.middle ? ` ${this.middle}` : '') + (this.last ? ` ${this.last}` : '');
  }

  render() {
    return <div>Hello, World! I'm {this.getText()}</div>;
  }
}

I will not going to write a StencilJS tutorial at this place. But one thing I need to mention. Stencil provides several output targets. We actually want to have a single file bundle which would be the dist-custom-elements-bundle out target. Unfortunately, this has been deprecated. We use its successor dist-custom-elements. It does basically the same thing but produces a js file per component. This is the better way because it is better to load several smaller bundles than a large one. It will also be better for leveraging http2. We would prefer a single file because it means less file handling on our frontend, but we can work with that.

outputTargets: [
  {
    type: 'dist-custom-elements',
  },
];

Finally, we are deploying these output files in an Azure Blob Storage. But any static hosting would do the job.

It sounds that easy, but nobody on our team has real experience in StencilJS and is especially lazy load them in an Angular application. One problem worth mentioning is the handling of assets. If the component uses assets that get deployed, you need to make sure to load them with an absolute path. Relative paths get resolved to the URL where the application is deployed. We solved the problem by compiling everything (e.g. SVG icons and JSON translation files) into the bundle. This way, we don't need to load them during the runtime.

Consuming the WebComponents dynamically during run time

After creating and deploying our WebComponents, they need to be integrated into the frontend of our applications. A simple script element loading js bundle will do the job. Then we just can use the custom element:

<script type="module" src='https://cdn.jsdelivr.net/npm/my-name@0.0.1/dist/myname.js'></script>
<my-header></my-header>

We found a nice library, ANGULAR EXTENSIONS ELEMENTS, which makes it even easier to lazy load elements in Angular. It also supports displaying special components for the loading and error cases.

<my-header *axLazyElement="headerUrl; errorTemplate: errorHeader; loadingTemplate: loading; module: true"></my-header>

One thing which needs to be done to make this work is defining the custom elements schema on the corresponding Angular module.

@NgModule({
  declarations: [...],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  imports: [ LazyElementsModule],
})

Summary

Not all of our problems were solved by introducing a shared Angular library. We came to the conclusion that an independently deployed and lazy loaded header and footer would be the best solution for us. We decided to use WebComponents for that job. Finally, we implemented it with StencilJS and integrated it with the Angular Extension Elements library.

Implementing header and footer as a micro-frontend was not very smooth. We had a steep learning curve and spent a lot more time than expected. But we are very happy with the result and I, personally, would do that definitely again.

The drivers for building self-contained systems

Let's talk about our drivers to use the self-contained systems architecture before we go deeper into that question.

We were facing a situation, where our customer had two legacy systems running. They are doing more or less the same. Actually, one of them was supposed to replace the other one, which has never been completed entirely. For extending and replacing those two systems we have chosen the self-contained system approach. This gives us the flexibility to maintain and migrate separate parts of the system in the future more easily.

One important part of the self-contained system architecture is to keep them as independent and decoupled as possible, otherwise, we would lose the advantages why we have chosen this approach.

Enforcing UI design guidelines

We are working on a couple of applications in this system now. The user should not really recognize that he/she is browsing multiple applications. We can't avoid page loads due to the architectural design we have chosen. But design, styles, and layout should not look different between the app.

Sooner or later, we need to think about, how we can enforce these constraints. Now, self-contained systems have a lot in common with Micro Services.

One strong recommendation when building micro-services is to not share code between the services. Sharing code increases the coupling between the services. And that makes it harder to maintain them independently. There are some companies like Netflix that purposely share code though, but I think they are the minority.

The rule to not share code is also valid for self-contained systems. We don't want to touch the entire system of systems when we, for example, update an application to a new Angular version. On the other hand, we don't want to fix bugs in code which is used from multiple applications multiple times. Or change the style in all applications manually.

Introducing versioned libraries

We need to find a way in between. Sharing code directly creates a hard dependency on that piece of code and we want to keep the freedom to prioritize and decide when we touch an application. We decided to create versioned libraries containing the shared code. It is important to make it versioned because it allows you to update this library in an application independently and on demand.

Building, publishing, and consuming an npm library is easy. So everything fine? No! For us, it introduced a completely new constraint. We have two teams and we first had to learn how we handle this library. Questions like "How do we do versioning?", "How do we handle branching?" or "How do we handle changes, especially breaking changes?" needed to be answered.

We introduced Semantic Versioning to be able to express breaking changes. We are working in a mono repo. When we create a release branch we update the major version number of the develop branch to avoid version conflicts between the branches. And we keep a lean changelog to have an overview of the changes and breaking changes we did. We also have a gathering among the developers. We call it a dev exchange. This is the platform where we discuss and announce cross-cutting concerns like our shared libraries.

Retrospective

Would I do it again? I'm not that sure. It definitely brings some value for us. It works quite well for things like UI components and global styles, but it also introduced an overhead we actually don't want to have.

Nothing is a silver bullet. It did not solve all our problems with shared UI components at the end. With this approach, we still need to touch all the applications when we introduce a new navigation item. But that is another story.

• The application is so huge, that it is difficult to get into the code base, and the original knowledge is gone for a long.

• The code is too fragile so it got expensive to build more value with it.

• Old technologies and libraries are not supported anymore.

Unfortunately, it is very expensive to replace an old system that has been built over decades and it does not bring any business value to just rewrite them with new technologies. In the worst case, it never finishes and the old system keeps running forever beside the new application. Did I mention that syncing data between software systems is no fun and expensive as well? And what are we supposed to do in 10 years when the new system will be outdated as well? Do we rewrite it again and have 3 generations of systems running in parallel? Yes that happens, I'm working currently on such a project...

So we are locked in a loop, replacing applications. Actually, we want to add business value and not reinvent the wheel again. What can we do to break this circle? I use an architectural style which is called a self-contained system.

What is actually the problem of large legacy systems?

Before we dig deeper into this architecture, let's see what causes this problem. Why do those systems reach a state where we can't move forward or backward? One of the reasons is the monolithic nature of the architectures which were usually used for those kinds of systems 15 years ago. A common architectural style at that time was the layered architecture. They are cut horizontally into layers like the UI layer, business layer, and data access layer.

We are talking about large applications. Having only horizontal cuts in the system results in a tight coupling between features and modules. That makes it difficult to change things like migrating the UI to a newer technology. And that's just because it's so big. Where should we start? It's like opening the box of Pandora.

What about microservices?

Micro-services are well known to face problems like that. They enable the usage of different technologies, scalability, team decoupling etc. And they are small enough to be easily replaced by a new one when their technologies get outdated.

Are they really a solution? I won't say no. But micro-services get hyped maybe a bit too much. Micro-services are complex to handle. They introduce a lot more complexity into the system. Things like distributed communication, traceability, resilience, monitoring, etc need to be adapted to micro-services. Further, micro-services are not an answer to modularize or split a user interface into maintainable parts. In the end, there is a big danger that it will end in a distributed monolith. We are also talking about UI monoliths.

Between a microservice and a monolith

If we would have a small application we would not talk about it and just refactor or rewrite it. Small applications are easy to understand as a whole. They are small enough to be migrated or even replaced. It also doesn't hurt to throw them away if not needed anymore.

Why don't we break our large system down into several smaller applications? This is it! We can cut our system vertically into completely separated, independent applications. Each application has its own tech stack such as user interface, database, and deployment stack. It has its own backlog and its own release cycle. This way we don't have the overhead of micro-services but each of those applications is small enough to be understood and to be maintained for a very long time.

It is actually a system of systems. This way we can build s sustainable system architecture that is and can stay fit for the future. We don't need to completely rewrite the old legacy system, as well. We can revitalize it by replacing only parts of it, or adding new features with new tiny applications. The coexistence of the legacy application with a replacement is not a risk anymore, but a feature. If we do that, it is important to make sure that the replaced features are built back into the legacy system as well. We make sure it can be slowly transitioned completely into the new self-contained systems architecture.

Summary

Let's the main message of this blog post. Large enterprise applications often reach their end of life due to unsupported technologies and lack of knowledge. Rewriting them doesn't bring any value, is expensive, and introduces the risk of never getting rid of the old application. An architecture style called self-contained systems splits a software system vertically into many small applications that are easy to understand and maintain. This way, it's also possible to transition an old, very large software system into a system which is fit for the future.

Every time we do that rather 'hacky' instead of having a proper code base for such kind of tools. I hate code which is not cleaned up, but has a lifetime of the whole project or product. This tend to suffer from the broken window effect and become worse and worse. So one day, I sat down and thought about how I can build a console application which is properly built and very easy to set up. You can get the sample code here.

I don't like to reinvent the wheel I was looking for libraries doing the job for me.

• CommandLineParser

• MediatR

• Microsoft Dependency Injection

• Serilog

To have more control over the log output, I'm using Serilog. With Serilog we can write to the console, a file or wherever we want to send and store our log messages.

var levelSwitch = new LoggingLevelSwitch
{
    MinimumLevel = LogEventLevel.Information,
};

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.ControlledBy(levelSwitch)
    .Enrich.FromLogContext()
    .WriteTo.Console(outputTemplate: "{Timestamp:HH:mm:ss} [{Level:u3}] {SourceContext} {Message:lj}{NewLine}{Exception}")
    .CreateLogger();

In any normal application I would use a dependency injection container to leverage the inversion of control principle. Basically it does not matter which framework we use for that job. I just hooked on the dependency injection extension from Microsoft which are also used in Asp.Net Core. As you may recognize, I'm registering the logger with the Microsoft logging extension into the dependency injection container. This libraries play neatly together, which makes this easier for us.

var serviceProvider = new ServiceCollection()
    .AddLogging()
    .AddSingleton<ILoggerFactory>(_ => new SerilogLoggerFactory(Log.Logger))
    .BuildServiceProvider();

And that I can setup the CommanLineParser to parse the program arguments.

return await Parser.Default.ParseArguments<Option1, Option1>(args)
    .MapResult(
        // the command arguments are valid and we can do something here
        async (object options) =>
        {
            return Task.FromResult(0);
        },
        // the command was invalid, we return an error code
        _ => Task.FromResult(1));

Now almost everything is in place in order that we can work with it. The CommanLineParser requires you to implement annotated classes which are filled from the parser. I want to create a git commands like tool, so I'm using the Verb feature of the CommanLineParser.

[Verb("hello", HelpText = "Just an example command.")]
public class HelloCommand
{
    [Option('t', "target", Required = true, HelpText = "Specifies whom to say hello.")]
    public string GreetingTarget { get; set; }
}

[Verb("goodbye", HelpText = "Just an example command.")]
public class GoodbyeCommand
{
    [Option('t', "target", Required = true, HelpText = "Specifies whom to say hello.")]
    public string GreetingTarget { get; set; }
}

I need to register my command in the CommanLineParser.

return await Parser.Default.ParseArguments<HelloCommand, GoodbyeCommand>(args)
    .MapResult(
        async (object options) =>
        {
            return Task.FromResult(0);
        }

Oh wait, the map results is untyped. I need to distinguish between the different options classes and cast them in order to access their information. This could lead to nasty code with many if or switch blocks. I prefer to have some cleaner way to do that job. Luckily there is a software development pattern for this problem. The mediator pattern can help us calling the correct command logic according to our inputs. I'm using the MediatR library which is a fully managed implementation of that pattern. And because we are using a dependency injection container it comes with no overhead at all.

I'm registering the MediatR library in the dependency injection container.

var serviceProvider = new ServiceCollection()
    .AddLogging()
    .AddSingleton<ILoggerFactory>(_ => new SerilogLoggerFactory(Log.Logger))
    .AddMediatR(Assembly.GetExecutingAssembly())
    .BuildServiceProvider();

The commands must inherit from IRequest in order that it works together with the MediatR library. I'm creating a command base class for that, we also can use it later on to add some general command line arguments to the commands.

public abstract class CommandBase : IRequest<int>
{
}

Every command has a command handler, which executes the logic of the command. We can inject our dependencies into our command handlers. I'm only using the logger, but it can be anything you want. E.g. an Entity Framework context or whatever.

public class HelloCommandHandler : IRequestHandler<HelloCommand, int>
{
    private readonly ILogger<HelloCommandHandler> _logger;

    public HelloCommandHandler(ILogger<HelloCommandHandler> logger)
    {
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    public Task<int> Handle(HelloCommand request, CancellationToken cancellationToken)
    {
        _logger.LogInformation($"Hello {request.GreetingTarget}");

        return Task.FromResult(0);
    }
}

public class GoodbyeCommandHandler : IRequestHandler<GoodbyeCommand, int>
{
    private readonly ILogger<GoodbyeCommandHandler> _logger;

    public GoodbyeCommandHandler(ILogger<GoodbyeCommandHandler> logger)
    {
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    public Task<int> Handle(GoodbyeCommand request, CancellationToken cancellationToken)
    {
        _logger.LogInformation($"Goodbye {request.GreetingTarget}");

        return Task.FromResult(0);
    }
}

And finally we can call the MediatR with the command and this will execute the corresponding command handler.

return await Parser.Default.ParseArguments<HelloCommand, GoodbyeCommand>(args)
    .MapResult(
        async (CommandBase command) =>
        {
            return await serviceProvider.GetRequiredService<IMediator>().Send(command);
        },
        _ => Task.FromResult(1));

Cool! with that we have a clean command line tool which is easy to test and maintain.

As an addition, I'm adding some general arguments to the base class. To demonstrate this, I'm adding a Verbose flag which adjusts the current log level.

public abstract class CommandBase : IRequest<int>
{
    [Option("verbose", Default = false, Required = false, HelpText = "Enables verbose output.")]
    public bool Verbose { get; set; }
}

async (CommandBase command) =>
{
    if (command.Verbose)
    {
        levelSwitch.MinimumLevel = LogEventLevel.Verbose;
    }

    return await serviceProvider.GetRequiredService<IMediator>().Send(command);
},

I used this architecture already in a few projects and I must say it was worth to do it. It is easy to understand and it does not get messed up. At the end, every line of code brings in maintenance effort and can waist the time of the team. Just care a bit, even though it is not the main product you are creating helps you and all involved peoples.

After the last article, we have a protected REST API in our ASP.NET Core backend. Technically we are fine with that. From a user's perspective, it is not very handy to run into unauthorized operations. To make this more user friendly we need a way to also check these permissions in our frontend. In the last few projects, I was involved in, we used Angular. So this article will target Angular even though the concept is also applicable to other frontend technologies such as React or ViewJS.

Loading the permissions from the backend

To be able to perform a permission check in the frontend, we need to load the authorization policies and user permissions from the backend.

First, we create an ASP.NET API controller returning the permissions of the logged-in user.

[ApiController]
[Route("api/v1/authorization-permissions")]
public class ResourcePermissionsController : ControllerBase
{
    [HttpGet]
    public ActionResult<Permission[]> GetPermissions()
    {
        var permissions = User.GetPermissions();
        // I usually map the entities to dto's, but  removed this here for simplicity
        return Ok(permissions);
    }
}

Then we create a service in the Angular frontend that can load the permissions.

export type PermissionAction = 'Read' | 'Write' | 'ReadRestricted' | 'ReadConfidential';

export interface Permission {
  resourceId: string[];
  actions: PermissionAction[];
}

@Injectable({
  providedIn: 'root',
})
export class AuthorizeService {
  constructor(private http: HttpClient) {}

  public getResourcePermissions(): Observable<Permission[]> {
    return this.http.get<Permission[]>(`${environment.apiBaseUrl}/authorize-permissions`);
  }
}

I usually use NgRX in my Angular applications, load the data in an effect, and store it in the NgRX state. I'm not going to go deeper into that topic because it is not important to the topic in this post.

Important is only, that you load the permissions at the correct time. Do you have any permissions to query for unauthenticated users, or are you forced to be logged in? In the applications I implemented, a user gets automatically logged in by single sign-on over an OAuth identity provider. So we loaded the user permission after the user had been signed in.

Loading the policies from the backend

As mentioned before, we also need to load the authorization policies into the Angular frontend. This is done similarly to the permissions.

We create an ASP.NET API controller returning the authorization policies. To mention is, that we need to allow to request them without the user being logged in because we are going to load them at the startup of the Angular application.

public class AuthorizePolicyDto
{
    public string? Name { get; set; }

    public ICollection<RequiredPermissionDto> Permissions { get; set; } = new Collection<RequiredPermissionDto>();
}

public class RequiredPermissionDto
{
    public ICollection<string> ResourceId { get; set; } = new Collection<string>();

    public PermissionAction Action { get; set; }
}

[ApiController]
[AllowAnonymous] // important, because we call this endpoint before the user has beed logged in
[Route("api/v1/authorization-policies")]
public class AuthorizationPoliciesController : ControllerBase
{
    public AuthorizationPoliciesController()
    {
        _mapper = mapper;
    }

    [HttpGet]
    public ActionResult<AuthorizePolicyDto[]> GetPolicies()
    {
        var policies = Enumeration.GetAllValues<AuthorizePolicy>();
        return Ok(MapToDtos(policies));
    }

    // in this case we map to dto's because the frontend needs it in a different format
    private static IEnumerable<AuthorizePolicyDto> MapToDtos(IEnumerable<AuthorizePolicy> policies)
    {
        return policies.Select(p => new AuthorizePolicyDto
            {
                Action = p.Action,
                ResourceId = p.ResourceId.Split('/', StringSplitOptions.None),
            });
    }
}

And then again, we load the policies into the Angular frontend.

export interface AuthorizePolicy {
  name: AuthorizePolicies;
  permissions: RequiredPermission[];
}

export interface RequiredPermission {
  resourceId: string[];
  action: PermissionAction;
}

// we extend the Authorize Service
@Injectable({
  providedIn: 'root',
})
export class AuthorizeService {
  constructor(private http: HttpClient) {}

  public getAuthorisationPolicies(): Observable<AuthorizePolicy[]> {
    return this.http.get<AuthorizePolicy[]>(`${environment.apiBaseUrl}/authorization-policies`);
  }
}

The authorization policies need to be loaded latest with the user permissions. You could load them together. We separated it and loaded the Policies in the Angular APP_INITIALIZER routine.

Checking the user permissions

Now we have all the data that is required to check the permissions in the frontend. We'll extend the AuthorizeService with the logic required to check the permissions against the policies. Again, I'm using NgRX, but you can use anything to store the permissions and policies in the front end.

// we extend the Authorize Service
@Injectable({
  providedIn: 'root',
})
export class AuthorizeService {
  constructor(private http: HttpClient, private store$: Store) {}

  public isAuthorized(policyName: AuthorizePolicies, values: Map<string, string>): Observable<boolean> {
    return combineLatest([
      this.store$.pipe(select(selectResourcePermissions)),
      this.store$.pipe(select(selectAuthorizationPolicies)),
    ]).pipe(
      // check if the permissions have been loaded
      filter(([permissions]) => permissions.status === 'SUCCEEDED' || permissions.status === 'FAILED'),

      // get the policy with the provided key
      map(([permissions, policies]) => {
        if (!policies.some((p) => p.name === policyName)) {
          throw new Error(`No policy with name '${policyName}' has been found`);
        }

        return {
          permissions,
          policy: policies.find((p) => p.name === policyName),
        };
      }),

      // check if the user is authorized
      map(({ permissions, policy }) => this.authorizeUser(permissions.data, policy, values)),
      first(),
    );
  }

  private authorizeUser(permissions: Permission[], policy: AuthorizePolicy, values: Map<string, string>): boolean {
    const isAuthorized =
      policy.permissions
        // replace variables in the policy
        .map((p) => AuthorizeService.substitutePermission(policy.name, p, values))

        // check policies against the permissions
        .map((p) => this.hasPermission(permissions, p))

        // are all required permissions granted?
        .findIndex((granted) => !granted) < 0;

    return isAuthorized;
  }

  private static substitutePermission(
    policy: string,
    permission: RequiredPermission,
    values: Map<string, string>,
  ): RequiredPermission {
    return {
      ...permission,
      resourceId: permission.resourceId.map((r) => {
        if (/^{.*}/g.test(r)) {
          const variableName = r.replace('{', '').replace('}', '');
          if (!values.has(variableName)) {
            throw new Error(`A value for the variable '${variableName}' is missing for policy ${policy}.`);
          }
          return values.get(variableName);
        }
        return r;
      }),
    };
  }

  private hasPermission(permissions: Permission[], requiredPermission: RequiredPermission): boolean {
    // check the every user permission if it matches the required permission
    const hasPermission =
      permissions.map((p) => AuthorizeService.matchPermission(p, requiredPermission)).findIndex((matched) => matched) >=
      0;

    return hasPermission;
  }

  private static matchPermission(permission: Permission, requiredPermission: RequiredPermission): boolean {
    if (permission.actions.findIndex((a) => a === requiredPermission.action) < 0) {
      return false;
    }
    for (let i = 0; i < requiredPermission.resourceId.length; i++) {
      if (permission.resourceId.length <= i) {
        return false;
      }
      if (permission.resourceId[i] === '**') {
        return true;
      }
      if (permission.resourceId[i] !== '*' && permission.resourceId[i] !== requiredPermission.resourceId[i]) {
        return false;
      }
    }
    if (permission.resourceId.length !== requiredPermission.resourceId.length) {
      return false;
    }
    return true;
  }
}

Are we done with that? Not yet. This is only the service that allows us to check the permission in any place within our Angular app. We can inject it into controllers, services, route guards, or directives to check the permissions.

Authorize Angular routes

We usually do a check in the routing. This can be done with a route guard which prevents the user from opening a page in the Angular app.

Note: we usually combine a check for authenticated AND authorized, I skip the authentication check because this depends on your way how authenticating a user.

export interface RouteData {
  authorize?: AuthorizeRouteData;
}

export const createAuthorizeRouteData = (policies: AuthorizePolicies[]): RouteData => ({ authorize: { policies } });

@Injectable({
  providedIn: 'root',
})
export class AuthGuard implements CanActivate, CanActivateChild {
  constructor(private oauthService: OAuthService, private store: Store, private authorizeService: AuthorizeService) {}

  async canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Promise<boolean> {
    return await this.isAuthorized(route);
  }

  async canActivateChild(childRoute: ActivatedRouteSnapshot, state: RouterStateSnapshot): Promise<boolean> {
    return await this.isAuthorized(childRoute);
  }

  private async isAuthorized(route: ActivatedRouteSnapshot): Promise<boolean> {
    // the required policy is defined in the Angular route data
    const routeData: RouteData = route.data;

    // skip it when no permission is required
    if (!routeData.authorize) {
      return true;
    }

    // extract the authorize policy variables from the route parameters
    const values = extractParams(route.root);

    // interate through the policies and check the user permissions
    for (const policy of routeData.authorize.policies) {
      const isAuthorized = await this.authorizeService.isAuthorized(policy, values).toPromise();
      if (!isAuthorized) {
        this.store.dispatch(go({ path: ['/auth', 'unauthorized'] }));
        return false;
      }
    }
    return true;
  }
}

As you have seen, the authorization policy variables get extracted from the route parameters. To do this we wrote a few helper methods.

export const extractParams = (
  route: ActivatedRouteSnapshot,
  params: Map<string, string> = new Map<string, string>(),
): Map<string, string> => {
  if (route.paramMap) {
    addParamMap(params, route.paramMap);
  } else {
    addParams(params, route.params);
  }
  for (const child of route.children) {
    extractParams(child, params);
  }
  return params;
};

export const addParams = (params: Map<string, string>, values: { [index: string]: string }): Map<string, string> => {
  if (values) {
    for (const key of Object.keys(values)) {
      params.set(key, values[key]);
    }
  }
  return params;
};

export const addParamMap = (params: Map<string, string>, values: ParamMap): Map<string, string> => {
  if (values) {
    for (const key of values.keys) {
      params.set(key, values.get(key));
    }
  }
  return params;
};

To make this work, the parent route parameters must be inherited in order that all parameters are present in the current route.

const routes: Routes = [
  // your routes
];

export const routingConfiguration: ExtraOptions = {
  paramsInheritanceStrategy: 'always',
};

@NgModule({
  imports: [RouterModule.forRoot(routes, routingConfiguration)],
  exports: [RouterModule],
})
export class AppRoutingModule {}

With that in place, a specific route can be guarded with one or more authorization policies.

const routes: Routes = [
  {
    path: 'employees/:employeeId',
    component: EmployeeComponent,
    data: createAuthorizeRouteData(['EMPLOYEE_READ']),
    canActivate: [AuthGuard],
  },
];

Authorize HTML elements with an Angular directive

The last thing I want to show you is how we show, resp. hide HTML elements if you are authorized to see them or not. Instead of always injecting the AuthorizeService into the controllers, we implemented a simple structural directive that does the check for us.

There are two ways to pass the authorization policy variables to the directive:

• by leveraging the route parameters as we did in the AuthGuard

• by passing them directly into the directive

export interface AuthorizeOptions {
  values: { [index: string]: string };
}

@Directive({ selector: '[appShowAuthorized]' })
export class ShowAuthorizedDirective implements OnInit, OnDestroy {
  @Input('appShowAuthorized') authorizePolicies: AuthorizePolicies;
  @Input() appShowAuthorizedOptions: AuthorizeOptions;

  private unsubscribe$ = new Subject();

  constructor(
    private authorizeService: AuthorizeService,
    private store$: Store<RootState>,
    private templateRef: TemplateRef<unknown>,
    private viewContainer: ViewContainerRef,
  ) {}

  ngOnInit(): void {
    if (!this.authorizePolicies) {
      this.viewContainer.clear();
      return;
    }

    this.store$
      .pipe(
        select((state) => state.router),
        // prevent the directive to get a different route config than the initial one on navigating away
        scan((acc: RouterReducerState<SerializedRouterStateSnapshot>, val) => {
          if (!acc || routeConfigEquals(acc.state.root, val.state.root)) {
            return val;
          }

          return acc;
        }, <RouterReducerState<SerializedRouterStateSnapshot>>null),
        filter((router) => !!router),
        map((router) => extractParams(router.state.root)),
        map((params) => addParams(params, this.appShowAuthorizedOptions?.values)),
        mergeMap((params) => this.authorizeService.isAuthorized(this.authorizePolicies, params)),
        takeUntil(this.unsubscribe$),
      )
      .subscribe((isAuthorized) => {
        if (isAuthorized) {
          this.viewContainer.clear();
          this.viewContainer.createEmbeddedView(this.templateRef);
        } else {
          this.viewContainer.clear();
        }
      });
  }

  ngOnDestroy(): void {
    this.unsubscribe$.next();
  }
}

This directive can be used directly in an HTML element.

<div *appShowAuthorize="'EMPLOYEE_READ'; options: { values: { employeeId: specificEmployeeId } }">
    <......></......>
</div>

Summary

Wow, that was quite a bit... After explaining our approach to a resource-based authorization model and implementing it in ASP.NET Core I showed you how to implement it in an Angular application. It is basically always the same concept and logic but implemented in a different language and framework. I hope it can help you build your authorization framework in your own application. If you have questions, please feel free to add a comment.

The traditional ASP.NET and WebAPI ASP.NET support only role-based authorization and with the ASP.NET Identity Model extension it was possible to use claim-based authorization. Both were limited in terms of resource-based authorization and a lot of manual work was required. Luckily, ASP.NET Core made a big progress with its Policy-based Authorization. This allows us to integrate our resource-based permission into the framework.

Resource Permissions

Let's start with the resource permissions. I have the following base implementation of the ResourcePermission class:

public enum PermissionAction
{
    Read,
    Write,
}

public class ResourcePermission : IEquatable<ResourcePermission>
{
    public Guid Id { get; set; }

    public string Resource { get; set; } = null!;

    public string? UserGroup { get; set; }

    public string? User { get; set; }

    public ICollection<PermissionAction> Actions { get; set; } = new Collection<PermissionAction>();
}

It is an entity which is stored in our database. So it has an Id, the Resource, the PermissionAction and the User resp. UserGroup navigation properties. In the simplest case, this can be strings, storing the AD Account Name and the AD Group. But you also can properly model that in your database depending on your needs. The PermissionAction is a simple enum containing the actions we want to protect.

We also need to be able to load the ResourcePermission entities for a specific user or his/her user group(s). We had several sources from where these resource permissions could originate:

• Static resource permissions

• Manually assigned and stored in the database

• Generated from other entities such as team members, etc.

To cover that, we implemented a PermissionService, which retrieved and aggregated all permissions from several providers.

public interface IResourcePermissionsProvider
{
    Task<IReadOnlyCollection<ResourcePermission>> GetPermissionsAsync(string userName, IReadOnlyCollection<string> userGroups);
}

public class ResourcePermissionsService : IResourcePermissionsService
{
    private readonly IEnumerable<IResourcePermissionsProvider> _providers;

    public ResourcePermissionsService(IEnumerable<IResourcePermissionsProvider> providers)
    {
        _providers = providers;
    }

    public async Task<IReadOnlyCollection<ResourcePermission>> GetPermissionsAsync(string userName, IReadOnlyCollection<string> userGroups)
    {
        var result = new List<ResourcePermission>();

        foreach (var provider in _providers)
        {
            var permissions = await provider.GetPermissionsAsync(userName, userGroups);
            result.AddRange(permissions);
        }

        return result;
    }
}

Authorization Policies

To describe the authorization policies, we need to define the required permissions first. Compared to the RequiredPermission class, we only need one PermissionAction to query what the user should be able to do on the provided resource.

public class RequiredPermission
{
    public RequiredPermission(string resourceId, PermissionAction action)
    {
        ResourceId = resourceId;
        Action = action;
    }

    public string Resource { get; }

    public PermissionAction Action { get; }
}

The implementation for the AuthorizationPolicy class is based on the Enumeration Class pattern, described by Microsoft. This includes a similar behavior as the traditional enum type, but allows us to enrich them with additional attributes. The key of the policy is also declared as a constant. Later on we will need it to access the policy in the standard ASP.NET Core AuthorizationAttribute.

public interface IAuthorizePolicy
{
    RequiredPermission[] Permissions { get; }

    string Key { get; }
}

public class AuthorizePolicy : Enumeration<string>, IAuthorizePolicy
{
    public const string DepartmentRead = "DEPARTMENT_READ";
    public const string DepartmentWrite = "DEPARTMENT_WRITE";

    public static readonly AuthorizePolicy DepartmentReadPolicy = new(
        DepartmentRead,
        new[] { new RequiredPermission("/departments/{departmentId}", PermissionAction.Read) });

    public static readonly AuthorizePolicy DepartmentWritePolicy = new(
        DepartmentWrite,
        new[] { new RequiredPermission("/departments/{departmentId}", PermissionAction.Write) });

    private AuthorizePolicy(string key, RequiredPermission[] permissions)
        : base(key)
    {
        Permissions = permissions;
    }

    public RequiredPermission[] Permissions { get; }
}

Checking the permission

After we have the ResourcePermission and AutorizationPolicy ready, it's time to implement the permission check. We do that with plain C# first. The ASP.NET core integration will follow afterward.

To check if a ResourcePermission matches with a RequiredPermission we need to check two things:

1. Has the ResourcePermission the required PermissionAction?

2. Is the resource of the ResourcePermission matching with the explicit resource id string from the RequiredPermission?

To match the resource path, we split both, the permission resource id and the required resource id into its segments by the / character. Now it is quite easy to compare the resource IDs. If every segment is equal, or if the permission resource id segment has a wild card * the resource IDs are matching. It is important to start with the root segment and work down the path. If the permission resource id segment has a deep wild card ** the matching can be aborted because every sub-segment will be a match anyway.

The following code snippet shows how the matching can be implemented.

private static bool MatchesPermission(ResourcePermission permission, string specificResourceId, PermissionAction requiredAction)
{
    if (!permission.Actions.Contains(requiredAction))
    {
        return false;
    }

    var requiredResourceId = specificResourceId.Split('/');
    var permissionResourceId = permission.Resource.Split('/');

    for (var i = 0; i < requiredResourceId.Length; i++)
    {
        if (permissionResourceId.Length <= i)
        {
            return false;
        }

        if (permissionResourceId[i] == "**")
        {
            return true;
        }

        if (permissionResourceId[i] != "*" && permissionResourceId[i] != requiredResourceId[i])
        {
            return false;
        }
    }

    if (permissionResourceId.Length != requiredResourceId.Length)
    {
        return false;
    }

    return true;
}

But this is not the complete permission check yet. An AuthorizationPolicy can contain multiple required permissions and we still need to replace the parameters in the required permissions with its target value.

private static readonly Regex Regex = new("{(.*?)}", RegexOptions.Compiled);

public static bool IsMetByPermissions(this IAuthorizePolicy policy, IReadOnlyList<ResourcePermission> permissions, Dictionary<string, string?> paramMap)
{
    foreach (var requiredPermission in policy.Permissions)
    {
        var specificResourceId = requiredPermission.ResourceId;

        // replacing the parameters in the required permission resoruce id
        var matches = Regex.Matches(requiredPermission.ResourceId).ToList();
        foreach (var match in matches)
        {
            var parameterName = match.Groups[1].Value;
            if (!paramMap.ContainsKey(parameterName))
            {
                throw new ArgumentException($"Parameter with name {parameterName} was not found.", nameof(paramMap));
            }

            specificResourceId = specificResourceId.Replace(match.Value, paramMap[parameterName], StringComparison.InvariantCultureIgnoreCase);
        }

        // checking whether the user has a matching permission
        if (!permissions.Any(permission => MatchesPermission(permission, specificResourceId, requiredPermission.Action)))
        {
            return false;
        }
    }

    return true;
}

Now we can call the permission check on the authorization policy. We need to retrieve the permissions of the corresponding user and provide the parameters that are required for the target policy.

var user = "my-user";
var groups = new[] { "group1", "group2" };

// get the permissions from the resource service
var permissions = await permissionService.GetPermissionsAsync(user, groups);

// specify the corresponding resource ids which are required
var parameters = new Dictionary<string, string>
{
    { "departmentId", "A" },
};


var userHasAccess = AuthorizePolicy.DepartmentReadPolicy.IsMetByPermissions(permissions, parameters);

ASP.NET Core integration

Microsoft has built a completely new and flexible authorization handling into ASP.NET Core. Besides the traditional role-based authorization and claim-based authorization, it provides the so-called policy-based authorization. We can cover almost every scenario we could think about with this approach.

To marry our resource-based authorization with the policy-based authorization from ASP.NET Core, we need four things:

1. Retrieve the user permissions

2. An authorization handler that calls the permission check

3. An authorization requirement that maps an ASP.NET Core policy with our AuthorizationPolicy

4. Register our implementations in the ASP.NET Core application

Retrieve the user permissions

We could do that simply by injecting the PermissionService wherever we need the user permissions. But this way it might happen that we load the permissions several times in a single endpoint call. To prevent this, we load the permissions in the token-validated event, after the user has been authenticated.

var authenticationBuilder = services
   .AddJwtBearer(OidcConstants.AuthenticationSchemes.AuthorizationHeaderBearer, options =>
{

    options.Events = new JwtBearerEvents
    {
        OnTokenValidated = async context =>
        {
            // get the permission service
            var permissionService = context.HttpContext.RequestServices
                .GetRequiredService<IResourcePermissionsService>();

            // get user name and role from the claims principal
            var loginName = context.Principal!.GetLoginName();
            var roles = context.Principal!.GetRoles()
                .ToList();

            // load the permissions
            var permissions = await permissionService.GetPermissionsAsync(loginName, roles);

            // add the permissions as claims to the claims principal
            var appIdentity = permissions.ToClaimsIdentity();
            context.Principal!.AddIdentity(appIdentity);
        },
    };
});

The permissions are converted to claims and added to the ClaimsPrincipalof the user. This way we can retrieve them whenever we want.

public static Claim ToClaim(this ResourcePermission permission)
{
    return new Claim(ShopDbClaimTypes.Permission, JsonSerializer.Serialize(permission), "json");
}

public static IEnumerable<Claim> ToClaims(this IEnumerable<ResourcePermission> permissions)
{
    return permissions.Select(ToClaim);
}

public static ClaimsIdentity ToClaimsIdentity(this IEnumerable<ResourcePermission> permissions)
{
    return new ClaimsIdentity(permissions.ToClaims());
}

Authorization Requirement

Let's start with the authorization requirement. Our authorization requirement implementation is only a wrapper around one or more authorization policies to make them compatible with the ASP.NET Core policy-based authorization.

public class AuthorizePolicyRequirement : IAuthorizationRequirement
{
    public AuthorizePolicyRequirement(params IAuthorizePolicy[] requiredPolicies)
    {
        RequiredPolicies = requiredPolicies;
    }

    public IAuthorizePolicy[] RequiredPolicies { get; }
}

We also need to register our authorization policies in ASP.NET Core. To do that, we convert them into requirements and add them to the ASP.NET Core authorization policies. If you have a look at the code snippet below, you may notice that we register the requirements with the key of the mapped authorization policy. This allows us later to just use the standard AuthorizeAttribute and pass in the policy name. See also (https://docs.microsoft.com/en-us/aspnet/core/security/authorization/policies?view=aspnetcore-3.0).

services.AddAuthorization(options =>
{
    // this adds all our authorize policies see
    foreach (var policy in AuthorizePolicy)
    {
        options.AddPolicy(policy.Key, p => p.Requirements.Add(new AuthorizePolicyRequirement(policy)));
    }
});

Authorization Handler

The authorization handler gets called when we enforce an authorization, e.g, by using the AuthorizeAttribute. The authorization handler does basically the same as the example earlier, where I illustrated how to use the resource-based authorization.

• Retrieving the permissions of the user

• Providing the parameters that are required for the authorization policy

• Call the permission check

We added the permission to the ClaimsPrincipal of the user. So it is quite easy to retrieve them in the authorization handler.

One of the benefits of this approach comes into place now. We can model our resource identifiers exactly the same or similar as our REST URI's. That means we have all the parameters that are required from the policy present in the ASP.NET Core route data. We just need to extract them and provide them in a shape we can use it. One thing has to be ensured in order to make that work, the parameter names in the ASP.NET Core route must match the parameter name of the used authorization policy.

And then we only need to call the permission check as we already have seen before.

public class AuthorizePolicyHandler : AuthorizationHandler<AuthorizePolicyRequirement>
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public AuthorizePolicyHandler(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    protected override async Task HandleRequirementAsync(AuthorizationHandlerContext context, AuthorizePolicyRequirement requirement)
    {
        if (!requirement.RequiredPolicies.Any())
        {
            return;
        }

        // get the routing parameters and provide them as parameters required by the authorization policy
        var routeData = _httpContextAccessor.HttpContext!.GetRouteData();
        var paramMap = routeData.Values.ToDictionary(x => x.Key, x => x.Value?.ToString());

        // get the permissions from the claims principal
        var permissions = context.User.GetPermissions();

        // check the permissions
        if (requirement.RequiredPolicies.All(policy => policy.IsMetByPermissions(permissions.ToList(), paramMap)))
        {
            context.Succeed(requirement);
        }

        await Task.CompletedTask;
    }
}

Also, the authorization handler needs to be registered in ASP.NET Core. This can be done by simply registering it as a service.

services.AddTransient<IAuthorizationHandler, AuthorizePolicyHandler>();

With that in place, we can use our resource-based authorization through the ASP.NET Core authorization.

[HttpGet("{departmentId}")]
[Authorize(AuthorizePolicy.DepartmentRead)]
public async Task<ActionResult> GetDepartmentAsync(Guid departmentId)
{
    return Ok();
}

Summary

In part one of the article series we explained our approach to a resource-based authorization model. In this article, we integrated this approach into the ASP.NET Core framework by using the ASP.NET Core policy-based authorization. Now we are able to protect the resources in our ASP.Net Core applications.

The next step will be to extend it with an Angular implementation to provide user-friendly authorization handling.

I will cover our approach to Resource Based Authorization in a series of articles. So stay tuned, more is coming.

Requirements

As I mentioned before, we basically need to restrict access to certain entities, but what means that in detail?

Let's say we provide a service for a large customer, where we manage the staff, inventory, tasks, and so on for him (an example is imaginary) and we implement a new application to support this service.

There are different types of users in this application:

• Business administrators, who can basically access everything

• System administrators, who have read-only access to everything

• Department Managers who have access to the department functionality like employee management and basically have access to the entities belonging to an employee, e.g. his tasks.

• The standard user who only has access to his tasks and publicly available information.

On top of that, we had the requirement, that the permissions for the resources could be assigned in several ways:

• Automatic assignment through AD groups

• Manual assignment through an admin user

• Automatic assignment through the user's role in his department

• Automatic assignment through resource ownership when a user creates a resource, e.g. a task

Our concept

A business administrator, who can access everything, could be covered with a simple role-based authorization like Active Directory groups. But as soon as we would need to break down a permission for specific resources to a dedicated user, it would be difficult to mirror that in the Active Directory. We also need to keep the JWT token size in mind. Mirroring everything into the Active Directory will produce very large JWT tokens, which also blow up Auth Cookies. That can be a problem with certain proxies like the Ingress controller in Kubernetes.

Resource Permission Model

We came up with the following model for our resource-based authorization:

The model is quite obvious. We have a user who can have some permissions. Theoretically, we already could work with that. If we have multiple users with the same permissions, let's say a manager and his deputy, it would lead to several duplicate permission entries. This would increase the complexity because we need to maintain these permissions.

To simplify that, we introduce the user groups. A user group can also have several permissions. A user can be a member of one or more groups. Of course, the user gets automatically all permissions of the groups (s)he is a member of.

We can model that in a database. We can retrieve the user by its AD Account Name and resolve the corresponding permissions. We also can resolve all groups the user is a member of and with that collect all permissions that are involved. Global groups can be modeled with AD groups which have a direct relation to our user groups.

Resource Identifiers

Every entity has a unique identifier. Theoretically, we can use this identifier to associate a permission with its recourse. This approach would work, but is kind of limited. How you would cover a scenario like all employees of a department? Every single employee of that department would need to be mirrored as resource permission. The meaning of "access to all employment of the department 'A'" would be lost.

We introduced the concept of resource identifiers. A resource identifier is a kind of a URI describing the resource. To target the employee '1' of the department 'A' we have the resource identifier /department/A/employees/1. This is clearly unique identifying, and can be matched to REST endpoint url's, which is also a resource identifier and introduces a context that makes it understandable.

Wildcards can express any resource on the corresponding path segment. With, all employees of department 'A' are matched and /department/*/employees/* would indicate all employees of all departments. We can go even a step further and target all sub-resources of department 'A' with the identifier /departent/A/**.

With this approach, we can target any kind of resources. We introduced a context with the identifier which makes it easier to understand and debug. As a bonus, we prevent our database from being flooded by resource permissions.

Permission Actions

If you have everything publicly accessible and only want to restrict write access, the resource identifier is enough to express a permission for a resource. In our case, we also needed to restrict the read access for our entities. In fact, I would consider to introduce that from scratch, otherwise, it will be quite an effort to change it.

We introduced the permission actions to express what can be done with this permission. Generally, we used only two of them: read and write. In some projects, we extended them through actions like read confidential.

Let's make this more clear: resource permission = resource identifier + resource actions. An example would be /department/A/employees/1 -> [read, write] which indicates read/write access on the employee with id '1'.

Validating Permissions

Now we have resource permissions for dedicated resources, but how do we check if a user has access to this resource? We need to compare the required permission with the resource permissions the user has.

Let's give some examples. We want to check if the user is permitted to modify employee '1' of department 'A'. We express that with /department/A/employees/1 -> write. Now we compare this with every permission of the user.

• /department/A/employees/1 -> [read, write]: All segments are matching, and the user is permitted.

• /department/A/employees/2 -> [read, write]: The employee ID does not match, the user is not permitted.

• /department/A/employees/* -> [read, write]: We have a wildcard permission that matches any employee ID of department 'A', the user is permitted.

• /department/** -> [read, write]: The wildcard permission indicates full access to all departments and its sub-resources, the user is permitted.

• /department/A/employees/1 -> [read]: The resource action is not matching, and the user is not permitted.

If any resource permission of the user is matched, the permission is granted.

Authorization Policies

At this stage, we have almost everything together that we can work with. We modeled the resource permissions and we know how we can validate the permissions of a user. A tiny piece is missing - the authorization policies.

In the real world, we don't query for a specific resource identifier. We wrap them into a so-called authorization policy.

Maybe you noticed that required permission which almost looks the same as the resource permission. There is one small, but important difference. While resource permission identifiers contain exact entity IDs or wildcards, a required permission identifier contains variables that can be replaced at query time.

For example, with the identifier, /departments/{departmentId}/employees/{employeeId} we express a generic resource identifier that needs to be used in a certain context. The steps to query this policy against the permissions would be:

1. Get the required permissions of the policy with the key EMPLOYEE_WRITE

2. Replace all variables with the required permission. /departments/{departmentId}/employees/{employeeId} will become /departments/A/employees/1.

3. Query the resulting required permission identifier with the required action against the user permissions.

4. If we query for an authorization policy, all required permissions must be matched.

This is very handy. If you align the naming of the required resource variables with the routing properties in Asp.Net Core or Angular, the policies can be queried during the routing and the variables can be automatically resolved.

Additional thoughts

Some of my fellows also introduced an additional property on the resource permission to indicate whether the permission is granted or denied. While this brings some more flexibility into the game, it also increases the complexity of querying the permissions. It is a possibility, but I personally never used it. The decision is yours.