Tore Nestenius

Visualizing Claude Code MCP Requests with Coding Agent Explorer

Tore Nestenius — Thu, 16 Apr 2026 00:00:00 GMT

Model Context Protocol (MCP) servers are becoming a key part of how Claude Code extends its capabilities. They give the agent access to documentation, code search, external APIs, and much more. But when Claude Code talks to an MCP server, what exactly is it saying? And what is the server sending back?

Until now, that communication has been invisible. The MCP Observer changes that. It is a new feature in the Coding Agent Explorer that intercepts all traffic between Claude Code and any MCP server and displays it in a real-time dashboard, with both a raw JSON view and a readable, formatted view that makes sense of the data.

Here is what you will learn in this post:

What MCP is and why it matters for coding agents
What the MCP Observer does and how it works
How to configure it and connect it to any MCP server
What you can see in the dashboard
A few MCP services to try straight away

This is a multi-part series on the Coding Agent Explorer, an open-source .NET tool for inspecting what AI coding agents do under the hood.

Part 1 - Introducing the Coding Agent Explorer
Part 2 - Exploring Claude Code Hooks with the Coding Agent Explorer
Part 3 - Visualizing Claude Code MCP Requests with the Coding Agent Explorer

What Is Model Context Protocol (MCP)?

The Model Context Protocol is an open standard that lets AI agents connect to external tools and data sources. An MCP server exposes a set of tools that the agent can discover and call, just like a REST API but designed specifically for AI agent communication.

Claude Code has built-in support for MCP. You can register any MCP server, and Claude Code will automatically discover the tools it provides and use them whenever they are relevant to the task at hand.

The protocol is built on JSON-RPC 2.0. When Claude Code connects to an MCP server, it sends messages like initialize, tools/list, and tools/call. The server responds with its capabilities and tool results. This is the conversation the MCP Observer lets you see.

HTTP vs. STDIO MCP Servers

MCP servers can communicate over two transports: HTTP and STDIO. Claude Code supports both.

Here is the difference:

HTTP servers
Expose a URL that Claude Code connects to over the network. The traffic is standard HTTP, which means a proxy can sit in the middle and capture it transparently. This is what the MCP Observer uses.
STDIO servers
Run as a local process. Claude Code launches the process and communicates with it over stdin and stdout. The MCP Observer cannot intercept this communication, so STDIO-based servers are not visible in the observer.

That said, Claude Code’s PreToolUse and PostToolUse hooks fire for MCP tool calls regardless of transport. They do not show the raw JSON-RPC protocol, but they do show which MCP tool was called and what parameters were passed. That is enough to understand what the agent is doing, even without the protocol detail. If you have not read the previous post on hooks, it is a good companion to this one.

What Is the MCP Observer?

The MCP Observer is a transparent proxy that runs on port 9999 (HTTP). Claude Code thinks it is talking to the real MCP server. In reality, it is talking to the observer, which forwards every request to the real server, captures the traffic, and displays it on the dashboard.

Here is how the data flows:

Claude Code gets the real responses without any modification. The observer is completely transparent. You can add it to any MCP workflow without changing how Claude Code or the MCP server behaves.

Why HTTP Only on Port 9999?

The proxy between Claude Code and the observer runs over plain HTTP, not HTTPS. This is intentional. The connection is local-only: both Claude Code and the observer run on the same machine, so the traffic never leaves your computer and encryption adds no security benefit. Using HTTP also avoids the need to set up a local certificate, which would make the setup much more involved.

The outbound connection from the observer to the real MCP server is a separate matter. The observer forwards requests to whatever URL you configure, and that connection uses whatever scheme the server requires. In practice, all public MCP servers use HTTPS, so the traffic between the observer and the real server is always encrypted.

How to Set Up the MCP Observer

Setting up the MCP Observer takes about two minutes.

Step 1: Start the Coding Agent Explorer

First, run:

dotnet run

This starts the MCP proxy on port 9999 and the existing proxy on port 8888, as well as the dashboard on ports 5000 and 5001.

For details on how to install, build, and run the Coding Agent Explorer, see the first post in this series: Introducing the Coding Agent Explorer.

Step 2: Create a working directory

Create a fresh folder where you will run claude. Then open a terminal in that folder before running the next step.

Step 3: Register the proxy with Claude Code

Run this command in your terminal from inside your working directory:

claude mcp add --transport http mcp_proxy http://localhost:9999

By default this uses local scope: the registration is stored in ~/.claude.json under your project path and is only active when Claude Code is started from this directory.

The URL http://localhost:9999 is the fixed address of the MCP Observer proxy and never changes. Which real MCP server the traffic is forwarded to is controlled separately inside the MCP Observer dashboard. You only need to run this command once.

To remove the registration later:

claude mcp remove mcp_proxy

For full details on scopes and other options, see the Claude Code MCP documentation.

Step 4: Verify the MCP configuration

Start Claude Code and run the /mcp command:

/mcp

This lists all registered MCP servers and their connection status. You should see mcp_proxy listed as connected. If the status shows an error, check that the Coding Agent Explorer is running and that a destination URL has been set in the MCP Observer dashboard.

Step 5: Open the MCP Observer dashboard

Open the dashboard at https://localhost:5001 and click MCP Observer in the navigation bar.

Step 6: Set the destination URL

The destination URL field is pre-filled with https://gitmcp.io/tndata/CloudDebugger as a ready-to-use default. This is the MCP endpoint for Cloud Debugger, another open-source project by me. It is a good starting point if you just want to try the observer without setting up your own MCP server.

GitMCP is a free, open-source service that turns any GitHub repository into a remote MCP server, giving AI tools access to up-to-date documentation and code directly from the source.

Leave the default URL in place and click Set to activate it. The status line updates to confirm the proxy is active and forwarding traffic.

When you click Set, the Coding Agent Explorer updates its internal destination and reconfigures the YARP reverse proxy on port 9999 to forward traffic to the new URL. No restart is needed. Only one destination can be active at a time. If you change it, the request history is cleared so that the table always reflects a single server.

Important!

If you change the destination URL while Claude Code is already running, restart Claude Code before continuing. Claude Code caches tool information from the MCP server when it connects, and it will not pick up the new server’s tools until it reconnects.

Step 7: Try your first prompt

The Cloud Debugger is an open-source .NET tool for debugging live Azure applications. It can capture and display HTTP requests, exceptions, service bus messages, and more, without attaching a debugger or redeploying.

With the MCP Observer active and the Cloud Debugger endpoint set, start Claude Code from your working directory and try one of these prompts:

What is the Cloud Debugger and what can it do?
Does the Cloud Debugger include any Python code?
Which Azure services does the Cloud Debugger support?

Watch the MCP Observer dashboard as Claude Code connects: you will see the initialize and tools/list calls appear first, followed by one or more tools/call requests as Claude Code fetches the information it needs to answer your question.

What You Can See

The MCP Observer captures every request and response and displays them in a table, sorted oldest to newest. Each row shows the time, HTTP method, path, JSON-RPC method, response status, and duration.

For tools/call requests, the JSON-RPC method column shows the name of the tool that was called in parentheses, so you can see at a glance which tools Claude Code is using. For example: tools/call (search_docs) or tools/call (fetch_page).

Click any row to open the detail panel at the bottom, which shows the request body on the left and the response on the right.

Two Ways to View the Response

The response panel has two view modes: Pretty and Raw.

Pretty

This is the default. It renders the response in a readable format that depends on the type of request:

tools/list responses are shown as a card for each tool, with the tool name, description, and input parameters clearly laid out.
initialize responses show the protocol version, server name and version, and capabilities as a simple key-value list.
tools/call responses show the returned content directly, so you can read the actual text the MCP server returned.
All other responses fall back to formatted JSON.

Raw

Shows the full JSON, pretty-printed, so you can inspect every field.

Sample MCP Services to Try

Here are two public MCP services that work well as starting points.

Microsoft Learn

The Microsoft Learn MCP server gives Claude Code access to the full suite of Microsoft’s documentation, including Azure, .NET, and the rest of Microsoft’s product ecosystem.

Destination URL:

https://learn.microsoft.com/api/mcp

Once registered, try asking Claude Code:

How do I create an Azure Container App using the az CLI?

You will see Claude Code call tools/list to discover the available tools, and then it will call one or more of them to fetch the relevant documentation, and finally it uses the results to answer your question. The MCP Observer shows each of those calls as they happen.

Context7

Context7 provides up-to-date documentation for popular libraries and frameworks. It is particularly useful for questions about rapidly changing ecosystems like Next.js, where training data can be out of date.

Destination URL:

https://mcp.context7.com/mcp

Once registered, try asking Claude Code:

How do I set up middleware in Next.js 15? Use context7

The Use context7 hint tells Claude Code to prioritise the Context7 MCP server for this query. Watch the MCP Observer to see how it resolves the library ID, fetches the relevant documentation, and uses it to answer your question.

A Practical Example: Watching a tools/call in Action

To make this concrete, here is what happens when you ask Claude Code the Azure Container App question above.

You type your prompt. Claude Code connects to the MCP server and the observer captures the following sequence:

Clicking the tools/list row in Pretty view shows all the tools the Microsoft Learn MCP server exposes: their names, descriptions, and accepted parameters. Clicking the tools/call row shows exactly what Claude Code asked for and what the server returned.

MCP Requests and Hooks

The MCP Observer shows you the protocol-level conversation between Claude Code and the MCP server. But there is a complementary view available in the Conversation View if you have hooks configured.

Claude Code fires PreToolUse and PostToolUse hook events for every MCP tool call, just as it does for built-in tools like Read or Bash.

The MCP Observer and the Conversation View complement each other. The observer shows you the raw protocol detail. The Conversation View with hooks shows you the full picture of what the agent was doing and why.

Here is an example of a PreToolUse call:

If you have set up HookAgent as described in the previous post in this series, those events appear in the Conversation View alongside the LLM API calls. This lets you see MCP tool usage in context: you can watch the LLM call that triggered the tool call, the hook events that fired around it, and the next LLM call that consumed the result, all on the same timeline.

Why This Matters

Most developers who start using MCP servers treat them as a black box. You register a server, Claude Code uses it, and something useful happens. But what tools does the server expose? What does Claude Code actually ask it? What does the server send back?

Those are exactly the questions the MCP Observer answers. Once you can see the traffic, you can evaluate whether a server is giving Claude Code good information, whether the tool descriptions are clear enough for the model to use them correctly, and whether the responses are fast enough to be practical.

For anyone building their own MCP server, the observer is invaluable. You can see exactly how Claude Code interacts with your server during development, without adding any logging to the server itself.

What’s Next

The Coding Agent Explorer now covers three layers of Claude Code’s operation:

LLM API (HTTP Inspector and Conversation View)
Lifecycle events (hooks)
MCP servers (MCP Observer)

Together they give you a complete picture of what the agent is doing at every level.

The full project is open-source and available on GitHub: github.com/tndata/CodingAgentExplorer

I Want Your Feedback!

If you try the MCP Observer and find a bug, have a feature request, or want to share your experience, please create an issue on GitHub. Contributions are welcome. The codebase is intentionally simple to make it easy to jump in.

Want to Learn Agentic Development?

I am currently working on a workshop called Agentic Development with Claude Code where we use the Coding Agent Explorer to explore how coding agents work under the hood. The MCP Observer is one of the tools I use to show participants exactly how Claude Code discovers and uses external tools.

You can read more about my workshops here: tn-data.se/courses

I also give a presentation called How Does a Coding Agent Work? for companies and conferences. Contact me if you are interested.

Frequently Asked Questions

Does the MCP Observer affect Claude Code or the MCP server in any way?

No. The observer forwards requests and responses without modification. Both Claude Code and the MCP server behave exactly as they would without the proxy.

Can I use the MCP Observer with any MCP server?

Yes, as long as the server uses the streamable HTTP transport (which all modern MCP servers do). Enter the server’s URL in the destination field and click Set.

Can I watch multiple MCP servers at the same time?

Not currently. The observer is configured for one destination at a time. To switch servers, enter the new URL and click Set. The request history is cleared when you change the destination. After changing the URL you must also restart Claude Code, as it caches tool information from the MCP server at startup and will not pick up the new server’s tools until it reconnects.

Why does changing the destination clear the request history?

Mixing requests from different servers in the same list would make the timeline confusing and hard to read. Clearing on change keeps the view focused on the server you are currently observing.

Do I need to restart Claude Code after registering the proxy?

Always start Claude Code after the Coding Agent Explorer is already running and after you have set the destination URL in the MCP Observer dashboard. Claude Code connects to the MCP server during startup to discover its tools. If the proxy is not yet active when Claude Code starts, it will not find any tools.

Can I observe STDIO-based MCP servers?

Not with the MCP Observer, which only works with HTTP transport. However, Claude Code fires PreToolUse and PostToolUse hook events for every MCP tool call regardless of transport. If you have hooks configured, those events appear in the Conversation View and show you which tool was called and what parameters were passed. It is a higher-level view than the raw JSON-RPC protocol, but it gives you meaningful visibility into what the agent is doing. See the previous post in this series for details on setting up hooks.

Exploring Claude Code Hooks with the Coding Agent Explorer (.NET)

Tore Nestenius — Fri, 20 Mar 2026 00:00:00 GMT

Ever wondered what Claude Code is actually doing while it works? Every file it reads, every command it runs, every permission it requests. Claude Code exposes all of this through a hook system that lets you intercept and observe each step.

In this post, you’ll learn what hooks are, how to set them up, and how to use the Coding Agent Explorer to visualize hook events in real time.

The post is part of a multi-part series on the Coding Agent Explorer, an open-source .NET tool for inspecting what AI coding agents do under the hood. You can jump to the section you need, but for background and context, it’s best to start here:

Part 1 - Introducing the Coding Agent Explorer (.NET)
Part 2 - Exploring Claude Code Hooks with the Coding Agent Explorer
Part 3 - Visualizing Claude Code MCP Requests with the Coding Agent Explorer (coming soon)

To make this more concrete, the diagram below shows how Claude Code emits hook events, how each event triggers a call to HookAgent, and how those events are then forwarded to the Coding Agent Explorer for visualization.

Each time a hook event occurs, Claude Code invokes HookAgent, which receives the event data and forwards it to the Coding Agent Explorer, where it appears in the dashboard in real time.

What Are Claude Code Hooks?

When things happen inside Claude Code, it can execute a hook. For example, when Claude Code:

Reading or writing a file
Running a shell command
Requesting a permission
Starting or ending a session
Submitting a user prompt

The diagram below highlights several of the hook events that Claude Code generates during execution.

A hook is simply a shell command that Claude Code runs at that point, passing a JSON payload describing the event via standard input (stdin). This gives you a way to extend, observe, and control Claude Code’s behavior from the outside.

What can hooks be used for?

Hooks turn Claude Code from a black box into something you can observe, control, and extend. In practice, they let you:

Enforce security policies before tools run
Log and audit tool usage
Trigger external automation
Notify external systems (Slack, CI, etc.)

In short, hooks let you move from observing the agent to controlling how it behaves.

Example: Block access to secret files

A classic use case is intercepting PreToolUse events to block the agent from accessing files it should not touch.

Let’s say we have a file named Secret.key that we never want Claude Code to read. When the agent attempts to access it, your PreToolUse hook intercepts the request, inspects the file path, and blocks the operation by returning a non-zero exit code with an error message. Claude Code respects the response and continues without ever opening the file.

The diagram below illustrates how the PreToolUse hook intercepts and blocks the request.

Here’s what Claude Code sends to the hook via stdin when it tries to read secret.key:

{
  "session_id": "9ec4714b-3475-4773-b4af-3f70d7fe68f7",
  "transcript_path": "C:\\Users\\Tore\\.claude\\projects\\C--Conf\\9ec4714b-3475-4773-b4af-3f70d7fe68f7.jsonl",
  "cwd": "C:\\MyApp",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Read",
  "tool_input": {
    "file_path": "C:\\MyApp\\Secret.key"
  },
  "tool_use_id": "toolu_01BQ4EQBtbxbFRoTEc1CXRgf"
}

How can a hook control Claude Code?

Hooks are not just for observing behavior; they can actively influence what Claude Code is allowed to do.

When a hook runs, it returns an exit code and an optional message. Claude Code uses this response to decide what happens next:

Exit code 0
allow the action to proceed
Non-zero exit code
block the action

The optional message is just as important. When an action is blocked, the message is passed back to Claude Code and becomes part of the model’s context. Instead of just failing, the agent receives feedback it can use to adjust its behavior.

In other words, the exit code enforces the decision, while the message helps guide what happens next

Which events can we hook into?

Claude Code provides four categories of hookable events:

Tool Events - PreToolUse, PostToolUse, PostToolUseFailure,..
Session Events - SessionStart, SessionEnd, PreCompact,…
Subagent Lifecycle - SubagentStart, SubagentStop, TaskCompleted, …
User Interaction - UserPromptSubmit, Notification, PermissionRequest, …

The diagram below gives a high-level overview of how hook events are grouped and emitted by Claude Code.

A complete reference for all events is included later in this post.

Why Hooks Matter for Every Project

Beyond observability, hooks are one of the most important control points available in any Claude Code project. By registering a PreToolUse hook, you get to run your own code before any tool executes, giving you the opportunity to inspect, block, or log every action the agent attempts.

This is a practical and effective way to restrict how Claude Code interacts with tools and files. You can block reads and writes to sensitive files and directories (credentials, .env files, private keys, config folders), prevent specific shell commands from running, and define clear rules around what the agent is allowed to touch.

Because your hook runs in your environment, it is always invoked before the tool executes and cannot be skipped through prompt manipulation alone. However, the effectiveness of the protection depends on how your hook validates and enforces its rules.

Hooks also provide a meaningful defense against p****rompt injection attacks. If a malicious file or web page contains hidden instructions telling Claude Code to exfiltrate data or modify a sensitive file, a PreToolUse hook can catch the attempt before the tool executes and block it with a non-zero exit code. Claude Code reads your error message and stops, preventing the action from reaching the file system.

In practice, hooks act as a powerful guardrail and auditing layer. For stronger guarantees, especially when shell access is enabled, they should be combined with environment-level controls such as filesystem restrictions or sandboxing.

In other words, hooks are one layer in a broader security model and should be combined with other controls for robust protection.

How to Observe Claude Code Hooks in Real Time

But how can we observe exactly when hooks are called and what data is passed to them? That is where the Coding Agent Explorer and its HookAgent tool come in.

Here is what the rest of this post covers:

How the HookAgent tool bridges Claude Code and the dashboard
How to set everything up in a few minutes
What you can actually see once it is running

Introducing HookAgent

HookAgent is a small companion CLI tool that ships with the Coding Agent Explorer. It acts as the bridge between Claude Code’s hook system and the Coding Agent Explorer.

The diagram below shows how HookAgent receives hook events from Claude Code and forwards them to the Coding Agent Explorer.

To use it, configure Claude Code to call HookAgent for each hook event you want to capture. From that point on, every time Claude Code fires a hook, it runs HookAgent and passes the event data via stdin.

HookAgent’s core responsibility is simple:

Read the incoming event from stdin
Attach Claude Code environment variables like CLAUDE_PROJECT_DIR and CLAUDE_SESSION_ID
Forward everything to the Coding Agent Explorer via a single HTTP POST request.
When the Explorer receives a hook event, it updates the dashboard in real time.

If the Explorer is not running when a hook fires, HookAgent exits immediately and Claude Code continues normally. Observability is always optional.

FACT: stdin and exit codes

stdin (standard input) is a standard way for one process to send data to another; in this case, Claude Code passes the hook event JSON as text to HookAgent via stdin.

The exit code is how a process reports the result back: 0 (zero) means success, while any non-zero value signals an error and can be used to block an action.

Getting Started with HookAgent

Getting hooks running takes about five minutes. Here is what you need.

Prerequisites

Before you get started, make sure you have the following installed and ready:

.NET 10 SDK installed.
Coding Agent Explorer source code downloaded.
Claude Code installed

See Introducing the Coding Agent Explorer for installation and setup instructions.

Step 1: Build HookAgent

Open a terminal in the root folder of the Coding Agent Explorer and run the appropriate publish script for your platform:

Windows:

publish.bat

macOS / Linux:

bash publish.sh

This builds both the Coding Agent Explorer and HookAgent into the Published folder:

Published/CodingAgentExplorer
The proxy and dashboard.
Published/HookAgent/HookAgent.exe
HookAgent (Windows: .exe, macOS/Linux: no extension).

Step 2: Create a working directory

Create a fresh folder where you will run claude (in this example, we name it MyApp), then copy the HookAgent folder from the Published folder into it. After copying, your working directory should look like this:

Windows:

C:\MyApp\HookAgent\HookAgent.exe

macOS / Linux:

~/MyApp/HookAgent/HookAgent

Step 3: Configure Claude Code hooks

The Coding Agent Explorer includes ready-to-use sample settings.json files for each platform.

Create a .claude folder in your working directory (MyApp) if it does not already exist.
Copy the sample settings.json for your platform into that .claude folder.

Use one of these sample files:

Windows: HookAgentSample-Settings-Windowssettings.json
macOS / Linux: HookAgent/Sample-Settings-LinuxMacOS/settings.json

Your working directory should now look like this:
Windows:

C:\MyApp\
      HookAgent\HookAgent.exe
     .claude\settings.json

macOS / Linux:

~/MyApp/
    HookAgent/HookAgent
    .claude/settings.json

This registers HookAgent for all Claude Code hook events. Feel free to remove any events you do not need. The full list of supported events and the settings.json syntax is documented in the Claude Code hooks reference.

The “matcher”: ”.*” field is a regex pattern applied to the tool name. .* matches all tools, so the hook fires for every tool call under that event. You can narrow it down. For example, “matcher”: “Bash” would only fire for Bash tool calls. Not all events support a matcher.

Note: Claude Code runs hook commands through bash on all platforms, including Windows. Always use forward slashes in the command path. The Windows sample uses HookAgent/HookAgent.exe. The macOS/Linux sample uses HookAgent/HookAgent with no .exe extension.

Step 4: Verify the hooks are registered

Start Claude Code from your working directory and run the /hooks command:

/hooks

Claude Code will list every configured hook event and the command registered for each one. You should see all hook events pointing to HookAgent. If the list is empty or events are missing, check that .claude/settings.json is in the right folder and that the JSON is valid.

Once you have confirmed the hooks are registered, exit Claude Code and move on to the next step.

Step 5: Start the Coding Agent Explorer

From the Coding Agent Explorer folder, start the Explorer:

dotnet run

On Windows the browser opens automatically. On macOS and Linux, open the dashboard manually at https://localhost:5001.

Don’t forget to enable the proxy in Claude Code as described in the previous post in this series.

Step 6: Test HookAgent

With the Explorer running, test HookAgent from your working directory before starting a full Claude Code session:

Windows (PowerShell):

{"hook_event_name":"UserPromptSubmit","session_id":"test"}' | HookAgentHookAgent.exe

Windows (cmd):

echo {"hook_event_name":"UserPromptSubmit","session_id":"test"} | HookAgentHookAgent.exe

macOS / Linux:

echo '{"hook_event_name":"UserPromptSubmit","session_id":"test"}' | HookAgent/HookAgent

A UserPromptSubmit event should appear in the Conversation View immediately. Make sure the “Hook Events” checkbox in the Conversation View is checked. If the Explorer is not running, the command exits silently and Claude Code is never affected.

Step 7: Run Claude

From your working directory (C:MyApp on Windows, ~/MyApp on macOS/Linux), run:

claude

Hook events will start appearing in the Conversation View as soon as Claude Code starts up, and then for every action it takes. Make sure the “Hook Events” checkbox in the Conversation View is checked, otherwise hook events will be hidden.

Seeing Claude Code Hooks and Tool Calls in Real Time

Once everything is running, the Conversation View becomes a live timeline of everything Claude Code does, with hook events interleaved alongside the API calls. You get a complete picture that was previously invisible.

Here is what a typical interaction looks like on the timeline when you ask Claude Code to fix a bug:

13:42:01 SessionStart
13:42:03 UserPromptSubmit "Fix the null reference exception in UserService.cs"
13:42:03 POST /v1/messages (Claude thinks about what to do)
13:42:05 PreToolUse Read (about to read UserService.cs)
13:42:05 PostToolUse Read (file contents returned)
13:42:05 POST /v1/messages (Claude analyses the code)
13:42:08 PreToolUse Edit (about to write the fix)
13:42:08 PostToolUse Edit (file updated)
13:42:08 POST /v1/messages (Claude confirms the fix)
13:42:10 Stop

In under 10 seconds, Claude Code made 3 LLM calls and 2 tool calls. Without hooks, you only see the API requests. With hooks, you see the full story.

Clicking any hook event in the timeline opens the full JSON payload. For a PreToolUse event, for example, you see the tool name, the exact input parameters, the session ID, and the working directory. For a PermissionRequest, you see exactly what Claude Code wants to do and why.

{
  "session_id": "814cc648-5d90-44e2-9239-144ad62abc76",
  "transcript_path": "C:\\Users\\Tore\\.claude\\projects\\C--Conf\\814cc648-5d90-44e2-9239-144ad62abc76.jsonl",
  "cwd": "C:\\Conf",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Glob",
  "tool_input": {
    "pattern": "**/UserService.cs"
  },
  "tool_use_id": "toolu_019GP34HeFh8N4QkWQWdAyUA"
}

Why This Is Useful in Workshops

I use the hooks feature extensively in my workshops on agentic development. The question I hear most often from developers who are new to coding agents is:

But what is it actually doing? And what data is actually passed to my hooks?

The Conversation View with hooks answers that question directly. You can project the dashboard on a shared screen and watch every session event, tool call, and permission request appear in real time as Claude Code works. It turns the agent from a magic black box into a system that developers can reason about, question, and understand.

In my experience, once developers see the full picture, a lot of things click. They understand why the agent reads files before editing them. They see how it loops back to the LLM after each tool call. They notice where token costs accumulate. And they start writing better prompts as a result.

For more details about my workshops and training classes, visit tn-data.se/training.

Claude Code Hook Events Reference

As of today, Claude Code supports these hook events. For the full and up-to-date reference, see the Claude Code hooks documentation.

SessionStart
Session begins or resumes
UserPromptSubmit
User submits a prompt
PreToolUse
Fires before any tool executes
PostToolUse
Fires after a tool succeeds
PostToolUseFailure
Fires after a tool fails
PermissionRequest
Claude Code requests permission to perform an action
Stop
Claude finishes responding
SubagentStart
A subagent is started
SubagentStop
A subagent finishes execution
Notification
Claude Code sends a notification
PreCompact
Fires before context compaction
ConfigChange
A settings file changes
TeammateIdle
Agent team coordination event
TaskCompleted
A task is marked as complete
SessionEnd
Session terminates

The PreToolUse and PostToolUse events are the most useful in practice. They fire for every tool call, whether it is a file read, a bash command, a web fetch, or an MCP tool invocation. Together, they give you a complete record of every action the agent takes.

PreToolUse is where you enforce rules: block access to sensitive files, reject dangerous shell commands, or log what the agent is about to do.
PostToolUse fires after a tool succeeds and is where you react to what just happened. When a tool fails, PostToolUseFailure fires instead and provides the error details.

Common uses include:

Run your test suite automatically after the agent edits a file
Trigger a linter or code formatter after a write
Log the completed action to an audit trail
Notify an external system (Slack, CI pipeline) that a file changed
Inspect the tool output before the agent continue

What’s Next: Inspecting Claude Code with MCP Observer

This post covered the hooks feature. The next post in this series will look at the MCP Observer, a new feature that lets you intercept and inspect traffic between Claude Code and any Model Context Protocol (MCP) server. If you’ve ever wanted to understand how MCP tools like Microsoft Learn or Context7 actually work under the hood when Claude Code uses them, that post is for you.

In the meantime, the full project is open-source and available on GitHub: github.com/tndata/CodingAgentExplorer.

I Want Your Feedback

The Coding Agent Explorer is open-source and I want to improve it with your help. If you find a bug, have a feature request, or want to share your experience, please create an issue on GitHub. I read every issue and appreciate all feedback.

Contributions are also very welcome. The codebase is intentionally kept simple (a single NuGet dependency, a vanilla JS frontend) to make it easy for anyone to jump in.

Want to Learn Agentic Development?

If this topic interests you, I’d love to help you go deeper. I’m currently working on a workshop called Agentic Development with Claude Code, where we explore how coding agents work, how to use them effectively, and how to build workflows around them. The Coding Agent Explorer is one of the tools I to use to help participants see what is really happening behind the scenes.

Learn more about my AI and Claude Code workshops and courses: Agentic Development and AI workshops.

I also give a presentation called How Does a Coding Agent Work? that covers the architecture and inner workings of AI coding agents. Contact me if you’d like me to run this at your company or conference.

Claude Code Hooks FAQ

Here are answers to common questions about how hooks work in Claude Code, how to configure them, and what to expect in practice.

Does HookAgent slow down Claude Code?

No. HookAgent makes a single HTTP POST per event and exits. The call is fast, and if the dashboard is not running it returns immediately. In practice, you will not notice any difference in Claude Code’s responsiveness.

Do I need to change my project or code to use hooks?

No. You only need to create or update the .claude/settings.json file in the directory where you run claude. Nothing in your project code changes.

Can I use only some of the hook events?

Yes. You can remove any hook entries from settings.json that you don’t want. For example, if you only care about tool calls, keep PreToolUse and PostToolUse and remove the rest.

Does this work on macOS and Linux?

Yes. Use publish.bat on Windows or bash publish.sh on macOS and Linux. Each script detects the current platform and builds a single-file HookAgent executable for it. On Linux and macOS the executable has no .exe extension, so use HookAgent/HookAgent as the command path in your settings.json.

Is this tool suitable for production use?

No. The Coding Agent Explorer is designed as a development and teaching tool. It is not intended for production use.

Can I block all sensitive file access using PreToolUse?

Not completely. PreToolUse lets you block direct tool calls (like reading secret.key), but it does not provide a true sandbox.

For example, the model might:

Generate a script (e.g. Bash or PowerShell) that reads files indirectly
Request access to a broader directory (e.g. “load all files in this folder”)
Use other tools or workflows that bypass your specific path checks

If you give Claude Code shell access (Bash, command line, PowerShell, etc.), it can effectively do anything you can do within that environment; including reading sensitive files through indirect means.

Even for direct tool calls, your hook logic must be implemented carefully. Naive checks (for example simple string matching on file paths) can sometimes be bypassed using variations in path representation, encoding, or traversal patterns. In practice, you need to normalize and validate inputs rigorously.

In other words, you are filtering requests, not enforcing OS-level isolation.

What does it take to truly secure file access?

If you need strong guarantees, you need to move beyond hooks and enforce restrictions at the environment level:

Run Claude Code in a sandbox
(container, VM, or restricted workspace)
**Limit filesystem permissions
**(only expose allowed directories)
Disable or tightly restrict shell access
(for example by disabling the Bash tool or restricting what commands can be executed, since it can be used to invoke other interpreters like PowerShell or cmd)
**Use allowlists instead of blocklists
**(explicitly permit safe paths only)

Hooks are best used as a guardrail and observability layer, not as your primary security boundary.

Links to other blog posts

Introducing the Coding Agent Explorer (.NET)

Tore Nestenius — Sat, 14 Feb 2026 00:00:00 GMT

I’m excited to introduce you to the Coding Agent Explorer, a new open-source .NET teaching tool I’ve created that lets you see exactly what happens under the hood when an AI coding agent works on your code.

It currently supports Claude Code (with more agents on the roadmap), and it is designed to help developers understand and adopt agentic development. If you’ve ever wondered what’s really going on between your prompts and the code changes that magically appear, this tool lets you see inside the process.

This article is part of a multi-part series on the Coding Agent Explorer, an open-source .NET tool for understanding what AI coding agents do under the hood.

Coding Agent Explorer Series

If you’re new to the tool, start with Part 1. Otherwise, jump to the section that interests you:

Part 1 – Introducing the Coding Agent Explorer (.NET)
Part 2 – Exploring Claude Code Hooks with the Coding Agent Explorer
Part 3 – Visualizing Claude Code MCP Requests with the Coding Agent Explorer (coming soon)

Here’s what you’ll learn:

Why understanding coding agents matters for every developer
What the Coding Agent Explorer does and how it works
How to get started in just a few minutes
What’s on the roadmap

Let’s dive in!

What Is Agentic Development?

Before we dive into the tool itself, let’s talk about what agentic development means. In traditional AI-assisted coding, you might get autocomplete suggestions or ask a chatbot a question and then copy the answer into your code. But agentic development takes this much further.

In agentic development, an AI agent operates autonomously inside your development environment. It can read your files, search your codebase, run commands, edit code, and even verify its own changes.

Instead of just suggesting code to you, the agent acts on your behalf, working through multi-step tasks in a loop: it thinks about what to do, takes an action, observes the result, and then decides what to do next.

Several tools have emerged in this space:

Claude Code by Anthropic, a CLI-based coding agent
GitHub Copilot, an AI development assistant
Cursor, an AI-first code editor with agentic features
Windsurf, another AI-powered editor
Lovable, focused on AI-driven app generation

These tools are rapidly changing how developers write software. But with all this autonomy, it becomes even more important to understand what the agent is actually doing! That’s where the Coding Agent Explorer comes in.

Why I Built This Tool

In my role as instructor and creating training material, I often create hands-on tools to help participants better understand, visualize, and grasp the various concepts that I teach.

The goal is that all participants should have a solid mental model of how things actually work under the hood. This is the same approach I took with the CloudDebugger, an open-source tool I created for teaching Azure to developers.

With AI coding agents becoming part of the mainstream developer toolkit, I saw the same need. For most of us, the experience feels like a black box: you type a prompt, something happens behind the scenes, and code appears.

But what is really going on?

I wanted a tool that lets you peek inside that black box and see every API call, every tool invocation, and every decision the agent makes. This tool helps you answer questions like:

How are tools and MCP servers used by the agent?
What does the /init command actually do?
What happens when I enable plan mode?
How many tokens do my tools and system prompt consume?
How can an agent read and modify my files?

With insight into the agent’s decisions, you can refine your prompts, reduce unnecessary tool calls, and reduce token costs.

What Is the Coding Agent Explorer?

The Coding Agent Explorer is a .NET reverse proxy combined with a real-time web dashboard. It sits between your coding agent (currently Claude Code) and the Anthropic API, intercepting every request and response that flows between them. Everything it captures is displayed in a live dashboard that you can explore while the agent is working or after the work is complete.

Here’s how the architecture looks at a high level:

The proxy captures all API traffic and streams it to the dashboard using SignalR for real-time updates. You see everything as it happens with no delay.

On the technology side, the project is built with:

.NET 10 and ASP.NET Core
YARP (Yet Another Reverse Proxy) for the proxy layer
SignalR for real-time communication between the proxy and the dashboard
A vanilla HTML/JS/CSS frontend

Three Ways to Explore With Coding Agent

The dashboard provides thre complementary views for exploring what the coding agent is doing. Each gives you a different perspective on the same data. The MCP Observer will be covered in a separate blog post.

The HTTP Inspector

The HTTP Inspector is the raw, detailed view. It shows every API call in a table with the key information at a glance: timestamp, HTTP method, model used, token counts, and timing.

You can click on any row to inspect the full details:

Request and response headers in their entirety
Request and response bodies, formatted for easy reading
Real-time response data, so you can see the full response as it was received by the agent
Token usage breakdown: input tokens, output tokens, cache creation tokens, and cache read tokens
Performance metrics: total duration and time-to-first-token

This view is especially valuable when you want to understand the technical details of the API communication. You can see exactly what the agent sends to the model, what the model responds with, and how long each step takes.

Then, you can click on a given request and view all the request and response details:

However, this view is useful, but not really helpful when you’re trying to understand how an agent works. This is why we also added the Conversation View, which allows you to make sense of all of these requests.

The Conversation View

The Conversation View takes the same API data and renders it in a chat-style format that’s easier to follow. Instead of raw HTTP traffic, you see the conversation as it unfolds:

System prompts that set up the agent’s behavior
User messages (your prompts)
Assistant responses with the agent’s reasoning
Tool calls like Read, Write, Bash, Grep, and others, showing exactly what the agent does
Tool results showing what came back from each tool invocation
MCP tool usage, letting you explore how the agent presents and invokes CP servers when communicating with the LLM

Large content sections are also collapsible, so you can focus on the parts that interest you. Each message also provides token and character statistics, giving you a sense of how much context each part of the conversation consumes.

This is the view I use the most in my workshops. It gives you a clear picture of how the agent “thinks”. That shows how it breaks down a problem, which tools it decides to use, and how it iterates toward a solution.

What Can You Learn From It?

Once you start monitoring the agent’s API calls, you’ll discover many things that aren’t obvious from the outside. Here are some of the insights that the Coding Agent Explorer reveals to us:

How prompts are constructed.
You’ll see the actual system prompts that Claude Code sends to the model. These are far more detailed than you might expect. Impressively, you’ll get to see instructions about tool usage, safety, code style, and more.
Tool usage patterns.
You’ll also see how the model selects and invokes tools like Read, Write, Bash, Grep, and Glob. You’ll notice how it reads files before editing them, how it searches for code, and how it verifies its changes.
Token economics.
It reveals what costs tokens and how prompt caching works. You’ll see cache creation tokens (when the model stores a prompt prefix), and cache read tokens (when it reuses a cached prefix). This is key for understanding performance and cost with these agents.
The agentic conversation loop.
Another cool feature is seeing how the back-and-forth between the agent and the API works. Each “turn” involves the model generating a response (potentially with tool calls), the agent executing those tools, and then sending the results back to the model. This loop continues until the task is complete.
Real-time observation.
You’ll be able to see the entire conversation unfold in real time as the agent works, giving you immediate insight into what it’s doing and why.
Multi-model execution
Observe how tasks are distributed between models such as Haiku and Opus.

Have you wondered why Claude Code sometimes seems to “think” for a while before responding? The Conversation View shows you exactly what’s happening: the agent might be reading multiple files, searching for patterns, or analyzing code before it starts writing its response to you.

Getting Started

Getting the Coding Agent Explorer running doesn’t take as long as you might think; it takes just a few minutes. Here’s the quick version (the GitHub README has full details):

Prerequisites: You’ll need the .NET 10 SDK installed.

1. Clone and run the project:

git clone https://github.com/tndata/CodingAgentExplorer.git cd CodingAgentExplorer dotnet run

This starts three endpoints:

The reverse proxy on port 8888
The web dashboard on ports 5000 (HTTP) and 5001 (HTTPS).

The dashboard opens automatically in your browser.

2. Point Claude Code at the proxy:

On Windows (cmd):

set ANTHROPIC_BASE_URL=http://localhost:8888

On Windows (PowerShell):

$env:ANTHROPIC_BASE_URL = "http://localhost:8888"

The repository also includes EnableProxy.bat and DisableProxy.bat scripts for convenience. These only affect the current terminal session, so closing the terminal automatically clears the setting.

3. Use Claude Code as normal.

Every API call will now flow through the proxy, and you’ll see it appear in the dashboard in real time.

Note: The proxy only listens on localhost and is not exposed to the network. API keys are automatically redacted from the stored data. Request data is kept in memory only (up to 1,000 requests), with no persistence to disk.

It’s Time to Understand How Coding Agents Work

AI coding agents are becoming a real part of the daily developer workflow. More and more developers and teams are integrating them into how they write, review, and maintain code.

As .NET developers, we have a tradition of wanting to understand the tools we use, and we’ll ultimately need to bring the same curiosity and rigor into understanding how AI coding agents work, too.

For example, while writing the blog post DefaultAzureCredential Under the Hood, I cloned the Azure SDK for .NET repository and patched the code locally to better understand how the token credential requests access tokens from Azure. That hands-on exploration gave me insights that go beyond what the documentation alone can provide.

For example, we can examine in detail how Claude Code uses its tools:

In my workshops, I often say, “The things you’re scared of, you should do more often.”

If coding agents feel like magic or a mystery, that’s exactly why you should look under the hood. Understanding what the agent does (and doesn’t do) helps you write better prompts, catch mistakes earlier, and build trust in the tool.

I Want Your Feedback!

The Coding Agent Explorer is open-source, and I want to improve it with your help. If you find a bug, have a feature request, or want to share your experience with the tool, please create an issue on GitHub. I read every issue and appreciate all feedback.

Contributions are also welcome!

The codebase is intentionally kept simple (single NuGet dependency, vanilla frontend) to make it easy for anyone to jump in.

Fun fact: The first pull request arrived four days after I published the tool, before I had even announced it.

Currently, the tool only supports Claude Code with the Anthropic API. Support for other coding agents and API providers is on the roadmap. If there’s a specific agent you’d like to see supported, let me know in the issues. Your input helps me prioritize what to build next.

Want to Learn Agentic Development?

If this topic interests you, I’d love to help you go deeper. I am working on a new workshop called “Agentic Development with Claude Code”, where we explore how coding agents work, how to use them effectively, and how to build workflows around them. The Coding Agent Explorer is one of the tools that I use in the workshop to help participants see what’s really happening behind the scenes.

You can read more about the Agentic Development workshop and other development courses here: Agentic Development & Development Workshops.

I also have a presentation called “How Does a Coding Agent Work?” that covers the architecture and inner workings of AI coding agents. Contact me if you’d like me to run this presentation at your company or conference.

More information about my AI development talks is available here: AI Development Talks & Presentations.

Frequently Asked Questions

If you’re considering using the Coding Agent Explorer with Claude Code, these are the most common questions about setup, security, performance, and intended use.

Does this tool work with coding agents other than Claude Code?

Not yet. The Coding Agent Explorer currently only supports Claude Code via the Anthropic API. Support for other coding agents and API providers is on the roadmap. If there’s a specific agent you’d like to see supported, let me know on GitHub.

Does the proxy affect Claude Code’s performance?

The proxy adds minimal overhead. It captures traffic as it passes through, but does not modify or delay requests or responses in any meaningful way.

Is my API key safe?

Yes. API keys (x-api-key and Authorization headers) are automatically redacted from all stored request data. The proxy only listens on localhost, so it is never exposed to the network. All captured data is kept in memory only and is lost when you stop the application.

Do I need to change my code or project to use this?

No. You only need to set a single environment variable (ANTHROPIC_BASE_URL) to point Claude Code at the proxy. Everything else works exactly as before. When you’re done, just close the terminal or clear the variable.

Can I use this in production?

The Coding Agent Explorer is designed as a development and teaching tool. It is not intended for production use. Use it locally when you want to learn, debug, or demonstrate how a coding agent works.

Links to other blog posts

Duende IdentityServer 7: A Complete Setup Guide for ASP.NET Core

Tore Nestenius — Thu, 22 Jan 2026 00:00:00 GMT

Duende IdentityServer is the leading OpenID Connect and OAuth 2 server for .NET. In this tutorial, I’ll walk you through setting up Duende IdentityServer 7.4.4 from scratch using ASP.NET Core 10.

What you’ll learn:

How to add and configure the IdentityServer middleware
How to integrate the sample user interface for login and logout
How to set up test users and in-memory configuration
How the request pipeline and middleware order work together
How to configure Serilog for comprehensive logging

My Personal IdentityServer Journey

My deep dive into IdentityServer started when customers began asking about OpenID Connect and authentication. I’ll be honest: these topics intimidated me at first. **_But I live by a simple motto: the things you’re scared of, you should do more often.

_**So I decided to crack the code.

I immersed myself in the material, created training workshops, and forced myself to really understand how everything worked. To cement my learning, I started answering questions on Stack Overflow and presenting at conferences and user groups.

New to OpenID-Connect?

Before diving into Duende IdentityServer, I highly recommend familiarizing yourself with OpenID Connect and OAuth first. IdentityServer builds on these protocols, and understanding concepts such as tokens, scopes, claims, and flows will make this tutorial much easier to follow.

To get started, check out my OpenID Connect for Developers tutorial, which provides an in-depth introduction tailored for developers.

Starting from Scratch

In this tutorial, we’ll start with the ASP.NET Core Empty project template and build a working Duende IdentityServer setup, step by step.

By starting from scratch, you’ll understand exactly what each component does, why it’s needed, and how everything fits together.

Why Build from Scratch?

Duende provides a set of excellent templates that get you up and running quickly, including:

Duende BFF Host using a Remote API
Duende BFF using a Local API
Duende BFF with Blazor autorender
Duende IdentityServer Empty
Duende IdentityServer Quickstart UI (UI assets only)
Duende IdentityServer with ASP.NET Core Identity
Duende IdentityServer with Entity Framework Stores
Duende IdentityServer with In-Memory Stores and Test Users

These templates are great for getting started. However, they come with many defaults and preconfigured code that can feel like magic. When something goes wrong or you need to customize the behavior, that magic becomes a problem.

I believe you should understand everything you bring into your IdentityServer project. That’s why we’ll build our service from scratch, copying only the files and configuration that we need from the template.

By the end, you’ll have something similar to the Duende IdentityServer with In-Memory Stores and Test Users template, with one key difference: you’ll understand exactly how everything is put together.

Step #1: Creating the IdentityService Project

Let’s get started by creating a new Empty ASP.NET Core project in Visual Studio 2026.

Use the following settings:

Project name: IdentityService
Framework: .NET 10
Configure for HTTPS: Yes
Application URL: Use the .dev.localhost TLD

We won’t enable Docker container support or Aspire orchestration for this project.

STEP #2: Setting the Port and Removing the HTTP Profile

By default, ASP.NET Core assigns random ports when you create a new project. I always use port 6001 for my IdentityServer instances, so I’ll configure that now for this project.

I also removed the HTTP profile and HTTP application URL. Since this is a local development identity service, we only need HTTPS.

Note: If you plan to containerize IdentityServer, you may want to keep HTTP support for internal container-to-container communication. For more details, check out my blog post IdentityServer in Docker Containers.

After these changes, your launchSettings.json file should look like this:

{
  "profiles": {
    "https": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "dotnetRunMessages": true,
      "applicationUrl": "https://identityservice.dev.localhost:6001"
    }
  },
  "$schema": "https://json.schemastore.org/launchsettings.json"
}

STEP #3: Adding the NuGet Packages

Next, we add the following NuGet packages to the project:

Duende.IdentityServer
The core IdentityServer library that provides OpenID Connect and OAuth 2.0 server functionality.
Duende.IdentityModel
A helper library for working with claims-based identity, OAuth 2.0, and OpenID Connect. It provides types, helpers, and constants for common protocol operations.
See the documentation for details.
Serilog.AspNetCore
Serilog enables structured logging from the start, making it much easier to diagnose issues during development and transition to production logging later.

STEP #4: Configuring Logging

Next, we configure Serilog to get full logging coverage of our application.

First, we create a bootstrap logger:

Log.Logger = new LoggerConfiguration()
.MinimumLevel.Information()
.Enrich.FromLogContext()
.WriteTo.Console(formatProvider: CultureInfo.InvariantCulture)
.CreateBootstrapLogger();

This bootstrap configuration ensures Serilog is active from the very beginning, reliably capturing any configuration errors or exceptions during the initial setup phase before the full ASP.NET Core host pipeline is constructed.

The bootstrap logger alone is not enough. We also need to integrate Serilog into ASP.NET Core properly.

To do this, we:

Wrap the ASP.NET Core startup in a try/catch/finally block to catch fatal exceptions and properly close and flush the logs on exit, ensuring no log statements are lost.
Configure the ASP.NET Core logging service to use Serilog.
Add the Serilog request logger to the request pipeline.

Here’s the complete code that implements all three steps:

try
{
    Log.Information("Starting host...");
    var builder = WebApplication.CreateBuilder(args);
    builder.Services.AddSerilog((services, lc) =>
    {
        lc.MinimumLevel.Information()
          .MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
          .MinimumLevel.Override("Microsoft.AspNetCore", LogEventLevel.Warning)
          .MinimumLevel.Override("System", LogEventLevel.Warning)
          .MinimumLevel.Override("Duende", LogEventLevel.Debug)
          .ReadFrom.Services(services)
          .Enrich.FromLogContext()
          .WriteTo.Console();
    });
    var app = builder.Build();
    app.UseSerilogRequestLogging();
    app.MapGet("/", () => "Hello World!");
    app.Run();
}
catch (Exception ex) when (ex is not HostAbortedException)
{
    Log.Fatal(ex, "Unhandled exception");
}
finally
{
    Log.Information("Shut down complete");
    Log.CloseAndFlush();
}

For more details about configuring Serilog for ASP.NET Core, visit the Serilog.AspNetCore GitHub page.

AddSerilog vs. UseSerilog: What’s the Difference?

In the code above, we used the AddSerilog method. However, you might encounter the UseSerilog method in other samples and tutorials.

What’s the difference between AddSerilog and UseSerilog?

There is no difference. If you look at the source code for UseSerilog, you’ll see that it internally calls AddSerilog. However, you should use AddSerilog, as it is the official public API intended for configuring Serilog in modern .NET applications.

STEP #5: Adding Duende IdentityServer

We added the IdentityServer NuGet package to our project earlier. Now it’s time to add it to our application.

First, we register IdentityServer with the dependency injection container:

var isBuilder = builder.Services.AddIdentityServer(options =>
{
    options.Events.RaiseErrorEvents = true;
    options.Events.RaiseInformationEvents = true;
    options.Events.RaiseFailureEvents = true;
    options.Events.RaiseSuccessEvents = true;
});

Events in IdentityServer represent significant occurrences within the system, such as successful logins, token issuance, and authentication failures. These events are disabled by default, so we enable them here to capture them in our logs.

Examples of built-in events include:

ClientAuthenticationSuccessEvent
ClientAuthenticationFailureEvent
TokenIssuedSuccessEvent
TokenIssuedFailureEvent
UserLoginSuccessEvent
UserLoginFailureEvent
And more…

You can read more about events in the Duende IdentityServer documentation.

We also need to add IdentityServer to the request pipeline:

app.UseIdentityServer();

This adds the IdentityServer middleware, which intercepts and responds to requests sent to its endpoints, including the discovery document, authorization endpoint, token endpoint, and others.

STEP #6: Naming the Console Window

As your solution grows and you add separate projects for clients and APIs, you’ll often run multiple applications at once. With several console windows open, it can be hard to tell which is which.
A simple fix is to set the console title at startup:

Console.Title = "IdentityService";

Add this near the top of Program.cs. It’s a small touch that makes debugging much easier, as shown below:

STEP #7: Adding Authorization

IdentityServer needs the authorization middleware to be present in the request pipeline, so we add it by calling UseAuthorization, as shown below:

app.UseSerilogRequestLogging();

app.UseIdentityServer();

app.UseAuthorization();

app.MapGet("/", () => "Hello World!");

Note that middleware order matters here. UseAuthorization must come after UseIdentityServer, because the authorization middleware relies on a populated HttpContext.User, which is established by the authentication middleware. UseIdentityServer adds the authentication middleware internally, so you do not need to call UseAuthentication separately.

We also add these two calls to be explicit about what services we register:

builder.Services.AddAuthentication();
builder.Services.AddAuthorization();

ASP.NET Core will automatically call them for us if we omit them, but I like to always be explicit in my code, so I add them anyway. Being explicit also makes it easier to configure them later if you need to add additional authentication handlers or authorization policies.

With this in place, we will have a request pipeline that looks like this:

Authentication always occurs first, establishing the user’s identity. Then IdentityServer inspects the request to handle any OAuth 2.0 or OpenID Connect protocol requests. Finally, the authorization middleware checks whether the user has permission to access the requested resource.

What about UseAuthentication?

UseIdentityServer includes a call to UseAuthentication, so it’s not necessary to add it separately.

What does UseIdentityServer do?

Internally, it adds multiple middleware components to the ASP.NET Core request pipeline, including:

CORS (Cross-Origin Resource Sharing)
DynamicSchemeAuthentication
Authentication
MutualTlsEndpoint
IdentityServer

Want to learn more about authentication?

My Authentication and Authorization in ASP.NET Core workshop covers how these middleware components work under the hood.

STEP #8: Verifying IdentityServer is Running

That’s it! We have now implemented a working IdentityServer. But how can we tell that it’s actually working? If we start the application, we only see the default “Hello World!” message.

The IdentityServer middleware exposes endpoints for handling OAuth 2.0 and OpenID Connect requests.

We can verify that everything is working by checking the discovery document. Navigate to:

https://identityservice.dev.localhost:6001/.well-known/openid-configuration

If everything is set up correctly, you should see the discovery JSON document.

{
  "issuer": "https://identityservice.dev.localhost:6001",
  "jwks_uri": "https://identityservice.dev.localhost:6001/.well-known/openid-configuration/jwks",
  "authorization_endpoint": "https://identityservice.dev.localhost:6001/connect/authorize",
  "token_endpoint": "https://identityservice.dev.localhost:6001/connect/token",
  "userinfo_endpoint": "https://identityservice.dev.localhost:6001/connect/userinfo",
  "end_session_endpoint": "https://identityservice.dev.localhost:6001/connect/endsession",
  "check_session_iframe": "https://identityservice.dev.localhost:6001/connect/checksession",
  "revocation_endpoint": "https://identityservice.dev.localhost:6001/connect/revocation",
  "introspection_endpoint": "https://identityservice.dev.localhost:6001/connect/introspect",
  "device_authorization_endpoint": "https://identityservice.dev.localhost:6001/connect/deviceauthorization",
  "backchannel_authentication_endpoint": "https://identityservice.dev.localhost:6001/connect/ciba",
  "pushed_authorization_request_endpoint": "https://identityservice.dev.localhost:6001/connect/par",
  "require_pushed_authorization_requests": false,
  "frontchannel_logout_supported": true,
  "frontchannel_logout_session_supported": true,
  "backchannel_logout_supported": true,
  "backchannel_logout_session_supported": true,
  "scopes_supported": [
    "openid",
    "profile",
    "scope1",
    "scope2",
    "offline_access"
   ...more... }

What is the Discovery Document?

Most OpenID Connect compliant servers expose a discovery document at the /.well-known/openid-configuration endpoint. This standardized JSON document tells clients everything they need to know about the identity provider, including:

Issuer
Authorization endpoint
Token endpoint
UserInfo endpoint
JWKS (signing keys) endpoint
Supported scopes
Supported response types
Supported signing algorithms
And more…

Instead of hard-coding URLs, clients can discover them at runtime. You can read more about it in the OpenID Connect Discovery 1.0 specification.

The current setup is not particularly useful yet because we’re missing a few things, including configuration, users, and a user interface. We’ll address those next.

STEP #9: Adding the User Interface

So far, we have created our sample project, added logging, and added IdentityServer. We have seen that IdentityServer is responding to requests. Great! But are we done?

No. Right now, we have only added the OpenID Connect endpoints. The key point to understand here is that Duende IdentityServer is just a library that implements OAuth and OpenID Connect. There is no user interface. There is no built-in login or logout page.

This is actually the real power of Duende IdentityServer. By focusing solely on protocol implementation, you follow the single-responsibility principle and have complete freedom to create your own user interface. You can customize the user experience exactly how you want, whether that means matching your company’s branding, adding multi-factor authentication flows, or integrating with external identity providers.

As shown below, a complete IdentityServer setup typically consists of two parts: the protocol endpoints provided by the middleware, and a user interface for login, logout, and consent that you provide yourself.

So how do we implement this? Do we have to build it ourselves?

Luckily, no. Duende provides a sample user interface for us to use. The Duende templates include this UI, but since we’re building our IdentityServer from scratch, we need to add it manually to our project.

We’ll do that next.

STEP #10: Downloading the Duende IdentityServer Source Code

The sample user interface we will use is available in the main IdentityServer GitHub repository. We’ll be copying files from the IdentityServerInMem template.

To download the source code, go to the releases page and download the source code for the version of the Duende IdentityServer NuGet package that you added earlier. I added version 7.4.4, so I downloaded the source code for this release and unzipped it.

Then navigate to identity-servertemplatessrcIdentityServerInMem and copy the Pages and wwwroot folders to your Visual Studio project.

In Solution Explorer, you should now see these two folders:

Build your application. The solution should build successfully.

The name ‘Base64Url’ does not exist in the current context

If you encounter the error: “The name ‘Base64Url’ does not exist in the current context”, then replace:

var bytes = Base64Url.Decode(encoded);

with:

var bytes = Base64Url.DecodeFromChars(encoded);

After this change, your application should build successfully.

Why this happens

This is due to a breaking change in Duende.IdentityModel, where the previously deprecated Base64Url.Encode and Base64Url.Decode APIs were removed. The new supported APIs are EncodeToString and DecodeFromChars. For details, see the related pull request.

STEP #11: Adding MVC and Razor Pages Support

The user interface we just added won’t work yet because we haven’t enabled support for ASP.NET Core Razor Pages. To do this, we need to add:

builder.Services.AddRazorPages();

This registers the required services to support Razor Pages in ASP.NET Core.

However, this alone is not enough. We also need to add the endpoint routing middleware to the request pipeline:

app.UseRouting();

(Add this after UseSerilogRequestLogging.)

Finally, replace the existing MapGet with:

app.MapRazorPages()
.RequireAuthorization();

If you run the application now, you should see the Duende IdentityServer welcome page. Awesome!

However, you’ll notice that the static content (images, CSS, and JavaScript) is not loading. We’ll fix that next.

STEP #12: Adding Static Content Support

Adding support for static content is easy. We just add this middleware to our request pipeline:

app.UseStaticFiles();

Add it before UseSerilogRequestLogging.

Restart the application, and you should now see the standard Duende IdentityServer welcome page:

STEP #13: Troubleshooting Fiddler with dev.localhost Endpoints

At this point, we have a fully working IdentityServer instance with a user interface, static content, and authentication in place. As you continue developing and integrating clients and APIs, one thing quickly becomes essential: the ability to inspect HTTP traffic.

This is especially important when working with OpenID Connect. Many critical requests, such as token requests, introspection calls, and user info lookups, are back-channel requests that occur entirely server-to-server. These requests never appear in browser developer tools.

For inspecting this traffic, I always use Fiddler Classic, an invaluable debugging tool that you can download for free.

The ERR_TUNNEL_CONNECTION_FAILED error

If you runFiddler and try to browse your IdentityServer running on a .dev.localhost address, you may encounter the ERR_TUNNEL_CONNECTION_FAILED browser error:

This can be confusing, especially since Fiddler and ASP.NET Core have worked well together for many years.

So what changed?

What is the .dev.localhost domain?

The .dev.localhost domain is a new feature introduced in .NET 10 to simplify local HTTPS development. It allows you to use realistic, TLS-secured hostnames without manually managing certificates. You can read more about it in the
Why You Should Be Using .NET 10’s New TLS Certificate Certificate blog post.

The reason for ERR_TUNNEL_CONNECTION_FAILED

You might wonder:

**Fiddler and ASP.NET Core have always worked together, so what changed?
**
The issue lies in how domain names are resolved. Modern browsers (Chrome, Edge, and Firefox) have a built-in rule: they automatically resolve any domain ending in localhost to 127.0.0.1 internally. They don’t even bother asking your operating system where the site is.

Fiddler, however, acts as a system proxy. When your browser sends a request through Fiddler, Fiddler asks the Windows OS to resolve the address. Unlike your browser, Windows has no idea where identityservice.dev.localhost is. You can verify this by trying to ping the address in your terminal:

C:>ping identityservice.dev.localhost
 Ping request could not find host identityservice.dev.localhost. Please check the name and try again.

The Fix: Updating the Hosts File

To fix this, we need to tell Windows where to find our local development domains. We do this by adding an entry to the hosts file located at C:WindowsSystem32driversetchosts.

Open this file in a text editor by running it as an Administrator, and add the following line:

127.0.0.1 identityservice.dev.localhost

The hosts file does not support wildcards (like *.dev.localhost), so you will need to add a specific entry for each service you create.

Verifying the Connection

Once you’ve saved the file, try the ping command again. It should now resolve correctly to your local loopback address:

ping identityserv

C:\>ping identityservice.dev.localhost

Pinging identityservice.dev.localhost [127.0.0.1] with 32 bytes of data:
Reply from 127.0.0.1: bytes=32 time<1ms TTL=128
Reply from 127.0.0.1: bytes=32 time<1ms TTL=128
Reply from 127.0.0.1: bytes=32 time<1ms TTL=128
Reply from 127.0.0.1: bytes=32 time<1ms TTL=128

Now, when you run Fiddler and refresh your application, everything should work seamlessly. You will be able to see all your HTTPS traffic, decrypted and ready for inspection!

STEP #14: Adding IdentityServer Users

If we start our application and try to authenticate, perhaps by clicking the “Click here to see the claims for your current session” link (as shown below):

We get this exception:

System.InvalidOperationException:
'Please call 'AddTestUsers(TestUsers.Users)' on the IIdentityServerBuilder in
Startup or remove the TestUserStore from the AccountController.'

How do we fix this?

Conveniently, a class with sample users is included among the files we added earlier when we added the user interface. Locate the PagesTestUsers.cs file and explore its content.

To add these users to IdentityServer, we simply call the AddTestUsers method:

var isBuilder = builder.Services.AddIdentityServer(options =>
    {
        options.Events.RaiseErrorEvents = true;
        options.Events.RaiseInformationEvents = true;
        options.Events.RaiseFailureEvents = true;
        options.Events.RaiseSuccessEvents = true;
    }).AddTestUsers(TestUsers.Users);

Restart the application and try to authenticate again. You should now be presented with a login screen. Enter bob as the username and bob as the password, and the login should succeed.

This confirms that our test users work and that we can authenticate using these credentials.

STEP #15: Adding IdentityServer Configuration

An IdentityServer with users is a good start. However, it won’t be very useful if we don’t define the IdentityResources, ApiScopes, and Clients.

A sample configuration file can be found in the in-memory template that we copied files from earlier. Go back to the source code and copy the Config.cs file found in identity-servertemplatessrcIdentityServerInMem and add it to the root of your project.

Open this file in Visual Studio and review its contents. You’ll find some sample resources and clients defined.

To add these configuration options to IdentityServer, add the following lines after AddIdentityServer:

// in-memory, code config
isBuilder.AddInMemoryIdentityResources(Config.IdentityResources);
isBuilder.AddInMemoryApiScopes(Config.ApiScopes);
isBuilder.AddInMemoryClients(Config.Clients);

For more details about these concepts, see my blog post: IdentityServer – IdentityResource vs. ApiResource vs. ApiScope

STEP #16: Exploring the User Interface

When we added the user interface earlier, you might have noticed that it contains quite an extensive set of pages. As a newcomer, this can feel a bit overwhelming.

Let’s clarify the key files and folders in the Pages folder:

Folders:

Account
Handles user login, logout, account creation, and access denied errors.
Ciba
Implements Client-Initiated Backchannel Authentication (CIBA), allowing authentication requests to be initiated on a separate device.
Consent
Displays the consent screen where users approve or deny client applications access to their data.
Device
Handles the device authorization flow, used for input-constrained devices like smart TVs.
Diagnostics
Displays the current user’s claims and session information, useful for debugging.
ExternalLogin
Manages authentication with external identity providers such as Google or Azure AD.
Grants
Allows users to view and revoke permissions they have granted to client applications.
HomeError
Displays an error page when something goes wrong.
Redirect
Handles post-authentication redirects back to the client application.
ServerSideSessions
Provides a UI for managing server-side sessions when that feature is enabled.
Shared
Contains shared layout files, navigation, and validation components used across all pages.

Key Files:

SecurityHeadersAttribute.cs
Adds security headers to responses to help prevent common web vulnerabilities.
Telemetry.cs
Integrates OpenTelemetry for distributed tracing and metrics.

STEP #17: Additional Configuration Options

The included user interface pages are great. They provide a solid starting point for implementing your own custom OpenID Connect identity solution.

However, I want to point out that there are several configuration files scattered throughout the Pages folder that are easy to overlook:

AccountLoginLoginOptions.cs
AccountLogoutLogoutOptions.cs
CibaConsentOptions.cs
ConsentConsentOptions.cs
DeviceDeviceOptions.cs

It’s worth being aware of these files when customizing the user experience. In particular, LoginOptions.cs and LogoutOptions.cs are important to review early on, as they control fundamental authentication behaviors like allowing local login, enabling remember me, and handling post-logout redirects.

Frequently Asked Questions

Below are questions I did not cover in detail above, but that are important for a production-ready setup.

Do I need Data Protection for IdentityServer in production?

IdentityServer relies on ASP.NET Core Data Protection to protect cookies and protocol state. In production, persist the key ring outside the app instance. Otherwise, restarts, redeployments, or scaling out can invalidate cookies and break sign-in flows. Use a shared key store per environment and protect keys at rest.

UseStaticFiles vs MapStaticAssets: which one should I use?

If you target .NET 9 or later and your assets are known at build or publish time, prefer app.MapStaticAssets(). It is optimized for static web assets and provides benefits such as build-time compression and fingerprinting that UseStaticFiles does not offer.

If you serve files added at runtime (for example, user uploads) or files from other locations or providers, you still need app.UseStaticFiles(). For more details, see Static files in ASP.NET Core.

How do I run Duende IdentityServer in Docker containers?

Running IdentityServer in containers is very achievable, but you need to get a few fundamentals right. The most common pitfalls are networking and URLs, especially the difference between container-to-container communication (internal DNS names) and browser-to-container communication (hostnames and ports), as well as correct issuer and redirect URI configuration.

I cover this end-to-end in a step-by-step series here: IdentityServer in Docker Containers.

Summary

We have now created a working Duende IdentityServer implementation from scratch. Along the way, we configured Serilog for comprehensive logging, added the IdentityServer middleware, integrated the sample user interface, and set up test users and configuration. You should now have a solid foundation for understanding how all of these pieces fit together.

The next step is to create a client application and an API that relies on this IdentityServer for authentication and authorization. However, that is beyond the scope of this blog post. In the meantime, I encourage you to explore the sample UI code, experiment with the configuration in Config.cs, and review the various options files we discussed.

If you want to learn more about OpenID Connect, OAuth, or Duende IdentityServer, check out my OpenID Connect for Developers tutorial and my workshops:

Feel free to reach out if you have any questions or want to discuss how to build a robust authentication solution for your organization.

Feedback, comments, found any bugs?

Have feedback, spotted an issue, or found a typo? I’d love to hear from you! Your input helps improve the content and assists other developers who might encounter similar challenges. Get in touch!

All code for this tutorial is available on GitHub.

BFF in ASP.NET Core #7 - Introducing the Duende BFF Library

Tore Nestenius — Wed, 20 Aug 2025 00:00:00 GMT

In the previous blog posts in this series, we built our own Backend-for-Frontend (BFF) implementation in ASP.NET Core from scratch. Now, you might be wondering about how much effort it would take to replace our custom solution with the Duende BFF Security Framework? In this post, we’ll walk through that migration process and see just how straightforward it can be.

This is a big topic, so I’ve split it into multiple parts. You can jump to the section you need, but for background and context, it’s best to start here:

Part 1 - Introduction
Part 2 - Introducing the Backend-for-Frontend (BFF) pattern
Part 3 - Securing the Cookie Session
Part 4 - Implementing a BFF in ASP.NET Core
Part 5 - Automatic Token Renewal
Part 6 - Securing the BFF using CORS
Part 7 - Introducing the Duende BFF Library

Introducing the Duende BFF Library

The Duende BFF (Backend For Frontend) Security Framework is a comprehensive ASP.NET Core library that’s designed to secure browser-based applications like SPAs and Blazor apps by implementing the modern Backend-For-Frontend security pattern.

This library provides a robust set of features that address the common security challenges of modern web applications:

This library provides features like:

Token extraction attack protection - keeps access tokens server-side
Built-in CSRF attack protection through custom header requirements
Server-side OAuth 2.0 support with complete protocol handling
Multi-frontend support
API reverse proxy capabilities for secure external API access
Server-side session state management
Back-channel logout support
Blazor authentication state management
And more…

Duende BFF Licensing

Before implementing Duende BFF in your project, it’s important to understand the licensing model. While the library is free for development, testing, and personal projects, production usage may require a commercial license depending on your business size and requirements. Duende Software also offers community editions and startup-friendly options.

For the most current licensing information and to determine what applies to your specific situation, visit the Duende Software website directly.

The Duende BFF Source Code

You can find all the code for this tutorial series on GitHub, with the specific implementation for this post located in the 5-Duende.BFF project folder. Having the complete working example will help you to follow along and see the migration in action.

Important: You’ll need to provide your own OIDC authentication server details to run the sample code successfully.

Adding the Duende.BFF NuGet Package

The first step in is to add the following NuGet packages:

The Duende.BFF.Yarp package is needed in order to support remote APIs.

Removing Duende.AccessTokenManagement.OpenIdConnect

Our previous implementation used the Duende.AccessTokenManagement.OpenIdConnect package for automatic token management. However, since Duende.BFF already includes this dependency; we need to remove the standalone package from our project to prevent library version conflicts.

Important: Failing to remove this package may cause your application to fail during startup due to conflicting dependencies.

Configuring Duende.BFF

Now we need to register the Duende BFF services in our Program class:

// Add Duende BFF services builder.Services.AddBff()
.AddRemoteApis();

The AddBff() method registers the core BFF framework services (authentication, session management, local API protection), while AddRemoteApis() adds the additional services needed specifically for proxying requests to external APIs using YARP (Yet Another Reverse Proxy).

Next, we add the BFF middleware to our request pipeline. Note the specific order of these middleware components. UseBff() must be placed before UseAuthorization() because anti-forgery validation needs to happen before authorization decisions are made:

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

The app.UseBff() middleware automatically handles X-CSRF header validation. The middleware examines endpoint metadata to identify BFF-protected endpoints and validates that requests include the required X-CSRF header.

Since this protection is now handled by the framework, we can now remove our custom CSRF component:

// Remove this code 
app.CheckForCsrfHeader();

The BFF Management Endpoints

In our custom BFF implementation, we created a BffController class that handled login, logout, and session information retrieval. With Duende BFF, we can remove this entire controller since the framework provides these endpoints automatically.

To enable the BFF management endpoints, add this single line to your request pipeline:

// Map BFF endpoints 
app.MapBffManagementEndpoints();

This automatically exposes the following endpoints:

/bff/login
Initiates the login process.
/bff/silent-login
/bff/silent-login-callback
Support silent login flows.
/bff/logout
Initiates the logout process.
/bff/user
Returns information about the currently logged-in user.
/bff/backchannel
Handles OpenID Connect back-channel logout notifications.
/bff/diagnostics
Exposes diagnostics information (enabled only in development environments by default)

Mapping of Local APIs

Our existing local API in the ApiController can remain largely unchanged. We simply need to add the [BffApi] attribute to the controller class:

[ApiController] 
[Route("api")] 
[Authorize] 
[BffApi] 
public class ApiController : ControllerBase 
{
    ...
}

The [BffApi] attribute automatically applies the security measures recommended for browser-based applications following the BFF pattern. This includes CSRF protection and proper token handling.

Mapping of Remote APIs

In our custom implementation, we handled remote API proxying through a method in the ApiController. This approach required manually proxying requests to /bff/remote while replacing the session cookie with the appropriate access token.

As you experienced firsthand, implementing this correctly involved quite a bit of complex code. Duende BFF simplifies this dramatically by leveraging Microsoft’s YARP (Yet Another Reverse Proxy) library to do this work for us.

This means we can replace our entire custom action method with this single line of code (in Program.cs):

app.MapRemoteBffApiEndpoint("/api/remote",
            new Uri("https://www.secure.nu/tokenapi/gettime"))
			.WithAccessToken(RequiredTokenType.User);

his approach significantly reduces the complexity and code required to implement secure remote API access, while also providing a high-performance proxy solution that would be difficult to implement ourselves.

Tweaking the frontend

We’ll make some small adjustments to the frontend by adding new buttons to the homepage that demonstrate the various BFF endpoints:

Each button serves a specific testing purpose:

Get User
Calls the /bff/user endpoint to retrieve data about the currently logged-in user and session information.
Diagnostics
Calls the /bff/diagnostics endpoint, which returns current user details and client access token for testing purposes.
Get Identity
Calls a custom /user/GetIdentity endpoint that we’ve implemented in a custom UserController class. This endpoint returns the raw ClaimsPrincipal authentication properties, cookie details, and session cookie information as seen by ASP.NET Core controllers. Since ASP.NET Core sometimes abstracts or transforms authentication data, this endpoint helps verify your assumptions during development.

Signing Out

To implement proper logout functionality, we need to make some minor adjustments to our application. Simply calling the /bff/logout endpoint isn’t sufficient. We must include the internal session ID as a query string parameter for security purposes.

This session ID requirement acts as CSRF protection for the logout endpoint, preventing attackers from maliciously signing users out of their sessions.

The logout URL with the session ID looks like this:
/bff/logout?sid=xxxxxxxxxSessionIDxxxxxxxxxxxx

The easiest way to obtain this complete logout URL is through the /bff/user endpoint, which includes a claim named bff:logout_url that contains the properly formatted logout URL.

You can find all the implementation details for this logout flow in the site.js JavaScript file.

Testing our implementation

With all these changes in place, we can verify that our application works exactly as before. Users can sign in to the BFF application and receive an authentication session cookie, maintaining the same user experience while benefiting from the enhanced security and simplified codebase.

The Journey from DIY to Production-Ready

Migrating from our custom BFF implementation to Duende BFF proved to be remarkably straightforward. The transition required only a few minor adjustments to achieve the same functionality we had before, but with significant improvements under the hood.

The YARP integration particularly stands out, providing a much more robust and modern approach to remote API proxying compared to our prototype implementation. This upgrade gives us enterprise-grade reliability with minimal effort.

While there are many additional configuration options and advanced features we could explore, those topics will have to wait for future blog posts or webinars. The foundation we’ve built here provides a solid starting point for most applications.

Summary

Throughout this blog series, we’ve built a comprehensive BFF implementation in ASP.NET Core and secured it using industry best practices. Our goal has been to provide you with a deep understanding of how a BFF works under the hood, whether you plan to build your own solution or leverage an existing one.

Existing BFF Solutions:

**Duende.BFF
**Enterprise-grade solution from the creators of Duende IdentityServer
OidcProxy.Net
A developer-friendly, open-source identity-aware reverse proxy built on YARP that requires minimal configuration to implement the BFF pattern for SPAs.

We’ve demonstrated that the BFF pattern is one of the most effective ways to harden SPA applications. It allows us to:

Leverage the browser’s built-in security features to their fullest potential
Keep sensitive authentication tokens and session data away from the frontend
Implement robust CORS protection against cross-origin attacks
Maintain a secure authentication flow without exposing credentials to JavaScript

The key insight: Understanding how a BFF works under the hood is essential for using it securely and effectively, regardless of whether you build your own or adopt an existing solution.

With the foundation we’ve built in this series, you’re now equipped to make informed decisions about BFF implementation and configuration in your own applications.

I hope you’ve found this blog post series valuable! Please share your thoughts and experiences as you implement these patterns in your own projects.

What Did We Not Cover?

What we’ve built so far is a solid starting point for a custom BFF setup. However, there are several important production considerations you may want to explore further:

Reducing Authentication Cookie Size
To keep your authentication cookies small and secure, consider using a cookie session store. Large cookies can impact performance and hit browser size limits. See this blog post for more details: Improving ASP.NET Core Security By Putting Your Cookies On A Diet.
Logging and Monitoring
Proper logging is essential for troubleshooting and security auditing, but was not included in this walkthrough. Consider implementing structured logging for authentication events, failed requests, and security-related activities.
Data Protection Configuration
ASP.NET Core uses the Data Protection API for critical functions like cookie encryption. In production environments, you’ll want to configure this properly! I’ve covered it in the following posts: Persisting the ASP.NET Core Data Protection Key Ring in Azure Key Vault
and Introducing the Data Protection API Key Ring Debugger.
Forwarded Headers Middleware
If your application runs behind a reverse proxy or terminates HTTPS at a load balancer or gateway, you’ll need to configure forwarded headers correctly to maintain security. For more details, see my blog post:
Configuring ASP.NET Core Forwarded Headers Middleware.
Using YARP as a Reverse Proxy
In our examples, we hand-coded the proxy logic between the browser and remote APIs. For a more flexible and high-performance solution, consider using YARP (Yet Another Reverse Proxy). YARP Documentation
Content Security Policy (CSP)
With the BFF pattern, you can implement a strict Content Security Policy since the frontend is served from your backend. This provides powerful protection against XSS attacks and reduces the risk of compromised browsers executing malicious scripts.
Shared Storage for Scaling
When scaling your BFF across multiple instances, you’ll need shared storage (like Redis or SQL Server) for access tokens and session data to prevent race conditions, especially with Identity Providers that don’t allow refresh token reuse.
Authorization Policies
Authorization Policies Beyond authentication (which the BFF manages for us), you’ll need to implement proper authorization using ASP.NET Core’s policy-based authorization system to control what authenticated users can access.

Resources

YARP (Yet Another Reverse Proxy)
BFF Session Management Endpoints
Implement BFF with ASP.NET Core and IdentityServer
Duende BFF Logout Endpoint
Set up a SPA+BFF with ASP.NET Core and Angular in 3 steps (.NET 8)

Ready to take your web security skills to the next level? If you want to deepen your understanding of web application security, OpenID Connect, or authentication in .NET, explore the comprehensive workshops available.

These hands-on, practical workshops are specifically designed for developers working with real-world applications and modern identity solutions. You’ll gain actionable knowledge that you can immediately apply to secure your own projects.

Feedback, comments, found any bugs?

Have feedback, spotted an issue, or found a typo? I’d love to hear from you! Your input helps improve the content and assists other developers who might encounter similar challenges. Get in touch!

BFF in ASP.NET Core #6 - Securing our BFF with CORS

Tore Nestenius — Thu, 14 Aug 2025 00:00:00 GMT

In this post, we take the next step in securing our Backend-for-Frontend (BFF) by adding robust Cross-Origin Resource Sharing (CORS) protection. CORS is essential for defending against a range of cross-origin attacks, and implementing it correctly is crucial for any application that handles sensitive data.

We’ll explore the types of attacks that CORS helps prevent, walk through its practical implementation in ASP.NET Core, and explain why proper configuration matters.

This is a big topic, so I’ve split it into multiple parts. You can jump to the section you need, but for background and context, it’s best to start here:

Part 1 - Introduction
Part 2 - Introducing the Backend-for-Frontend (BFF) pattern
Part 3 - Securing the Cookie Session
Part 4 - Implementing a BFF in ASP.NET Core
Part 5 - Automatic Token Renewal
Part 6 - Securing the BFF using CORS
Part 7 - Introducing the Duende BFF Library

The Attack Scenario: When Your Site Has an Evil Twin

Let’s set the stage:

Our real site is localtest.me. This is the domain we want to protect. But attackers are always looking for new tricks. Imagine someone copies your site and hosts it on a different domain, like yoggle.com. Or, even worse, they manage to run a version on a subdomain, like hacked.localtest.me, after a subdomain takeover attack.

The attacker’s goal is simple. By tweaking the JavaScript on these fake sites, they try to send requests to your real BFF component at localtest.me. With the credentials flag set in their fetch calls, they attempt to include any cookies your users might have for your site:

fetch('https://localtest.me:5001/api/local', {
    method: 'GET',
    credentials: 'include',
})

Why use localtest.me and yoggle.com?

Both domains resolve to 127.0.0.1, making them perfect for local development and testing. Using realistic domain names helps us reason about cross-origin behavior more accurately compared to using just localhost. Tools like mkcert let us easily create trusted certificates for HTTPS, taking our setup even closer to production.

Why not use localhost?

Browsers treat localhost as “potentially trustworthy” according to the Secure Contexts specification. This means features that normally require HTTPS on regular domains may still work over plain HTTP on localhost. While this is convenient for development, it can hide security issues that will only appear in production. For more accurate security testing, it is better to use domains like localtest.me that behave more like real-world environments.

Preventing Unauthorized Cross-Origin API Requests

Our current Backend-for-Frontend (BFF) setup already applies strong protections to the session cookie:

HttpOnly
SameSite=Strict or Lax
A prefixed cookie name (__Host-)

The __Host- prefix is especially valuable. It enforces that the cookie can only be set from the root path (/), that it must be sent over HTTPS, and it cannot include a Domain attribute. This prevents the cookie from being shared with subdomains, even if one is compromised.

However, one risk still remains: a user could be tricked into visiting a fake version of your site, perhaps through a phishing email or a malicious link. That fake site could then attempt to send requests to your real BFF using the user’s browser. If the target origin matches and your CORS settings are too permissive, the browser may include the session cookie in these requests.

To better demonstrate this risk, let’s temporarily set the SameSite value to None in our cookie configuration:

.AddCookie("cookie", options =>
{
    options.Cookie.Name = "__Host-AuthCookie";
    options.Cookie.SameSite = SameSiteMode.None;
    ...
});

We set SameSite to None here so that browser SameSite restrictions do not interfere with our demonstration.

Exploring the Cross-Origin Request Problem

The attacker has deployed two copies of our site: one on a different domain (yoogle.com) and one on a subdomain (hacked.localtest.me). These malicious sites attempt to send requests to our legitimate BFF component on localtest.me, and if cookies are present in the browser, they may be included in the request.

At first glance, everything appears secure. By default, the browser blocks the response due to missing CORS headers. In the browser console, we see an error like this:

And in the application, we observe a failed request:

This looks reassuring, right? The request failed, so we must be protected!

But here’s the critical issue: we’re not actually safe.

Confused about CORS?

My Web Security Fundamentals workshop covers the complete spectrum of web vulnerabilities and defenses, from XSS and CSRF to secure authentication patterns and coding practices.

The Problem with Simple CORS Requests

When JavaScript makes a cross-origin request, the browser applies CORS rules to decide whether the response should be passed back to the page.

By enabling CORS with strict settings, we can control:

Which origins are allowed to call our API
Which HTTP methods and headers can be used

This helps prevent other sites from making unauthorized API requests using JavaScript.

We might think this keeps us safe! After all, the application shows an error, and the request “failed,” right?

But if you inspect the traffic using a tool like Fiddler, you’ll see that the request was still sent to our BFF:

So what’s going on?

To understand this, we need to stop thinking of ‘the page’ as one thing. The web page and the browser that displays it are actually separate components working together, like this:

When JavaScript on a page makes a request, it doesn’t directly contact the server. Instead, it asks the browser to make the request on its behalf.

In our case, the backend did not return the expected CORS headers, so the browser blocks the response from being delivered to the page. But the request still reaches the server, and it includes your cookies.

That means the backend might still process the action, even if the page does not receive the result.

So yes, the request “failed” in the browser, but not on the network. That is the real problem.

What is the solution?

Preflight CORS Requests

In the previous example, the browser still sent the real request, even though the page was blocked from seeing the response. This can be a problem if the request changes state on the server.

To prevent the browser from sending the actual request right away, we can make it ask for permission first. This is done using a preflight request. The browser first sends a separate OPTIONS request to check if the real request is allowed.

In some cases, the browser will do this automatically based on the method or headers in the request. But if we want to force the browser to always perform a preflight, we can add a custom header:

fetch('https://localtest.me:5001/api/remote', {
    method: 'GET',
    credentials: 'include',
    headers: {
        'X-CSRF': '1'
    }
})

The X-CSRF header can be any custom name. The important part is that it makes the request a non-simple request (one that requires special CORS handling), which causes the browser to run a preflight check before sending it.

A preflight request looks like this:

OPTIONS https://localtest.me:5001/api/local HTTP/1.1
Host: localtest.me:5001
Access-Control-Request-Method: GET
Access-Control-Request-Headers: x-csrf
Origin: https://hacked.localtest.me:7001
Referer: https://hacked.localtest.me:7001/

If yoogle.com is a trusted domain, then the server should respond to the browser’s preflight request with the following headers to allow the actual request:

HTTP/1.1 204 No Content
Date: Wed, 25 Jun 2025 13:06:44 GMT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: X-CSRF,Content-Type
Access-Control-Allow-Methods: GET
Access-Control-Allow-Origin: https://yoogle.com:6001
Access-Control-Max-Age: 600

This response tells the browser that requests from https://yoogle.com:6001 are allowed, including credentials and the specified headers and methods. The Access-Control-Max-Age header allows the result to be cached for 10 minutes.

Important

Preflight requests only happen for cross-origin requests. For same-origin requests, the browser skips this step and sends the request directly.

Enabling CORS in our BFF

To allow the backend to respond to the browser’s CORS preflight requests, we need to enable and configure CORS in our application.

Start by adding this configuration to your Program.cs file:

builder.Services.AddCors(options =>
{
    options.AddDefaultPolicy(policy =>
    {
        policy.WithOrigins("https://localtest.me:5001")
              .AllowAnyMethod()
              .WithHeaders("X-CSRF", "Content-Type")
              .AllowCredentials()
              // Optionally cache for 10 minutes
              .SetPreflightMaxAge(TimeSpan.FromMinutes(10));
    });
});

Then we add the CORS middleware to the request pipeline:

...
app.UseRouting();

app.UseCors();

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

Order matters here. The CORS middleware must be placed after UseRouting() but before UseAuthentication() and UseAuthorization() to work correctly.

With this configuration in place, our BFF now has proper CORS protection. The browser will only allow cross-origin requests from trusted origins, and only when they follow the rules we have defined.

Improving the CORS Protection

Adding the X-CSRF header in frontend requests forces the browser to send a preflight request. But what if an attacker simply skips that header? In that case, the browser might treat the request as a simple request and send it directly, without a preflight.

To handle this vulnerability, we need to ensure that the backend enforces the presence of the X-CSRF header. If the header is missing or invalid, then the request gets rejected before any processing occurs.

We can implement this protection using a custom middleware component:

public class CsrfHeaderMiddleware
{
    private readonly RequestDelegate _next;

    public CsrfHeaderMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var path = context.Request.Path.Value?.ToLowerInvariant();

        // Check if request is for protected endpoints
        if (ShouldCheckCsrfHeader(path))
        {
            var csrfHeader = context.Request.Headers["X-CSRF"]
                                            .FirstOrDefault();

            if (csrfHeader != "1")
            {
                context.Response.StatusCode = 401;
                await context.Response.WriteAsync(
                              "Missing or invalid X-CSRF header");
                return;
            }
        }

        await _next(context);
    }

    private static bool ShouldCheckCsrfHeader(string? path)
    {
        if (string.IsNullOrEmpty(path))
            return false;

        return path.StartsWith("/bff/session") || path.StartsWith("/api/");
    }
}

To make it easier to add to the pipeline, we also define this extension method:

public static class CsrfHeaderMiddlewareExtensions
{
    public static IApplicationBuilder CheckForCsrfHeader(
                              this IApplicationBuilder builder)
    {
        return builder.UseMiddleware<CsrfHeaderMiddleware>();
    }
}

Then, in your application setup, add it after the CORS middleware:

app.UseCors(); 
app.CheckForCsrfHeader();

This middleware answers a critical question:

If this header is missing, is it really coming from one of our legitimate clients?

It provides the backend with a simple yet effective way to block requests that bypass the expected request flow. This protection also guards against simple HTML forms posting directly to your application, since forms cannot set custom headers.

Removing the CORS Credentials Option

If your frontend only needs to communicate with your own BFF (same-origin requests), consider removing the credentials: ‘include’ option from your fetch calls altogether.

Why does this matter?

By default, browsers automatically include cookies in same-origin requests. However, without the credentials option, cookies will never be sent on cross-origin requests, even if the backend is misconfigured to allow them.

This creates an additional layer of defense-in-depth. If a cross-origin request is made accidentally or maliciously, it will be unauthenticated, and your backend will most likely reject it.

It’s a simple yet effective way to reduce the risk of cross-origin data leakage and provides protection against configuration mistakes.

fetch('https://localtest.me:5001/api/remote', {
    method: 'GET',     
	headers: {         
	    'X-CSRF': '1'
	}
})

What’s next?

In this post, we secured our BFF with robust CORS protection and custom middleware to defend against cross-origin attacks. In the next and final post of this series, we’ll replace our custom BFF implementation with Duende.BFF.

to BFF in ASP.NET Core #7 – Introducing the Duende BFF Library

BFF in ASP.NET Core #5 - Automatic Token Renewal

Tore Nestenius — Wed, 06 Aug 2025 00:00:00 GMT

Nobody wants to sign in every hour. Yet that’s exactly what happens when access tokens expire in applications without proper token management. The good news? We can fix this by implementing automatic token renewal in our BFF!

This is a big topic, so I’ve split it into multiple parts. You can jump to the section you need, but for background and context, it’s best to start here:

Part 1 - Introduction
Part 2 - Introducing the Backend-for-Frontend (BFF) pattern
Part 3 - Securing the Cookie Session
Part 4 - Implementing a BFF in ASP.NET Core
Part 5 - Automatic Token Renewal
Part 6 - Securing the BFF using CORS
Part 7 - Introducing the Duende BFF Library

The Problem

Our implementation works perfectly for the lifetime of an access token. The catch? That lifetime varies widely based on your identity provider configuration: some use 10-minute tokens for high security, others allow 24 hours or more. Regardless of the duration, when tokens expire, users lose access to remote APIs even though their BFF session remains active. Let’s fix that.

How do we get a new access token?

Introducing the Refresh Token

When we authenticate with OpenID Connect, we can request a special long-lived credential called a refresh token. This token has one job: obtaining new access tokens when the current one expires.

Here’s how it works:

During initial login, we request the offline_access scope.
The identity provider returns three tokens: ID token, access token, and refresh token.
When the access token expires, we use the refresh token to request a fresh set of tokens.
The user can continue accessing the remote APIs without knowing this happened.

The refresh token typically lasts much longer (days or weeks) and can be used multiple times to keep renewing access tokens until the user explicitly logs out, or when the refresh token itself expires.

The refresh token can either be a one-time token that can only be used once (called a rotating refresh token), or a reusable token that can be used multiple times until it expires. With rotating refresh tokens, each time you use the refresh token to get a new access token, you also receive a new refresh token. This approach provides better security since a compromised refresh token can only be used once.

The Token Renewal Implementation Challenge

By requesting the offline_access scope during authentication, we will receive a refresh token. However, ASP.NET Core has no built-in mechanism to use it when access tokens expire automatically.

When an access token expires, the remote API responds with:

HTTP/1.1 401 Unauthorized
Server: Microsoft-IIS/10.0
WWW-Authenticate: Bearer error="invalid_token", error_description="The token expired at '06/24/2025 09:24:46'"
Date: Tue, 24 Jun 2025 09:24:47 GMT
Content-Length: 0

So how do we implement automatic renewal? Let’s explore that next.

Using the Duende Access Token Management Library

Instead of building token renewal from scratch, we’ll use the production-tested Duende.AccessTokenManagement library. This open-source solution handles the complex security requirements of token management, including automatic renewal with refresh tokens for us.

Why Not Build It Yourself?

Token management looks simple but hides serious pitfalls:

Race conditions when multiple requests need renewal simultaneously.
Token storage conflicts in multi-instance deployments.
Security vulnerabilities from improper token handling.

Real-world incidents have occurred where custom implementations accidentally exposed tokens to wrong users or leaked credentials through caching errors. These aren’t theoretical risks, instead they’re expensive mistakes that happen when security-critical code is built in-house without extensive testing.

About the Library

The library delivers production-tested stability backed by excellent documentation and support:

By using this battle-tested library, you get reliable token management without the risk and maintenance burdens of custom code.

Implementing the Access Token Management Library

Once the package is installed, integrating the library into your application requires just a few lines of code. Register and configure it in your Program.cs:

Once the package is installed, integrating the library into your application requires just a few lines of code. Register and configure it in your Program.cs:

builder.Services.AddOpenIdConnectAccessTokenManagement(o =>
{
    o.RefreshBeforeExpiration = TimeSpan.FromSeconds(15);
});

The RefreshBeforeExpiration setting controls when the library proactively refreshes tokens before they expire. In this example, we’re using 15 seconds to demonstrate the renewal process in action. For production applications, you’ll typically want a longer buffer, anywhere from 1-5 minutes depending on your API response time requirements and token lifetime.

Updating the ApiController

Now we need to update the ApiController to use the access token management service. Start by injecting the service through the constructor:

public class ApiController : ControllerBase
{
    private readonly HttpClient _httpClient;
    private readonly IUserTokenManagementService _tokenManagement;

    public ApiController(HttpClient httpClient,
                         IUserTokenManagementService tokenManagement)
    {
        _httpClient = httpClient;
        _tokenManagement = tokenManagement;
    }
    ...
}

Next, replace the existing logic that retrieves the access token with the new implementation using the token management service:

// Get access token using Duende Access Token Management
// (handles automatic refresh)
var tokenResult = await _tokenManagement.GetAccessTokenAsync(User);
if (tokenResult.IsError)
{
    return StatusCode((int)HttpStatusCode.Unauthorized, new
    {
        error = "Failed to get access token",
        details = $"Token error: {tokenResult.Error}",
        statusCode = 401,
        tokenManagementUsed = true
    });
}

// Create HTTP request with Authorization header
var url = "https://www.secure.nu/tokenapi/gettime";
var request = new HttpRequestMessage(HttpMethod.Get, url);

var authHeader = new AuthenticationHeaderValue("Bearer",
                                               tokenResult.AccessToken);
request.Headers.Authorization = authHeader;

Using the Access Token Management library

With the setup complete, you can now run the application and make calls to the remote API. In Fiddler, you will see that each request from the browser to the BFF triggers a corresponding call to the remote API, as expected.

When the access token is about to expire or has become invalid, the Access Token Management library automatically requests a new token from the authorization server (in this case, Duende IdentityServer). This process is handled entirely by the library, so you do not need to write any manual logic for handling token expiration or refresh.

You can observe this behavior in the server logs when a token refresh occurs:

trce: Duende.UserAccessAccessTokenManagementService
      Starting user token acquisition
dbug: Duende.UserAccessAccessTokenManagementService
      Token for user Bob Smith will be refreshed.
      Expiration: 06/24/2025 11:37:41 +00:00,
      ForceRenewal:False
trce: Duende.UserTokenEndpointService
      Refreshing access token using refresh token:
      hash=blsquoA1xJkBGCxQ2kqM4w
dbug: Duende.UserTokenEndpointService
      Sending Refresh token request to:
      https://identityservice.secure.nu/connect/token
dbug: Duende.UserTokenEndpointService
      Access Token of type Bearer refreshed with expiration:
      06/24/2025 11:38:12 +00:00
trce: Duende.UserAccessAccessTokenManagementService
      Returning refreshed token for user: Bob Smith
info: System.Net.Http.HttpClient.Default.LogicalHandler
      Start processing HTTP request
      GET https://www.secure.nu/tokenapi/gettime
info: System.Net.Http.HttpClient.Default.ClientHandler
      Sending HTTP request
      GET https://www.secure.nu/tokenapi/gettime
info: System.Net.Http.HttpClient.Default.ClientHandler
      Received HTTP response headers after 42.5267ms - 200
info: System.Net.Http.HttpClient.Default.LogicalHandler
      End processing HTTP request after 47.1398ms - 200

Summary

Adding automatic access token renewal to the BFF was straightforward, thanks to the Access Token Management library. You can review the complete implementation for this step in the 3-TokenRenewal project. The full source code for the entire series is available on GitHub.

This enhancement ensures users stay authenticated without interruption, while the library handles all the token management behind the scenes.

What’s next?

With OpenID Connect and automatic access token management in place, our BFF setup is nearly complete. However, before it is truly production-ready, there are still important security measures to address.

The next step is to implement proper CORS (Cross-Origin Resource Sharing) support to help protect your application from cross-origin threats. This will be the focus of the next blog post. Stay tuned!

To BFF in ASP.NET Core #6 – Securing our BFF with CORS.

BFF in ASP.NET Core #4 - Implementing a BFF from scratch

Tore Nestenius — Wed, 30 Jul 2025 00:00:00 GMT

In this blog post, we’ll implement a minimal yet complete Backend-for-Frontend (BFF) in ASP.NET Core. By starting with a simple foundation and adding features incrementally, you’ll learn not just how to build a BFF, but why each component matters for securing modern web applications.

This is a big topic, so I’ve split it into multiple parts. You can jump to the section you need, but for background and context, it’s best to start here:

Part 1 - Introduction
Part 2 - Introducing the Backend-for-Frontend (BFF) pattern
Part 3 - Securing the Cookie Session
Part 4 - Implementing a BFF in ASP.NET Core
Part 5 - Automatic Token Renewal
Part 6 - Securing the BFF using CORS
Part 7 - Introducing the Duende BFF Library

The Application Architecture

To demonstrate the BFF pattern in action, we’ll build a minimal application with two main components: a jQuery-based web page for the frontend and an ASP.NET Core backend that implements the BFF logic. This simple setup lets us focus on understanding how the core BFF components work together.

The overall architecture looks like this:

BFF API Endpoints

Our BFF exposes five HTTP endpoints that demonstrate the key responsibilities of the pattern:

Authentication Endpoints

/bff/login
Initiates the authentication flow by redirecting the user to the identity provider.
/bff/logout
Terminates the user’s session both locally and at the identity provider.
/bff/session
Returns the current user’s authentication state, including claims and tokens.
⚠️ Demo endpoint only - production applications should never expose tokens to the browser.

API Endpoints

/api/local
A protected endpoint within the BFF that requires authentication via the session cookie.
/api/remote
This proxies requests to an external API, automatically attaching the user’s access token from the server-side session.

A typical BFF supports two types of APIs:

Local APIs that terminate within the BFF (authenticated via the session cookie).
Remote APIs that are proxied to external services (where the BFF exchanges the session cookie for an access token).

From the frontend’s perspective, both types are secured using the same session cookie.

The WEB UI

Our demo interface provides a simple way to interact with all the BFF endpoints:

Each button demonstrates a core BFF capability:

Login
Initiates authentication with the identity provider.
Get Session
Displays the current authentication state, including claims and tokens. Note: This is for demonstration purposes only; tokens should never be exposed in production environments.
Logout
Ends the session and clears authentication.
Call Local API
Calls the /api/local endpoint, demonstrating cookie-based authentication for BFF-hosted APIs.
Call Remote API
Calls the /api/remote endpoint, demonstrating how the BFF proxies requests with proper token handling.

The response area shows the raw API responses, making it easy to understand what data flows through each part of the system.

Getting the BFF Source Code

All code for this tutorial is available on GitHub:

The solution contains multiple projects showing the BFF evolution:

1-StartCode
Basic application with simple cookie authentication
2-OpenIDConnect
Adds real identity provider integration
(Additional stages covered in subsequent sections)

In the application, we have added the following two controller classes:

BffController
It implements the logic for Login, LogOut, and Get Session.
ApiController
This class implements the local and remote API endpoints.

Starting Point: Project 1-StartCode

When you run the first project, you’ll find a minimal setup with two key ASP.NET Core controllers:

BffController

Handles authentication operations:

/bff/login - Currently uses a fixed test user
/bff/logout - Clears the authentication cookie
/bff/session - Returns current user information

ApiController

Implements the API endpoints:

/api/local - A simple authenticated endpoint
/api/remote - Placeholder for external API calls

This starting point utilizes basic cookie authentication with a hardcoded user, providing a foundation to build upon before adding OpenID Connect integration.

You can run 1-StartCode immediately to see basic BFF functionality in action. The local API endpoints work, but you’ll notice two limitations:

No real authentication or OpenID-Connect support (just a fixed test user).
The remote API call fails (it needs an access token we don’t have yet).

Adding OpenID Connect support

Now let’s upgrade our basic BFF to use real authentication. This transformation requires five specific changes:

Add NuGet packages
Install the OpenID Connect authentication middleware.
Configure OpenID Connect
Set up the authentication handler in Program.cs.
Update the challenge scheme
Change from “Cookies” to “oidc”.
Remove the fixed user logic
Delete the SignInUser method from BffController.
Update logout behavior
Ensure it signs out from both the BFF and the identity provider.

Important: You’ll need to update the OpenID Connect settings with your own identity provider configuration, including client registration details and endpoints.

After these changes (available in the 2-OpenIDConnect project), your BFF now:

Authenticates users through a real identity provider
Stores tokens securely in server-side session
Provides cookie-based authentication for the frontend
Proxies remote API calls with proper access tokens
Handles complete logout flow (local + identity provider)

This is a fully functional BFF implementation with all the core security features in place.

Want to dive deeper into OpenID Connect and OAuth?

If you’re interested in mastering these technologies, I also teach a hands-on workshop: Introduction to OpenID Connect and OAuth. It’s a great way to build a solid understanding and get practical experience with real-world scenarios.

Supporting Remote APIs

One of the most valuable features of the BFF pattern is its secure handling of external API calls. Unlike traditional SPAs, which must manage tokens in JavaScript, the BFF acts as a secure reverse proxy, keeping sensitive credentials out of the browser.

Here’s the complete flow when calling an external API:

Frontend → BFF:
The browser sends a request to /api/remote with the session cookie.
Cookie → Token:
The BFF validates the cookie and retrieves the stored access token.
BFF → API:
The BFF forwards the request to the external API with the access token.
API → Frontend:
The response flows back through the BFF to the browser.

Why This Matters

This design achieves three critical goals:

Security: Browser cookies never leave your domain.
Simplicity: The frontend only deals with one authentication mechanism.
Control: All token management happens on server-side.

The remote API only recognizes valid access tokens, whereas the browser only recognizes session cookies. This clean separation of concerns is what makes the BFF pattern so effective for modern web applications.

Won’t This Add Latency?

A common concern is whether adding a proxy layer impacts performance. In practice, the overhead is minimal because:

Connection reuse:
With HTTP/2, the browser maintains a single multiplexed connection to your BFF, which is often faster than opening multiple connections to different APIs.
Negligible overhead:
Most API calls already traverse multiple layers (load balancers, API gateways, reverse proxies). One more hop rarely makes a difference. Often, one or more database requests are involved, and these take significantly more time than a single network hop.
Caching opportunities:
The BFF can implement caching for frequently accessed data.

The security benefits far outweigh any minimal latency:

API abstraction:
Internal service architecture stays hidden from external clients.
Centralized security:
Rate limiting, authentication, and monitoring all happen in one place.
Attack surface reduction:
Only your BFF needs to be hardened against internet-facing threats.
Token isolation:
Compromised browser code can never access your API tokens.

What’s next?

We now have a working BFF with all the core features. To make it production-ready, we’ll need:

Automatic token renewal (Part 5) - Keep users signed in when access tokens expire.
Enhanced security (Part 6) - CORS configuration and additional protections.

Try the code and experiment with different scenarios to see the BFF pattern in action!
To BFF in ASP.NET Core #5 – Automatic Token Renewal.

BFF in ASP.NET Core #3 - The BFF Pattern Explained

Tore Nestenius — Wed, 23 Jul 2025 00:00:00 GMT

The BFF pattern eliminates many SPA security risks, but it introduces a new critical component: the session cookie. This cookie becomes the key to your user’s authentication. If it’s not properly secured, you’ve simply moved the vulnerability from JavaScript tokens to HTTP cookies.

This post shows you how to properly secure the session cookie using HTTPS, HttpOnly flags, SameSite protection, and other essential browser security features.

This is a big topic, so I’ve split it into multiple parts. You can jump to the section you need, but for background and context, it’s best to start here:

Part 1 - Introduction
Part 2 - Introducing the Backend-for-Frontend (BFF) pattern
Part 3 - Securing the Cookie Session
Part 4 - Implementing a BFF in ASP.NET Core
Part 5 - Automatic Token Renewal
Part 6 - Securing the BFF using CORS
Part 7 - Introducing the Duende BFF Library

Securing the Communication with the BFF

The session cookie is the cornerstone of BFF security. After a user logs in, this cookie becomes their digital identity, included with every request from the browser to the BFF.

Here’s where the BFF pattern really shines: when you handle OIDC directly in the browser, you can’t leverage most of the browser’s built-in security mechanisms.

With the BFF approach, we can finally use the full arsenal of browser security features. Session cookies unlock HttpOnly protection, SameSite controls, Secure flags, and host prefixes. When properly configured, these create multiple layers of protection that can withstand sophisticated attacks and pass rigorous penetration tests.

But how do we protect this cookie and the communication channel?

Using HTTPS

HTTPS isn’t optional in modern web applications. It’s the foundation that makes everything else possible. Without HTTPS, your BFF implementation will encounter immediate problems: OpenID Connect flows may fail, browsers will block security-critical cookies, and essential security features will not activate.

The HttpOnly flag is your first line of defense against JavaScript-based attacks. This simple yet powerful attribute instructs the browser to block JavaScript access to the authentication cookie, preventing malicious scripts from stealing the session cookie.

Set-Cookie: .AspNetCore.cookie=CfDJ8IgPXE...; HttpOnly

This protection is critical because it directly addresses cross-site scripting (XSS), one of the most common attack vectors. Even if an attacker manages to inject malicious JavaScript into your application, they cannot access or steal the session cookie. It’s one simple change, with a big impact!

Important: HttpOnly doesn’t block legitimate functionality. Cookies marked with HttpOnly are still automatically included in same-origin requests made by JavaScript (such as fetch or XMLHttpRequest calls), ensuring your application functions normally while remaining protected.

Adding this flag helps reduce the risk of stolen session cookies through injected scripts.

The Secure attribute adds another essential layer of protection by ensuring your session cookie only travels over encrypted HTTPS connections. This simple flag prevents the cookie from ever being sent over via plain HTTP, even by mistake.

Set-Cookie: .AspNetCore.cookie=CfDJ8IgPXE...; HttpOnly; Secure

This protection is vital for preventing man-in-the-middle attacks. Without the Secure flag, if any part of your application accidentally makes an HTTP request, the session cookie could be transmitted in plain text, potentially exposing it to network eavesdroppers.

Browsers prevent setting Secure cookies on HTTP sites, with one exception: localhost during local development. Since production BFF implementations run on public HTTPS endpoints, this development exception doesn’t affect your security posture.

Before SameSite protection existed, browsers had a dangerous default behavior where they would send cookies with every request to your domain, regardless of where that request originated. This meant malicious websites could trigger requests to your application and your users’ cookies would be automatically included.

This creates a serious vulnerability. Imagine a user is logged into their banking application in one tab, then clicks a malicious link in an email. That malicious site can send hidden requests to the bank’s website, and because the browser automatically includes the user’s session cookie, the bank sees these requests as legitimate. This is the foundation of Cross-Site Request Forgery (CSRF) attacks.

The SameSite attribute solves this problem by giving you control over when cookies are included in cross-site requests. Modern browsers increasingly require this attribute, and it should be part of every cookie configuration.

The attribute accepts three values:

Strict
The cookie is only sent with requests originating from the same site. This provides maximum protection but can impact user experience. Users clicking links from external sites (emails, social media) will appear logged out and need to sign in again.
Lax (default)
The cookie is sent for “safe” top-level navigation (like clicking a link) but blocked for potentially dangerous requests (like form submissions from other sites). This prevents most CSRF attacks while maintaining good usability.
**None
**The cookie is sent with all cross-site requests. This requires the Secure flag and should only be used if your application specifically needs cross-site cookie access. Most BFF implementations should avoid this setting. This is how cookies behaved before the SameSite attribute was introduced.

For BFF implementations, use SameSite=Strict if your application can handle users appearing logged out when arriving from external links. Otherwise, SameSite=Lax provides excellent protection with better usability.

Here’s what a secure session cookie might look like:

Set-Cookie: .AspNetCore.cookie=CfDJ8IgPXE...; HttpOnly; Secure; SameSite=Strict

By default, session cookies are included in all same-site requests. But what exactly qualifies as “same-site”? The answer reveals a significant security blind spot that many developers overlook.

Understanding the Same-Site Boundary

In browser security, “same-site” is much broader than most people expect. All of these domains are considered part of the same site:

example**.com**
login.example**.com**
api.example**.com**
test.login.example**.com**

This broad scope applies to all top-level domains, including country-code domains. For example, these are all considered the same site:

example.co.uk
login.example.co.uk
api.example.co.uk
test.login.example.co.uk

The Public Suffix List helps browsers decide if two domains belong to the same site or not.

The Subdomain Takeover Risk

This broad cookie scope creates a vulnerability: if an attacker compromises any subdomain (such as test.api.example.com), they can potentially access cookies intended for your main application. This is known as a subdomain takeover attack.

Fortunately, modern browsers provide a powerful solution: prefixed cookie names. The __Host- prefix enables the strongest origin-binding protection available, transforming your cookie from site-scoped to origin-scoped security.

Here’s how it works: when a cookie name starts with __Host-, browsers automatically activate special security restrictions. This isn’t just a naming convention; instead, it’s a security feature built into the browser itself.

Here is an example:

Set-Cookie: __Host-SessionCookie=XXXXX; HttpOnly; Secure; Path=/; SameSite=Strict

Requirements for __Host- cookies:

No Domain attribute - This locks the cookie to the exact hostname that set it
Path must be / - Ensures the cookie applies to the entire origin
Must include Secure flag - Enforces HTTPS-only transmission

With the __Host- prefix, a cookie set by https://example.com becomes completely isolated. It will never be sent to:

login.example.com
api.example.com
test.login.example.com

This simple naming convention eliminates the risk of subdomain takeover entirely. Your session cookie is now bound to the exact origin that created it, not just the broader site boundary.

Additional Security Enhancements

Once the core cookie protections are in place, you can further strengthen your BFF security with these measures:

CORS
Cross-Origin Resource Sharing (CORS) controls which origins can communicate with your BFF. We’ll explore this in detail in Part 6, as it deserves dedicated coverage for BFF implementations.
Content Security Policy (CSP)
CSP controls which resources the browser can load, providing strong protection against XSS attacks. Learn more about CSP.
Essential Security Headers
Modern browsers support several security headers that significantly improve your application’s defense:
- Strict-Transport-Security
  This header enforces HTTPS connections and prevents protocol downgrade attacks by instructing browsers to only communicate with your server over secure connections. Once set, browsers will automatically redirect HTTP requests to HTTPS and reject connections with invalid certificates.
- X-Content-Type-Options: nosniff
  Prevents browsers from MIME-sniffing responses away from the declared content type. Read more about the X-Content-Type-Options header.
- X-Frame-Options
  Protects against clickjacking by controlling whether your site can be embedded in frames.
- Referrer-Policy
  Controls the amount of referrer information included with requests. Read more about the Referrer-Policy header.

While configuring these headers is beyond the scope of this blog post series, they are an important part of a strong BFF security setup. In ASP.NET Core, most can be added using middleware in the request pipeline.

Summary

Securing the session cookie is critical to the BFF pattern’s success. In this post, we’ve covered the essential layers of protection:

Communication Security

HTTPS - The foundation that enables all other security features

HttpOnly - Blocks JavaScript access, preventing XSS token theft
Secure - Ensures cookies only travel over encrypted HTTPS connections
SameSite - Controls cross-site request behavior (use Strict or Lax)
Path=/ - Applies the cookie to your entire application
__Host- prefix - Locks the cookie to your exact origin, preventing subdomain attacks

Want to Dive Deeper?

These cookie protections are part of a broader security strategy. My Web Security Fundamentals workshop covers the complete spectrum of web vulnerabilities and defenses, from XSS and CSRF to secure authentication patterns and coding practices.

What’s Next

Now that we understand how to secure the session cookie properly, it’s time to put this knowledge into practice. Part 4 walks through implementing a BFF in ASP.NET Core, showing you exactly how to configure all the security features we’ve covered.

To BFF in ASP.NET Core #4 – Implementing a BFF from scratch.

BFF in ASP.NET Core #2 - The BFF Pattern Explained

Tore Nestenius — Thu, 17 Jul 2025 00:00:00 GMT

How do you secure a Single-Page Application without storing tokens in the browser? The answer lies in the Backend-for-Frontend (BFF) pattern. This architectural approach shifts authentication complexity to the backend, keeping your frontend simple and secure. Let’s explore how it works and why it’s become the gold standard for SPA security.

This is a big topic, so I’ve split it into multiple parts. You can jump to the section you need, but for background and context, it’s best to start with part 1:

Part 1 - Introduction
Part 2 - Introducing the Backend-for-Frontend (BFF) pattern
Part 3 - Securing the Cookie Session
Part 4 - Implementing a BFF in ASP.NET Core
Part 5 - Automatic Token Renewal
Part 6 - Securing the BFF using CORS
Part 7 - Introducing the Duende BFF Library

The Backend-for-Frontend Pattern

Security experts and major OIDC providers increasingly recommend moving authentication out of the browser entirely. This approach is called the Backend-for-Frontend (BFF) pattern, and it’s becoming the standard for securing modern SPAs.

This is a prescription these days, not just an optional pattern that exists out there. The security landscape has evolved to the point where storing tokens in the browser is no longer considered acceptable for production applications, making the BFF pattern essential rather than optional.

The core idea is straightforward: instead of your React, Angular, or Blazor app handling OpenID Connect flows and managing tokens, a dedicated backend component (the BFF) takes complete responsibility for authentication.

Here’s how it works:

The browser communicates with the BFF using a simple session cookie.
The BFF handles all OpenID Connect interactions with your identity provider.
The BFF stores tokens securely on the server side.
When your SPA needs data, the BFF calls backend APIs using the stored tokens.

The BFF acts as an authentication proxy: your frontend gets the user experience of being “logged in” through a session cookie, while the BFF handles all the complex OIDC flows and token management behind the scenes.

Where does the BFF pattern come from?

The Backend-for-Frontend pattern didn’t start as a security solution. It originally emerged from the microservices world to solve a different problem: how to efficiently serve multiple types of client applications.

The core idea was simple but powerful: instead of forcing mobile apps, web browsers, and desktop applications to all use the same generic API, we can create dedicated backend services tailored to each client’s specific needs.

This approach solved several problems:

Optimized data delivery:
Each client received exactly the data format and structure it needed.
Simplified frontends:
No more complex data transformation logic in client applications.
Clear separation of concerns:
Backend teams could optimize for specific client requirements.

This made the frontend simpler and more efficient, since it received exactly the data and structure it needed. It also helped separate any security concerns between different parts of the system.

This evolution makes perfect sense: if we can create specialized backends to meet data needs, why not create specialized backends to meet security needs? The BFF is like having your authentication specialist that lets your React, Angular, or Blazor app focus purely on user experience.

The Backend-For-Frontend Pattern in Practice

Now let’s see how this works in practice. With the BFF pattern, we move all authentication logic out of the frontend. Your SPA no longer needs to handle OIDC flows or manage tokens. Instead, a dedicated backend component manages all security concerns.

The BFF acts as a confidential client to your identity provider, which means it can securely store client secrets and handle the full OIDC flow. Your browser never sees tokens or handles the complex token exchange protocols.

This architectural shift unlocks powerful security advantages:

Session Cookie Security:
The browser communicates with the BFF using a simple session cookie. This allows us to leverage strong, battle-tested browser security features, like:
- HTTP-only cookies - JavaScript cannot access the session cookie.
- SameSite protection - Prevents cross-site request forgery attacks.
- Secure flag - Ensures cookies only travel over HTTPS.
Reduced Attack Surface:
With tokens stored securely on the server, we eliminate major attack vectors, like:
No XSS token theft - Malicious scripts can’t steal what isn’t there.
No token exposure - Browser developer tools won’t reveal sensitive tokens.
Simplified frontend - Less security-critical code to review and maintain.

This creates a robust and yet simpler security perimeter that’s difficult to breach:

The Duende BFF Framework

Before we dive into building our own implementation, it’s worth mentioning that a production-ready solution already exists, and that’s the Duende.BFF security framework. This commercial product, developed by the team behind Duende IdentityServer, is currently the only dedicated BFF framework available for ASP.NET Core that I am aware of.

So why build our own instead of using Duende.BFF?

There are three key reasons:

Learning and Understanding:
Building a BFF from scratch reveals the underlying security principles and common pitfalls that frameworks often abstract away. When you understand how authentication flows work at a fundamental level, you can make better architectural decisions and troubleshoot issues more effectively.
Practical Knowledge:
Working through the implementation details gives you the confidence to customize, extend, or debug BFF behavior in your own applications. This hands-on experience is invaluable when dealing with security-critical code.
Universal Skills:
Understanding the fundamentals gives you confidence and knowledge when working with any BFF implementation, whether it’s an existing solution like Duende.BFF or a custom implementation that you build yourself.

For production applications, definitely consider Duende.BFF if it fits your budget and requirements. For learning and understanding the core concepts, building your own implementation provides deeper insights.

For a comprehensive introduction to the Duende BFF framework, I recommend watching ‘Token Management: Applying the Duende Backend for Frontend (BFF) Security Framework’ by Erwin van der Valk.

What’s Inside a BFF?

Now that we understand why BFF is valuable, let’s look under the hood. A typical BFF implementation consists of two core components that work together to provide secure and seamless authentication:

Session Management:
This component handles the complete OpenID Connect authentication flow with your identity provider. It manages the login process, issues secure session cookies to the browser, and stores access and refresh tokens safely on the server. Think of it as your authentication orchestrator; it keeps users logged in and handles token lifecycle management entirely behind the scenes.
API Proxy:
This component acts as a secure gateway between your SPA and backend APIs. When your frontend makes API calls, the proxy uses the session cookie to identify the user, retrieves the appropriate access token from storage, and forwards the request to the target API with proper authentication headers attached.

These two components work together seamlessly, allowing the session management component to establish trust with the browser, while the API proxy leverages that trust to make authenticated calls on the user’s behalf.

What’s next

Now that we understand how BFF works architecturally, it’s time to dive into the security details. In Part 3, we’ll explore how to properly secure the session cookie that travels between your browser and BFF.

To BFF in ASP.NET Core #3 – The BFF Pattern Explained.

Implementing BFF Pattern in ASP.NET Core for SPAs

Tore Nestenius — Wed, 09 Jul 2025 00:00:00 GMT

This multi-part blog series will show you how to implement secure authentication for Single-Page Applications using the Backend-for-Frontend (BFF) pattern with ASP.NET Core.

We’ll explore why handling OpenID Connect directly in SPAs creates security risks, then build a complete BFF implementation that eliminates browser token storage and follows OAuth 2.0 best practices. In short, it will help you to build secure applications with less complexity in the frontend!

As this is a big topic, I’m planning to release a new post in this series approximately once a week, with each part building on the previous one. You can jump to the section you need, but for background and context, it’s best to start here:

The Problem with Direct OIDC in SPAs

In my work, I regularly encounter development teams implementing OpenID Connect authentication directly in their Single-Page Applications. The typical flow looks like this:

The browser-based frontend authenticates directly with the OIDC provider.
The OIDC JavaScript library stores the received tokens in the browser.
Uses them to call backend APIs.

This approach seems straightforward, but it introduces significant security risks and complexity.

**so what exactly are these risks?
**

The Problem With Tokens In the Browser

Let’s explore the key problems with this approach:

Protecting the tokens:
Storing tokens (access token, ID token, and refresh token) in the browser puts them at risk of theft through cross-site scripting (XSS) attacks or malicious third-party scripts. For example, a compromised browser extension could easily access tokens stored in localStorage, giving attackers full access to your APIs.
Increased attack surface:
Adding OpenID Connect support directly to your SPA means handling tokens, redirects, and callbacks in JavaScript. This prevents you from utilizing secure browser features, such as HTTP-only cookies and same-site protections, while significantly increasing your application’s attack surface.
Added Complexity:
OpenID Connect and token handling introduce a lot of complexity to your frontend. Even with libraries, you need to understand token flows, configure edge cases like renewal and error handling, and manage logout scenarios. This increases security-critical code that requires careful writing, testing, and review.
Using a trusted library:
Searching npm for “oidc” returns thousands of JavaScript libraries, but only a small number are certified by the OpenID Foundation. Using an unmaintained or insecure library can introduce subtle bugs or serious security vulnerabilities.

These problems are well-documented in the security community. Rather than diving deep into every detail, I recommend these excellent talks that explain the issues clearly:

Using the BFF pattern to secure SPA and Blazor Applications
alert‘OAuth 2 0’; // The impact of XSS on OAuth 2.0 in SPAs
Web Security and BFF with Philippe De Ryck
Philippe is one of the authors of the OAuth 2.0 for Browser-Based Applications guide.

Curious about OpenID-Connect?
Head over to my OpenID Connect for Developers article for an accessible, in-depth introduction to OpenID Connect for developers.

The Impact of Stolen Tokens

The impact extends far beyond browser access. Once an attacker exfiltrates these tokens, they gain portable, offline access to your APIs. The stolen access token can be used from any client application or system. The attacker doesn’t need continued access to the victim’s browser.

This means they can:

Call your APIs from their own systems.
Use automated tools to exploit the token.
Continue accessing resources until the token expires (potentially hours or days later).
Potentially use the token across multiple applications if it has a broad scope.

Refresh tokens make this even worse. If a refresh token is also stolen, the attacker can:

Generate new access tokens indefinitely.
Maintain persistent access even after the original access token expires.
Continue the attack for weeks or months until the refresh token is revoked or expired.

This transforms a temporary browser compromise into a persistent, distributed security threat that’s much harder to detect and contain.

The Solution: the Backend-for-Frontend (BFF) Pattern

So what’s the better approach? Instead of handling authentication directly in the SPA, we move all token management to the backend and use a simple session cookie for communication between the frontend and backend.

This creates a much cleaner and more secure architecture:

Key principles of the BFF approach:

No tokens in the browser:
Eliminating tokens from the frontend removes a major security risk and reduces complexity. No more worrying about XSS attacks stealing your tokens or trying to implement secure storage in JavaScript.
Use the browser’s built-in security features:
Without frontend token management, you can fully utilize HTTP-only cookies, same-site protection, and secure flags. All of these are battle-tested browser security mechanisms that work without additional configuration.
Keep the frontend simple and focused:
Your SPA can concentrate on what it does best: user interface and experience. Authentication complexity stays in the backend where it belongs.
Centralize trust and session handling in the backend:
The backend handles the OpenID Connect flow, manages sessions, and securely stores tokens. This makes logging, monitoring, and auditing much easier.
Reducing complexity:
Moving the authentication into the backend reduces the number of moving parts in the frontend and cuts down the attack surface. This also means fewer security concerns for frontend developers to worry about.

This approach is called the Backend-for-Frontend (BFF) pattern. It’s not a new concept, but it’s particularly effective for securing modern SPAs.

What you’ll learn: By the end of this series, you’ll have a solid starter implementation that eliminates browser token storage, leverages HTTP-only cookies, and centralizes authentication in ASP.NET Core, giving you a strong foundation for your own BFF journey.

Official Recommendation

The BFF pattern isn’t just a theoretical improvement; it’s recognized as the current best practice by the OAuth working group. The IETF draft specification for OAuth 2.0 for Browser-Based Apps explicitly states:

“This architecture is strongly recommended for business applications, sensitive applications, and applications that handle personal data.”

This official endorsement reinforces the message that moving authentication to the backend is more than a matter of convenience; it is also about meeting established security standards suited to modern web applications in today’s world.

Why I Created This Series

I wrote this series for two main reasons, both rooted in real-world experience.

First, I wanted to deepen my own understanding of BFF implementations. Reading about authentication patterns is one thing, but actually building, testing, and troubleshooting them reveals nuances you can’t get from just theory alone.

Second, I needed a comprehensive, working example for the security workshops I run with development teams. When I’m explaining secure SPA architectures, nothing beats having actual ASP.NET Core code that teams can examine, run, and adapt to their own projects.

You can learn more about these security workshops here.

These workshops focus on practical security implementation: the kind of hands-on knowledge that helps teams avoid common pitfalls and build more secure applications from the start.

Ready for the Deep Dive?

This deep dive follows that same hands-on philosophy - we’ll build a complete BFF implementation together so you can see exactly how it works under the hood (and hopefully with fewer headaches, too!).

In Part 2, we’ll explore exactly how the BFF pattern works and why it solves these security challenges.

To part 2 - The BFF Pattern Explained.

How to Use KurrentDB for Event Sourcing in C# on Azure

Tore Nestenius — Tue, 13 May 2025 00:00:00 GMT

In this blog post, you will learn how to deploy a test instance of KurrentDB to Azure and access it from a console application in .NET.

Why did I write this blog post?

While updating my DDD, CQRS, and Event Sourcing in .NET training course to the latest version of .NET and C#, I also decided to switch from EventStoreDB to KurrentDB for the course’s hands-on exercises.
Previously, we ran EventStoreDB locally, but during our corporate training sessions, we found that installing software onto student machines often gets restricted. To work around this, I chose to host KurrentDB in Azure, with a separate instance running for each student.

As usual, I thought to share my learning with you! This blog post walks through how I deployed KurrentDB to Azure and connected to it from C#.

What is KurrentDB?

KurrentDB is the new name for EventStoreDB, one of the first purpose-built databases for event sourcing. It was created by Greg Young, who also introduced the Command and Query Responsibility Segregation (CQRS) pattern.

KurrentDB stores every change to your data as an event. Instead of just saving the latest state, it records what happened, when, and why. This approach lets you rebuild the full history of your system, create audit logs, replay behavior, or build read models that are tailored for specific needs.

The KurrentDB database is open-source, written in C#, and available on GitHub. The source code is well written and makes for an interesting codebase to review and explore. I find that reading and exploring real-world projects is a great way to pick up new techniques and ideas.

Is KurrentDB a new database?

No, it was originally released in 2012 and is one of the few purpose-built event store databases available. It has had many years to mature and evolve. If you’re curious about how it works internally, check out this talk by Gregory Young: How an EventStore actually works.

What is Event Sourcing?

Event sourcing is a way of storing data by recording each change as an event. Instead of saving the latest state, you store the full history of everything that happened. This makes it easy to rebuild states, trace changes, and support things like auditing and custom views.

For example, in a shopping cart, you can store each action as it happens:

To get to the current state, you would load all events and apply them one by one to the shopping cart. A big benefit of event sourcing, is that it makes it much easier to understand how and why something changed within a system, which is great for troubleshooting.

Deploying KurrentDB to Azure

There are several ways to host KurrentDB in Azure, but my requirements were:

Each student should get their own dedicated instance.
It must be easy to deploy and clean up using a PowerShell script.
No need to deal with https (TLS) certificates.
It should be cost-effective.

Given these needs, I decided to use Azure Container Instances. KurrentDB is available as a container image, and you can find the details in their installation guide.

Azure Container Instances are suitable for testing KurrentDB, but should not be used for production. ACI enforces certain restrictions that limit some features KurrentDB relies on to run properly.

KurrentDB and the network

Before we deploy KurrentDB, we need to understand its network configuration. By default, KurrentDB listens to two network ports:

Port 1113

KurrentDB uses port 1113 for internal TCP traffic between cluster nodes, such as replication and gossip.

In our case, since we’re running a single-node setup, we don’t need to worry about port 1113. This port is used only for internal node-to-node communication and should never be exposed to the public internet or client applications.

Port 2113

KurrentDB uses by default port 2113 for client communication over HTTP or HTTPS.

In this example, we expose port 2113 to the public internet. To simplify setup and avoid dealing with TLS certificates, we run KurrentDB in insecure mode by setting the KURRENTDB_INSECURE environment variable to true. This is fine for testing and development, but it should never be used in production.

Deploying KurrentDB to Azure Container Instances

For my first attempt at deploying KurrentDB as an Azure Container Instance, I used the following PowerShell script:

$containerImage = "docker.kurrent.io/kurrent-latest/kurrentdb:latest"
$ResourceGroupName = "rg-kurrenteventstore"
$containerName = "kurrentdb-attempt1"
$Location = "swedencentral"

# Create resource group if it doesn't exist
az group create --name $ResourceGroupName `
                --location $Location `

# Create Azure Container Instance
az container create `
	--resource-group $ResourceGroupName `
	--name $containerName `
	--image $containerImage `
	--ports 2113 `
	--environment-variables "KURRENTDB_INSECURE=true" `
	--cpu 1 `
	--memory 1 `
	--os-type Linux `
	--location $Location `
	--restart-policy Never `
	--dns-name-label "$containerName-$(Get-Random)" `
	--query "ipAddress.fqdn"

After running the script, we had a working KurrentDB instance deployed to the public internet, accessible on port 2113.

When navigating to the URL in your browser, you’ll see KurrentDB’s built-in web interface. This gives you a quick way to check that the instance is up and running, and allows you to explore some basic information and diagnostics like below.

Deploying multiple instances of KurrentDB

Being able to deploy an instance to Azure is awesome. However, I need a script to deploy multiple instances to Azure.

The modified script eventually became this:

$containerImage = "docker.kurrent.io/kurrent-latest/kurrentdb:latest"
$ResourceGroupName = "rg-kurrenteventstore2"
$Location = "swedencentral"

$instanceCount = 2

# Create resource group if it doesn't exist
az group create --name $ResourceGroupName `
                --location $Location `

$urls = @()

for ($i = 1; $i -le $InstanceCount; $i++)
{
    $containerName = "kurrentdb-$i"

	# Create Azure Container Instance
	$fqdn = az container create `
		--resource-group $ResourceGroupName `
		--name $containerName `
		--image $containerImage `
		--ports 2113 `
		--environment-variables "KURRENTDB_INSECURE=true" `
		--cpu 1 `
		--memory 1 `
		--os-type Linux `
		--location $Location `
		--restart-policy Never `
		--dns-name-label "$containerName-$(Get-Random)" `
		--query "ipAddress.fqdn" `
		--output tsv

	$urls = $urls + "${fqdn}:2113"

}

Write-Output "`nAll instance URLs:"
$urls

Kurrent Navigator

To manage your KurrentDB instance, you can use Kurrent Navigator. This is a standalone desktop app with a clean, modern interface for browsing events, inspecting streams, working with projections, and more. It runs on Windows, macOS, and Linux, and it is useful for both daily administration and troubleshooting.

Sending events to KurrentDB from C#

For .NET developers, KurrentDB offers an official .NET client, which is also available as a NuGet package: KurrentDB.Client. It supports both .NET Framework 4.8 and modern .NET versions. Details about how to use this package can be found in the getting started documentation.

The code below creates four events and sends it to KurrentDB:

using KurrentDB.Client;
using KurrentDB.Client.Core.Serialization;

var server = "[ServerAddress]";
var settings = KurrentDBClientSettings.Create($"esdb://{server}?tls=false");
settings.OperationOptions.ThrowOnAppendFailure = false;

await using var client = new KurrentDBClient(settings);

var events = new List<object>
{
    new NewOrderCreated
    {
        Id = Guid.NewGuid(),
        CustomerID = Guid.NewGuid(),
        SalesPersonID = Guid.NewGuid(),
        SalesPersonName = "John Doe"
    },
    new OrderCancelled
    {
        Id = Guid.NewGuid(),
        Reason = "Customer changed their mind"
    },
    new ProductAddedToOrder
    {
        Id = Guid.NewGuid(),
        ProductId = Guid.NewGuid(),
        ProductName = "Laptop",
        Quantity = 1,
        PricePerUnit = 1200.00m
    },
    new ProductRemovedFromOrder
    {
        Id = Guid.NewGuid(),
        ProductId = Guid.NewGuid()
    }
};

var streamName = "order-12345";

await AppendEventsAsync(client, streamName, events);

async Task AppendEventsAsync(KurrentDBClient client,
                              string stream,
                              List<object> events)
{
    // Map the events to KurrentDB message type.
    var messages = events
        .Select(e => Message.From(data: e,
                                  messageId: Uuid.NewUuid())).ToList();

    await client.AppendToStreamAsync(streamName: stream,
                                      messages: messages);
}

// Event definitions
public class NewOrderCreated
{
    public Guid Id { get; set; }
    public Guid CustomerID { get; set; }
    public Guid SalesPersonID { get; set; }
    public string? SalesPersonName { get; set; }
}

public class OrderCancelled
{
    public Guid Id { get; set; }
    public string? Reason { get; set; }
}

public class ProductAddedToOrder
{
    public Guid Id { get; set; }
    public Guid ProductId { get; set; }
    public string? ProductName { get; set; }
    public int Quantity { get; set; }
    public decimal PricePerUnit { get; set; }
}

public class ProductRemovedFromOrder
{
    public Guid Id { get; set; }
    public Guid ProductId { get; set; }
}

After sending the events, we can open Kurrent Navigator to view the events stored in the database:

Reading events from KurrentDB

Reading from KurrentDB is straightforward. You just need to create a client and specify the stream you want to read from, like this:

using KurrentDB.Client;
using System.Text;
using System.Text.Json;

Console.WriteLine("Reading events from KurrentDB...");

var server = "kurrentdb-2-1927695997.swedencentral.azurecontainer.io";
var settings = KurrentDBClientSettings.Create($"esdb://{server}?tls=false");
settings.OperationOptions.ThrowOnAppendFailure = false;

await using var client = new KurrentDBClient(settings);

var streamName = "order-12345";
var events = await client
    .ReadStreamAsync(Direction.Forwards, streamName, StreamPosition.Start)
    .ToListAsync();

foreach (var ev in events)
{
    var json = Encoding.UTF8.GetString(ev.Event.Data.Span);
    Console.WriteLine($"{ev.Event.EventNumber} - {json}");
}

As an output, we will get:

Reading events from KurrentDB...
0 - {"id":"0d0545fe-5242-4c06-8ad5-573cd4a89bd1",
     "customerID":"264c704d-1754-4e56-9f2a-0f8b4202a045",
     "salesPersonID":"3fa6e8f1-c114-4eea-81e0-eefa9fe2a4f4",
     "salesPersonName":"John Doe"}

1 - {"id":"b3f37164-94c6-426d-bfe2-b8a6063f37ac",
     "reason":"Customer changed their mind"}

2 - {"id":"4b391bb9-b288-4dc9-9f19-ad65dc577cad",
     "productId":"4bcb44e5-6bc6-42dd-b47c-18496a4d5380",
     "productName":"Laptop","quantity":1,"pricePerUnit":1200.00}

3 - {"id":"6f2fa70f-12ec-46e7-b715-aad3f559be32",
     "productId":"bb5147e0-5fbb-4339-88ce-1249fb002d0b"}

Summary

Writing this blog post was a great way to explore everything new from the team behind KurrentDB. I especially enjoyed trying out the Kurrent Navigator, which was completely new to me. Hosting KurrentDB in Azure using Container Instances turned out to be a smooth experience. Just keep in mind that if you’re coming from EventStoreDB, some names and behaviors have changed, which caused a few bumps along the way.

Curious about DDD, CQRS, and Event Sourcing?

If you’re interested in learning more about these concepts, I offer several training classes, including DDD, CQRS and Event Sourcing in .NET and Modern Application Architecture. You can find the full list of workshops on my training page. I also offer coaching if you’d like help working through architectural challenges.

The CQRS and Event Sourcing framework that I use in my training can be found at https://cqrs.nu. It’s a project I was part of creating. There, you’ll also find an example of how to do BDD-style testing of Event Sourced systems.

Resources

Configuring ASP.NET Core Forwarded Headers Middleware

Tore Nestenius — Thu, 10 Apr 2025 00:00:00 GMT

In my previous blog post, I explained what the Forwarded Headers Middleware does and why it matters. In this post, I will show you how to add it to your application, configure it, and point out a few common issues that can arise in configuring the forwarded headers middleware.

In this blog post:

Testing the Forwarded Headers Application
Adding the ForwardHeaders Middleware
Configuring ForwardHeadersMiddleware
ForwardHeaders Middleware in Action
Observing the Problem in the Logs
Allowed Forwarded Headers Hosts
The ASPNETCORE_FORWARDEDHEADERS_ENABLED variable
Forwarded Headers in the Cloud Debugger
Source Code
Summary

The Sample ForwardHeaders Application

Let’s start with a new ASP.NET Core project using the empty template:

Then I updated launchSettings.json to listen on ports 5000 and 5001:

"applicationUrl": "https://localhost:5001;http://localhost:5000",

After that, I replaced the default app.MapGet() with this endpoint:

app.MapGet("{**route}", async (HttpContext context,
                              IOptions<ForwardedHeadersOptions> forwardedOptions) =>
{
    var requestDetails = new
    {
        Protocol = context.Request.Protocol,
        Scheme = context.Request.Scheme,
        Path = context.Request.Path.Value,
        PathBase = context.Request.PathBase.Value,
        Host = context.Request.Host.ToString(),
        DisplayUrl = context.Request.GetDisplayUrl(),
        RemoteIpAddress = context.Connection.RemoteIpAddress?.ToString(),
        Headers = context.Request.Headers
                  .ToDictionary(h => h.Key, h => h.Value.ToString()),
        ForwardedHeaders = new
        {
            ForwardedHeaders = GetEnabledFlags(forwardedOptions.Value.ForwardedHeaders),
            AllowedHosts = forwardedOptions.Value.AllowedHosts.ToList(),
            KnownNetworks = forwardedOptions.Value.KnownNetworks
                            .Select(n => n.Prefix + "/" + n.PrefixLength)
                            .ToList(),
            KnownProxies = forwardedOptions.Value.KnownProxies
                            .Select(p => p.ToString()).ToList(),
            forwardedOptions.Value.ForwardLimit,
            forwardedOptions.Value.OriginalForHeaderName,
            forwardedOptions.Value.OriginalHostHeaderName,
            forwardedOptions.Value.OriginalProtoHeaderName,
            forwardedOptions.Value.OriginalPrefixHeaderName,
            forwardedOptions.Value.ForwardedForHeaderName,
            forwardedOptions.Value.ForwardedHostHeaderName,
            forwardedOptions.Value.ForwardedProtoHeaderName,
            forwardedOptions.Value.ForwardedPrefixHeaderName
        }
    };
    context.Response.ContentType = "application/json";
    await context.Response.WriteAsync(JsonSerializer.Serialize(requestDetails));
});

A small helper method is also added:

static List<string> GetEnabledFlags(ForwardedHeaders headers)
{
    return Enum.GetValues<ForwardedHeaders>()
    	.Where(flag => flag != ForwardedHeaders.None && headers.HasFlag(flag))
		.Select(flag => flag.ToString())         
		.ToList(); 
}

When called, the endpoint responds to any request and returns the request details as seen by ASP.NET Core. It’s a simple and effective way to inspect how the middleware works. The response also includes the current configuration for the Forwarded Headers Middleware.

Testing the Forwarded Headers Application

To test it, we can add a Visual Studio .http file like this one:

GET http://localhost:5000 HTTP/1.1 
X-Forwarded-For: 123.0.123.1 
X-Forwarded-Proto: https 
X-Forwarded-Host: nestenius.se

This lets us send requests with custom headers. To send a request to the application, you just need to start it and click the Send request link:

Since we haven’t added the Forwarded Headers middleware yet, the response will look like this:

{
  "Protocol": "HTTP/1.1",
  "Scheme": "http",
  "Path": "/",
  "PathBase": "",
  "Host": "localhost:5000",
  "DisplayUrl": "http://localhost:5000/",
  "RemoteIpAddress": "::1",
  "Headers": {
    "Host": "localhost:5000",
    "X-Forwarded-For": "123.0.123.1",
    "X-Forwarded-Proto": "https",
    "X-Forwarded-Host": "nestenius.se"
  },
  "ForwardedHeaders": {
    "ForwardedHeaders": [],
    "AllowedHosts": [],
    "KnownNetworks": [
      "127.0.0.1/8"
    ],
    "KnownProxies": [
      "::1"
    ],
    "ForwardLimit": 1,
    "OriginalForHeaderName": "X-Original-For",
    "OriginalHostHeaderName": "X-Original-Host",
    "OriginalProtoHeaderName": "X-Original-Proto",
    "OriginalPrefixHeaderName": "X-Original-Prefix",
    "ForwardedForHeaderName": "X-Forwarded-For",
    "ForwardedHostHeaderName": "X-Forwarded-Host",
    "ForwardedProtoHeaderName": "X-Forwarded-Proto",
    "ForwardedPrefixHeaderName": "X-Forwarded-Prefix"
  }
}

From this response, we can tell that the middleware either isn’t present or has chosen to ignore the request based on its current configuration. One clear sign is that none of the X-Original-* headers were added. These headers are only set when the middleware rewrites the request using the forwarded values, which didn’t happen here.

Why not use the browser?

While you can use a browser to send basic requests, it won’t let you set custom headers like X-Forwarded-For or X-Forwarded-Host. Browsers restrict which headers can be set for security reasons. That’s why tools like .http files, Bruno, or Fiddler are much more suitable for this kind of testing. Because they let you define exactly which headers to include in your request.

What about the X-Forwarded-Prefix header?

This header deserves a blog post of its own. It’s closely tied to how PathBase works in ASP.NET Core, and things can get tricky when you’re running apps behind reverse proxies. If you want to dig deeper into how PathBase works, I recommend Andrew Lock’s excellent post: Understanding PathBase in ASP.NET Core.

Adding the ForwardHeaders Middleware

To start using the middleware, you first need to add it to the start of the request pipeline:

app.UseForwardedHeaders();

But just adding it like this won’t do anything on its own. You also need to configure it. Here’s the starting point:

builder.Services.Configure<ForwardedHeadersOptions>(options => 
{     
    //TODO: Add configuration here
	... 
});

If you run the application now and send a test request, the output will look exactly the same as before. Nothing has changed yet.

Configuring ForwardHeadersMiddleware

By default, the middleware does not process any X-Forwarded-* headers. We can confirm this by checking the response, which shows an empty ForwardedHeaders list:

"ForwardedHeaders": [],

The ForwardedHeaders array is a core part of the middleware’s configuration. It lists which X-Forwarded-* headers the middleware is currently set up to process. Right now, it’s empty, so no headers will be considered or used when rewriting the request.

We need to tell the middleware which headers it should read explicitly to fix this. The available headers are:

X-Forwarded-For
X-Forwarded-Host
X-Forwarded-Proto
X-Forwarded-Prefix

Some proxies use different header names. If that’s the case, you can change the expected names using these configuration options:

ForwardedForHeaderName (Default “X-Forwarded-For”)
ForwardedHostHeaderName (Default “X-Forwarded-Host”)
ForwardedProtoHeaderName (Default “X-Forwarded-Proto”)
ForwardedPrefixHeaderName (Default “X-Forwarded-Prefix”)

To enable all four headers, configure the middleware like this:

options.ForwardedHeaders = ForwardedHeaders.XForwardedFor |
                           ForwardedHeaders.XForwardedHost |
                           ForwardedHeaders.XForwardedProto |
                           ForwardedHeaders.XForwardedPrefix;

Or simply use the shortcut:

options.ForwardedHeaders = ForwardedHeaders.All;

Both of these will enable the same functionality.

In our case, we don’t want to support the X-Forwarded-Prefix header, so we leave it out on purpose:

options.ForwardedHeaders = ForwardedHeaders.XForwardedFor |
                           ForwardedHeaders.XForwardedHost |                            
						   ForwardedHeaders.XForwardedProto;

Being explicit about which headers you want to support is a good practice.

Why do we need to configure this?

It gives you control over which headers the middleware should support and which ones to ignore. Which headers you need to support depends on the proxy that you use and how your infrastructure is set up. Not all proxies send the same headers; some may only use a subset. Being explicit helps avoid misconfigurations and improves security.

Now restart the application and send the request again. You should now see that the ForwardedHeaders array contains the expected headers:

"ForwardedHeaders": [
   "XForwardedFor",   
   "XForwardedHost",   
   "XForwardedProto" 
],

ForwardHeaders Middleware in Action

With the ForwardedHeaders option set, the middleware is now active. It will look for the headers you’ve configured and rewrite the request based on their values.

Let’s compare what the request looks like before and after enabling the middleware:

Before

{
  "Protocol": "HTTP/1.1",
  "Scheme": "http",
  "Path": "/",
  "PathBase": "",
  "Host": "localhost:5000",
  "DisplayUrl": "http://localhost:5000/",
  "RemoteIpAddress": "::1",
  "Headers": {
    "Host": "localhost:5000",
    "X-Forwarded-For": "123.0.123.1",
    "X-Forwarded-Proto": "https",
    "X-Forwarded-Host": "nestenius.se"
  },
}

After

{  
  "Protocol": "HTTP/1.1", 
  "Scheme": "https",
  "Path": "/",
  "PathBase": "",
  "Host": "nestenius.se",
  "DisplayUrl": "https://nestenius.se//",
  "RemoteIpAddress": "123.0.123.1",
  "Headers": {
    "Host": "nestenius.se",
    "X-Original-Proto": "http",    
	"X-Original-Host": "localhost:5000",    
	"X-Original-For": "[::1]:61781"
  },
}

The middleware has updated the Scheme, Host, and RemoteIpAddress fields using the values from the X-Forwarded-* headers.

At the same time, the original values have been preserved in the X-Original-* headers. This lets your application know what was received and rewritten, which is helpful for diagnostics and auditing.

ForwardHeadersMiddleware in Production

Let’s say you take the code above and deploy it to a production environment where a reverse proxy (like NGINX, Traefik, or a load balancer) sits between the users and your web application. This proxy is a separate service that forwards requests to your app and adds the appropriate X-Forwarded-* headers.

But now… it stops working. Why?

This is the setup:

The problem is that the middleware only trusts requests from known sources, meaning known proxies or networks. By default, it only trusts local addresses. If we look at the response from our application, we’ll see these two configuration settings that control this:

"KnownNetworks": [
  "127.0.0.1/8"     
],     
"KnownProxies": 
[       
  "::1"
],

This means the forwarded headers will be ignored unless the request comes from either:

An address in the 127.0.0.1/8 network range (IPv4 localhost)
The specific address ::1 (IPv6 localhost)

You might wonder why the middleware doesn’t just trust all incoming addresses. Well, that would be a security risk! If any IP could forward headers, a malicious client could spoof values like the original IP address, scheme, or host, which could then break logging, access control, or other logic that depends on those details.

How the Trust Check Works Internally

If we look at the source code of the Forwarded Headers Middleware, we find a method that decides whether the IP address of the incoming request is allowed:

private bool CheckKnownAddress(IPAddress address)
{
    if (address.IsIPv4MappedToIPv6)
    {
        var ipv4Address = address.MapToIPv4();
        if (CheckKnownAddress(ipv4Address))
        {
            return true;
        }
    }
    if (_options.KnownProxies.Contains(address))
    {
        return true;
    }
    foreach (var network in _options.KnownNetworks)
    {
        if (network.Contains(address))
        {
            return true;
        }
    }
    return false;
}

This code shows that a request is trusted if its IP address matches an entry in the KnownProxies list or falls within a configured KnownNetworks range.

Testing Without a Real Proxy

How can we test the proxy’s behavior without setting up an entire proxy environment?

One way is to fake it. You can add a simple middleware before UseForwardedHeaders that overrides the RemoteIpAddress. This lets you simulate a request coming from a specific proxy IP address. Here’s how that looks:

app.Use(async (context, next) =>
{     
    // Spoof RemoteIpAddress      
	context.Connection.RemoteIpAddress = IPAddress.Parse("10.0.0.2");     
	await next(); 
}); 

app.UseForwardedHeaders();

If you now send a test request to the application, it will ignore the X-Forwarded-* headers because the spoofed IP address (10.0.0.2) is not on the list of trusted proxies or networks.

Observing the Problem in the Logs

When the Forwarded Headers Middleware rejects a request, it will write a debug entry to the log. It can also emit warnings for other issues, such as malformed headers or configuration problems. You need to increase the log level for the middleware’s namespace to see all of these messages.

In your appsettings.json, update the logging section like this:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.AspNetCore.HttpOverrides": "Debug"
    }
  },
  "AllowedHosts": "*"
}

The key part is setting the log level for the Microsoft.AspNetCore.HttpOverrides namespace to Debug.This enables more logging from the Forwarded Headers Middleware.

Now, if we run the application with the spoofed IP address in place, we should see a message like this in the console:

dbug: Microsoft.AspNetCore.HttpOverrides.ForwardedHeadersMiddleware[1]
      Unknown proxy: 10.0.0.2:65529

This confirms that the forwarded headers were ignored because the request did not come from a trusted source.

Fixing the Unknown proxy problem

To fix the issue, we need to tell the middleware which proxies or networks we trust. In our example, the proxy uses the IP address 10.0.0.2.

We have two options:

Trust a specific proxy IP

To trust just one IP address, you can configure it like this:

options.KnownProxies.Clear(); 
options.KnownProxies.Add(IPAddress.Parse("10.0.0.2"));

First, we clear the list to remove the default entry for localhost (::1). If you’re not using localhost in production, there’s no reason to keep it trusted.

Trust a network range

If your proxy could use different IPs within a subnet, it’s better to trust a full network range:

options.KnownNetworks.Clear(); 
options.KnownNetworks.Add(new IPNetwork(IPAddress.Parse("10.0.0.0"), 24));

This allows traffic from the entire 10.0.0.0/24 range (10.0.0.0 to 10.0.0.255) to be trusted.

By adding either of these configurations, the middleware will now accept forwarded headers from your proxy at 10.0.0.2.

Restricting where these headers are accepted from really is critical. Trusting all of the sources would allow clients to spoof X-Forwarded-* headers, which could affect security, logging, or routing behavior.

Allowed Forwarded Headers Hosts

Another important part of the Forwarded Headers Middleware is how it handles the X-Forwarded-Host header.

By default, the middleware will accept any value in the X-Forwarded-Host header. This means that a client or proxy could send in any hostname, and the middleware would apply it without restrictions.

To tighten this risky behavior, you can use the AllowedHosts setting in the ForwardedHeadersOptions configuration.

options.AllowedHosts.Clear();     
options.AllowedHosts.Add("nestenius.se");

With this configuration, only forwarded requests that include X-Forwarded-Host: nestenius.se will be accepted and applied. Any other value will be ignored.

The ASPNETCORE_FORWARDEDHEADERS_ENABLED variable

If you’ve worked with ASP.NET Core in Azure App Service or Azure Container Apps, you might have encountered the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable.

This environment variable controls whether ASP.NET Core will automatically add the Forwarded Headers Middleware to your application during startup.

Like when you use the default host builder like this:

var builder = WebApplication.CreateBuilder(args);

If the ASPNETCORE_FORWARDEDHEADERS_ENABLED is set to true, ASP.NET Core will automatically call UseForwardedHeaders() behind the scenes. You don’t have to add it manually to the middleware pipeline.

This behavior is implemented in a component called ForwardedHeadersStartupFilter (source code).

Okay, so let’s explore this next!

Testing ASPNETCORE_FORWARDEDHEADERS_ENABLED

We will remove the manual middleware setup from the application to test this feature.
Comment out these two lines:

//builder.Services.Configure<ForwardedHeadersOptions>(options => 
//{
//    //TODO: Add configuration here... 
//}); 

//app.UseForwardedHeaders();

If you send a test request with X-Forwarded-* headers, they should be ignored. This is to be expected, since the middleware is no longer active.

Enabling the Middleware via Environment Variable

Next, let’s enable it using the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable. The easiest way to do that is by adding it to your launchSettings.json:

...
  "https": {
    "commandName": "Project",
    "dotnetRunMessages": true,
    "launchBrowser": true,
    "applicationUrl": "https://localhost:5001;http://localhost:5000",
    "environmentVariables": {
      "ASPNETCORE_ENVIRONMENT": "Development",
      "ASPNETCORE_FORWARDEDHEADERS_ENABLED": "true"
    }
  }
...

The FORWARDEDHEADERS_ENABLED setting

If you’d prefer not to use environment variables, you can enable the Forwarded Headers Middleware by setting the FORWARDEDHEADERS_ENABLED flag to true in your appsettings.json:

{   
  ...   
  "FORWARDEDHEADERS_ENABLED": "true" 
}

Why Spoofing the IP No Longer Works

If you now try to spoof the remote IP address with a middleware like this:

app.Use(async (context, next) => {
    // Spoof RemoteIpAddress      
	context.Connection.RemoteIpAddress = IPAddress.Parse("10.0.0.2");     
	
	await next(); 
});

…it won’t work as expected.

The Forwarded Headers Middleware is already executed before this custom middleware. When you enable it using the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable, it’s added automatically at the very start of the pipeline by the internal ForwardedHeadersStartupFilter.

By the time your spoofing code runs, the middleware has already processed the request using the original RemoteIpAddress. So, changing it afterward has no effect. The forwarded headers will be ignored if the request appears to come from an untrusted IP (like ::1 or 127.0.0.1), and you won’t be able to simulate a proxy this way.

Custom Configuration with FORWARDEDHEADERS_ENABLED

When the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable is set to true, or the FORWARDEDHEADERS_ENABLED setting is enabled in your configuration, the Forwarded Headers Middleware is automatically added at the beginning of the request pipeline.

By default, this middleware uses a built-in configuration that:

Processes the X-Forwarded-For and X-Forwarded-Proto headers
Clears the list of trusted proxies and networks (meaning none are trusted)

This behavior comes from the internal ForwardedHeadersOptionsSetup class, which you can find here: ForwardedHeadersOptionsSetup.

Overriding the Default Configuration

To override this behavior, you can manually configure the options in your Program class:

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.All;
    options.KnownProxies.Clear();
    options.KnownProxies.Add(IPAddress.Parse("10.0.0.2"));
});

Using appsettings.json

You can also use appsettings.json to configure the middleware:

"ForwardedHeaders": {
  "ForwardedHeaders": "XForwardedFor,XForwardedHost,XForwardedProto",
  "ForwardLimit": 1,
  "RequireHeaderSymmetry": true,
  "KnownProxies": [
    "::1"
  ],
  "KnownNetworks": [
    "127.0.0.1/8"
  ],
  "AllowedHosts": [
    "nestenius.se"
  ]
}

To apply this configuration, you still need to bind it in code using:

builder.Services.Configure<ForwardedHeadersOptions>
            (builder.Configuration.GetSection("ForwardedHeaders"));

Without this line, the settings from appsettings.json will be ignored, and the middleware will fall back to its built-in defaults.

Forwarded Headers in the Cloud Debugger

The Cloud Debugger is the perfect tool for exploring how forwarded headers are used in practice, especially in environments like Azure App Services or Azure Container Apps.

The Cloud Debugger is an open-source tool I created using ASP.NET Core 9. It’s designed to help developers, architects, and DevOps teams inspect, explore, and debug HTTP requests and Azure-specific behaviors in live cloud deployments.

You can deploy it directly to Azure as an App Service or Container App. Once it’s running, it provides a browser-based interface with several built-in tools to inspect HTTP headers, understand how forwarded headers are handled, and explore its middleware configurations tools.

Source Code

You can find the source code related to this blog post on GitHub.

Summary

Writing this blog post has been a deep and practical journey into the world of proxies, forwarded headers, and how ASP.NET Core handles these scenarios under the hood.

We started with a minimal app to explore how the middleware works in a controlled environment. Then, we stepped through configuration options, common pitfalls, and production considerations like trusted proxies and forwarded host validation. We also looked at how to test proxy scenarios locally, how logging can help when things don’t behave as expected, and what happens when you enable the middleware using the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable.

Even though we covered a lot, there are still more advanced topics to explore! Topics like support for multiple proxy layers, deeper integration with Kubernetes ingress controllers, and the details of how PathBase actually interacts with X-Forwarded-Prefix.

If you’re deploying applications behind a reverse proxy or load balancer, you can consider getting familiar with this middleware as time well spent!

And don’t forget, if you want to explore how Azure handles forwarded headers in real-world environments, check out the open-source Cloud Debugger. It’s a practical tool for testing, learning, and debugging how ASP.NET Core behaves when it’s deployed behind Azure front ends.

Resources

Exploring the Forwarded Headers Middleware in ASP.NET Core

Tore Nestenius — Wed, 22 Jan 2025 00:00:00 GMT

Proxies are vital for load balancing and security, but they obscure the actual client IP, scheme, and domain, causing broken links, inaccurate logging, and other headaches. In this post, we’ll look at how ASP.NET Core’s Forwarded Headers Middleware restores these details so your services behave as though they’re directly on the public internet.

What is the Forwarded Headers Middleware?

In ASP.NET Core, requests travel through a pipeline made of various middleware components. The Forwarded Headers Middleware is one such component that often comes pre-configured (or can be easily enabled) to handle forwarded headers from proxies. It’s typically placed among the first modules in the pipeline, as shown below:

What problem does the Forwarded Headers Middleware solve?

In many scenarios, our services and applications are deployed behind a proxy server, which may serve various roles, such as:

Load balancer
Web Application Firewall (WAF)
Reverse proxy
Content cache
TLS Termination
…

The example below shows three service instances behind a proxy, acting as a load balancer.

The general problem is that the details about the original request are lost as it passes through the proxy.

In other scenarios, a single proxy might manage traffic for multiple domain names, and the services need to identify the original request to return the correct content to the caller.

Making ASP.NET Core Services Proxy-Aware

The goal is to make the internal services act as though they are directly accessible on the public internet, even though they are behind a proxy.

To solve this, we somehow need to:

Recognize the public URL that the user accessed instead of the internal network address.
Identify the original client IP address rather than the IP address of the proxy.
Determine the scheme of the original request (HTTP or HTTPS).

As shown below, we want the application in service1 to believe it received a request to https://tn-data.se rather than http://service1.

Let’s get a bit more technical

Let’s dive a bit deeper into the technical details. Imagine a setup with a proxy sitting between the client and the service:

How can we make Service1 behave as if it received a request from IP 193.8.1.12 to https://tn-data.se instead of IP 10.0.0.1 to http://service1?

Introducing the X-Forwarded Headers

The first step is configuring the proxy to add a set of headers to the outgoing request describing the original request received by the proxy.

The X-Forwarded-* headers are special HTTP headers that help servers understand where a request came from when it passes through intermediaries like proxies or load balancers. They provide essential details such as the original client’s IP address, the protocol used, and the host requested.

Proxies can add these headers to the request, informing the service about the originating IP, scheme, and host.

Let’s explore how we handle this in ASP.NET Core next.

ASP.NET Core and the X-Forwarded Headers

The Forwarded Headers Middleware is responsible for rewriting the request when these headers are present in the incoming request.

Using the details from the above example, here’s what happens to the request as it passes through the middleware:

Steps taken:

The middleware adds X-Original-* headers to the request, containing details about the current request.
It then rewrites the request based on the information found in the X-Forwarded-* headers.

Forwarded Headers in Azure Container Apps

To observe these headers in action, we can deploy my open-source Cloud Debugger tool as an Azure Container App. This tool allows us to inspect the request before and after this middleware has processed it.

For example, in the image above:

The request scheme has been updated from HTTP to HTTPS.
The sender’s IP address has changed from ::ffff:100.100.0.60 (a local IPv6 Azure address) to 193.150.241.131 (my computer’s public IP address).
The ::ffff:x.x.x.x format is an IPv6 representation of an IPv4 address, mapping it into the IPv6 space.

This shows how the middleware reconstructs the original request context using the X-Forwarded-* headers.

In the cloud debugger for Azure, we also get this nice overview of the headers:

Here, two X-Forwarded-* headers are received, and two corresponding X-Original-* headers are created with the updated information.

Upskill With Me: Courses, Workshops & Training

Want to sharpen your skills and make the most of your professional development program? I offer a range of workshop courses and coaching services for individuals and teams! Click the links or the button to find out more. If you have any questions, I’m happy to help! Find Out More

What About Security?

The Forwarded Headers Middleware offers several ways to validate and control how X-Forwarded-* headers are processed. Because blindly trusting them can be risky. Attackers or misconfigured proxies might send bogus headers, leading to incorrect IP addresses, spoofed schemes, and other vulnerabilities. In a future post, we’ll explore best practices to secure and configure these headers properly, including limiting trusted networks and carefully validating header values.

Summary

In this blog post, I examined the purpose and functionality of the Forwarded Headers Middleware in ASP.NET Core. This middleware processes X-Forwarded-* headers to restore information about the original request, including the client’s IP address, the request scheme (HTTP or HTTPS), and the public URL. The middleware modifies the request with these details while preserving the original values in dedicated headers for reference.

In my Configuring ASP.NET Core Forwarded Headers Middleware post, I’ll provide a hands-on guide to configuring and working with these headers in your applications.

Resources

AdditionalAuthorizationParameters in ASP.NET Core 9

Tore Nestenius — Mon, 30 Dec 2024 00:00:00 GMT

In ASP.NET Core 9, a new feature called AdditionalAuthorizationParameters allows you to customize OAuth and OpenID Connect (OIDC) flows more quickly. This new feature allows developers to add custom authentication parameters without needing to rely on the complex workarounds that existed before ASP.NET Core 9 was released. Sounds familiar? Then you’re going to like this!

In this blog, I will practically introduce you to this feature, how it works, and how it ties together with Pushed Authorization Requests and AuthenticationProperties. Let’s jump in.

Why do we need AdditionalAuthorizationParameters?

Before ASP.NET Core 9, adding custom parameters to OAuth or OpenID Connect (OIDC) authorization requests was a cumbersome challenge. Developers had to override methods like BuildChallengeUrl in custom OAuth handlers or insert parameters manually using event hooks such as OnRedirectToIdentityProvider. This approach was verbose and error-prone, often leading to inconsistent project implementations.

AdditionalAuthorizationParameters solves this by providing a more straightforward and maintainable approach by including custom parameters directly in the authorization request configuration.

What Does Adding Custom Parameters Mean?

Customizing the initial authorization request sent to an OIDC authorization server often involves adding extra parameters to control or enhance the authentication process. A typical authorization request might look like this:

GET https://identityservice.secure.nu/connect/authorize
    ?client_id=localhost-addoidc-client
    &redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignin-oidc
    &response_type=code
    &scope=openid%20profile%20email%20offline_access
    &code_challenge=dtaF1NHSE5-C6E9eDuf-kEZJ_j7n48BaSTmezd4Go7Y
    &code_challenge_method=S256
    &response_mode=form_post
    &nonce=638645227425598693.OGFkYjhmMWUtZ...
    &state=CfDJ8IgPXRNAZH1EkNA0dd3_JvsHlnov...
    &x-client-SKU=ID_NET9_0
    &x-client-ver=8.1.2.0 HTTP/1.1

Sometimes, you may need to add extra parameters to further customize the authentication flow, for example, adding an audience, a tenant ID, or setting a specific prompt behavior.

Curious about what state and nonce contain? See Demystifying OpenID Connect’s State and Nonce Parameters in ASP.NET Core for more details.

The Old Way: Complex Workarounds

Before .NET 9, adding custom parameters often forced developers to resort to convoluted methods, such as:

.AddOpenIdConnect(options =>
{
    // ...
    options.Events.OnRedirectToIdentityProvider = context =>
    {
        context.ProtocolMessage.SetParameter("parameter1", "value1");
        context.ProtocolMessage.SetParameter("parameter2", "value2");
        context.ProtocolMessage.SetParameter("parameter3", "value3");
        return Task.CompletedTask;
    };
});

This results in an authorization request like:

GET https://identityservice.secure.nu/connect/authorize
    ?client_id=localhost-addoidc-client
    &redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignin-oidc
    &response_type=code
    &scope=openid%20profile%20email%20offline_access
    &code_challenge=dtaF1NHSE5-C6E9eDuf-kEZJ_j7n48BaSTmezd4Go7Y
    &code_challenge_method=S256
    &response_mode=form_post
    &nonce=638645227425598693.OGFkYjhmMWUtZ...
    &parameter1=value1
    &parameter2=value2
    &parameter3=value3
    &state=CfDJ8IgPXRNAZH1EkNA0dd3_JvsHlnov...
    &x-client-SKU=ID_NET9_0
    &x-client-ver=8.1.2.0 HTTP/1.1

While this approach worked, it required extra boilerplate and was far from intuitive.

How Does AdditionalAuthorizationParameters Improve This?

In ASP.NET Core 9, this process is significantly simplified. The new AdditionalAuthorizationParameters property, added to OpenIdConnectOptions, allows developers to configure additional parameters with minimal effort:

public class OpenIdConnectOptions : RemoteAuthenticationOptions
{
    // ...
    /// <summary>
    /// Gets the additional parameters that will be included in the authorization request.
    /// </summary>
    /// <remarks>
    /// The additional parameters can be used to customize the authorization request,
    /// providing extra information or fulfilling specific requirements of the
    /// OpenIdConnect provider. These parameters are typically, but not always,
    /// appended to the query string.
    /// </remarks>
    public IDictionary<string, string> AdditionalAuthorizationParameters { get; }
        = new Dictionary<string, string>();
    // ...
}

This lets you achieve the same goal with cleaner, more readable code:

.AddMyOpenIdConnect(options =>
{
    // ...
    options.AdditionalAuthorizationParameters.Add("parameter1", "value1");
    options.AdditionalAuthorizationParameters.Add("parameter2", "value2");
    options.AdditionalAuthorizationParameters.Add("parameter3", "value3");
});

This is a much-needed improvement when configuring OpenID Connect, making the code more maintainable.

What About Pushed Authorization Requests (PAR)?

The feature is also compatible with Pushed Authorization Requests (PAR). When using PAR, the request with AdditionalAuthorizationParameters might look like this:

POST https://identityservice.nu/connect/par HTTP/1.1
Host: identityservice.secure.nu
User-Agent: Microsoft ASP.NET Core OpenIdConnect handler
Content-Type: application/x-www-form-urlencoded

client_id=localhost-addoidc-client
&redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignin-oidc
&response_type=code
&scope=openid+profile+email+offline_access
&code_challenge=oIDRmjhH7UJXLaGXFNxbU5obKYXk8lMfj-OSsP73DmQ
&code_challenge_method=S256
&response_mode=form_post
&nonce=638645236162573853jIyMzc5...
&parameter1=value1
&parameter2=value2
&parameter3=value3
&state=CfDJ8IgPXRNAZH1EkNA0dd3_...
&client_secret=mysecret

The additional parameters are seamlessly included in the PAR request, keeping the feature compatible with modern authorization flows.

Curious about PAR? See Pushed Authorization Requests (PAR) in ASP.NET Core 9 for the full picture.

AdditionalAuthorizationParameters vs. AuthenticationProperties

AdditionalAuthorizationParameters lets you append custom parameters to the initial OpenID Connect authorization request.

AuthenticationProperties serves a different purpose: handling transient data stored alongside the authentication flow, such as redirection URLs or other metadata relevant to the sign-in process.

Summary

AdditionalAuthorizationParameters is a small but focused addition to ASP.NET Core 9 that fills a real gap in the OpenID Connect options model. If you need to pass custom parameters to the authorization endpoint, this is now the clean, built-in way to do it.

Simplifies customizing the initial authorization request.
Only applies to the OpenID Connect authentication handler.
Compatible with Pushed Authorization Requests (PAR).

Resources

API Proposal: The original GitHub issue related to this feature — Add AdditionalAuthorizationParameters to OAuthOptions/OpenIdConnectOptions.

IdentityServer In Docker Containers – Handle Logout (Part 4)

Tore Nestenius — Mon, 16 Dec 2024 00:00:00 GMT

In this final post in this series, we’ll now resolve logout challenges you might run into with IdentityServer, ensure proper sign-out redirects, and summarize the key takeaways from the series. Let’s complete the setup and finalize our IdentityServer configuration!

This blog has been broken up into four separate posts:

IdentityServer in Docker Containers: Adding Containers (Part 1)
IdentityServer in Docker Containers: Networking (Part 2)
IdentityServer in Docker Containers: HTTPS and SameSite (Part 3)
IdentityServer in Docker Containers: Handle Logout (Part 4)

Logout from IdentityServer (Attempt #10)

With the client application and IdentityServer successfully set up, communicating, and allowing users to log in, it’s time to ensure that sign-outs work securely and as expected.

When you run the system and log in at https://localhost:5001/, you should be redirected to the IdentityServer login page at https://localhost:7001/Account/Login.

From there, you can log in using the credentials bob/bob. You’ll be redirected back to the client application after successfully logging in and granting any necessary consent.

In the top-right corner, you should see the name of the logged-in user:

Clicking on the username will display detailed information about the current user, including their claims and tokens.

Additionally, this sample application provides a tool that shows all the details about the current request, such as the request headers:

However, there is still one final issue: when attempting to log out, you’re redirected to this URL:

http://identity/connect/endsession?post\_logout\_redirect\_uri…

This URL is incorrect because the identity service name is only accessible within the Docker network.

Fortunately, we can fix this by adding a custom event handler to AddOpenIDConnect to adjust the logout URL.

AddOpenIdConnect(options =>
{
    ...
    options.Events.OnRedirectToIdentityProviderForSignOut = context =>
    {
        context.ProtocolMessage.IssuerAddress =
            "https://localhost:7001/connect/endsession";
        return Task.CompletedTask;
    };
});

Now, when you try to sign out, you’ll first be prompted to confirm the logout:

If you confirm, you’ll be presented with a screen that confirms you have successfully logged out:

Great! You’ve successfully logged out, but we can improve the logout experience even more.

IdentityServer Redirect After Sign Out (Attempt #11)

The current sign-out experience can be improved by automatically redirecting the user back to the client application after logging out. How do we achieve this?

Start by locating the LogoutOptions class in IdentityServer, which is somewhat tucked away in the PagesLogout folder. It would be more intuitive if this configuration were placed in a more central location, but for now, we’ll modify it as follows:

public static class LogoutOptions
{
    public static readonly bool ShowLogoutPrompt = false;
    public static readonly bool AutomaticRedirectAfterSignOut = true;
}

However, after restarting the application, nothing has changed! That’s odd. How do we solve this?

JWT token validation error: IDX10205: Issuer validation failed.

Checking the IdentityServer logs, you should see this error:

JWT token validation error: IDX10205: Issuer validation failed. Issuer: 'http://identity'. 
Did not match: validationParameters.ValidIssuer: 'https://localhost:7001' or 
validationParameters.
ValidIssuers: 'null' or validationParameters.ConfigurationManager.CurrentConfiguration.Issuer: 
'Null'. For more details, see https://aka.ms/IdentityModel/issuer-validation.

Wait, why is there a token issue when we sign out? We’re not calling an API? When the client requests IdentityServer to sign out, it sends a request like this:

Request starting HTTP/2 GET https://localhost:7001/connect/endsession
?post_logout_redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignout-callback-oidc
&id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6IkNEODRGQTgzNEY...
&state=CfDJ8KWm8...
&x-client-SKU=ID_NET8_0
&x-client-ver=7.1.2.0

Upskill With Me: Courses, Workshops & Training

What is the Purpose of id_token_hint?

According to the OpenID Connect specification:

The ID Token previously issued by the OP to the RP is passed to the Logout Endpoint as a hint about the end user’s current authenticated session with the Client. This indicates the end-user’s identity that the RP requests to be logged out by the OP.

This token serves several important purposes:

Session Identification:
This helps the Identity Provider identify which session to log out of, especially if multiple sessions are active.
Logout Context:
Ensures the logout request is associated with a valid session.
Security:
The token mitigates risks like Cross-Site Request Forgery (CSRF) attacks by verifying that the request comes from a trusted client.
User Experience:
This improves the flow by allowing the Identity Provider to make informed decisions about logging out of specific clients or all sessions.

What’s Inside the ID Token?

If you decode the id_token using https://jwt.io, you’ll see something like this:

{
  "iss": "http://identity",
  "nbf": 1728670667,
  "iat": 1728670667,
  "exp": 1728670967,
  "aud": "localhost-addoidc-client",
  "amr": ["pwd"],
  "nonce": "638642674649534072.ZDJlZWY0YzAtZjdmMi00ZTQ0LWIxZTAtOTM1ZjBiMThkMDNkZTM0ZTMxM2UtOGQ3My00ZTZlLTk3ZTktYWZhNDBhMmExOTVk",
  "at_hash": "kGT-YFIlnrw1AsguWas2yw",
  "sid": "F410E3EB5B7B5B0E6A8C8F3AC16BBA8F",
  "sub": "2",
  "auth_time": 1728670667,
  "idp": "local",
  "name": "Bob Smith",
  "given_name": "Bob",
  "family_name": "Smith",
  "email": "BobSmith@email.com",
  "email_verified": true,
  "website": "http://bob.com"
}

The problem is that the token’s issuer is http://identity, while IdentityServer expects it to be https://localhost:7001. This discrepancy stems from the dynamic discovery document issue we encountered earlier.

How to fix the issuer in IdentityServer

To fix this, we can set a static issuer in IdentityServer by adding the following to its Program.cs:

var isBuilder = builder.Services.AddIdentityServer(options =>
{
    options.IssuerUri = "https://identity";
    ...
}

This change ensures that the tokens issued have a consistent issuer value no matter where the request originates. For example, with this change, the discovery document will contain:

Within Docker (http://identity/.well-known/openid-configuration)

{
   "issuer":"http://identity",
   "jwks_uri":"http://identity/.well-known/openid-configuration/jwks",
   "authorization_endpoint":"http://identity/connect/authorize"
   ...
}

From the Host (https://localhost:7001/.well-known/openid-configuration):

{
   "issuer":"https://identity",
   "jwks_uri":"https://localhost:7001/.well-known/openid-configuration/jwks",
   "authorization_endpoint":"https://localhost:7001/connect/authorize"
   ...
}

By setting the IssuerUri to a static value (https://identity), we ensure the issuer remains consistent across all environments while the other parameters adjust based on the request’s origin.

When we try to sign out now, we are automatically redirected back to the client application.

Working with proxies?

If your client is behind a proxy or load balancer, you might need to configure the ForwardedHeaders middleware. Check out these two blog posts for more details:

Summary and Feedback

Writing this blog series has been both challenging and rewarding. Learning how to containerize IdentityServer and connect it with a client application in Docker taught me a lot about IdentityServer and OpenID Connect, even some details I didn’t fully understand.

I might have made mistakes or missed some important points. I would love to hear your feedback and suggestions on improving these posts. Your thoughts will help me make this content better for everyone.

We also deliberately chose not to modify the host file, which could have resolved some issues faster. However, taking the harder route allowed us to learn more and better understand the process.

Source Code

You can find all the source code for each step, along with the final solution, on my GitHub repository.

What’s next for me?

I’m planning to turn this blog series into a live webinar. If you’re interested in learning more about IdentityServer and want to join an interactive session, sign up for my newsletter to stay updated on the event details.

What Should I Blog About Next?

I’m always looking to create content that helps the developer community. What topics would you like me to cover in future blog posts? Your suggestions are invaluable, and I’d love to hear your ideas! You can find my contact details here.

Do You Need Help with Authentication?

I offer training and consulting services to help teams implement secure and scalable authentication solutions, including IdentityServer and OpenID Connect. I also specialize in ASP.NET Core development, architecture design, and code reviews.

Feel free to reach out if you need support with authentication, ASP.NET Core, or architectural guidance. I’m here to help you build robust and secure solutions.

IdentityServer in Docker Containers: HTTPS and SameSite (Part 3)

Tore Nestenius — Sun, 08 Dec 2024 00:00:00 GMT

In this third part of the series, we tackle login issues in IdentityServer caused by cookie restrictions in HTTP and show how to resolve them by implementing HTTPS. We’ll guide you through securing communication between the host, client, and IdentityServer containers and configuring HTTPS in Docker to ensure everything runs smoothly.

This blog has been broken up into four separate posts:

IdentityServer in Docker Containers: Adding Containers (Part 1)
IdentityServer in Docker Containers: Networking (Part 2)
IdentityServer in Docker Containers: HTTPS and SameSite (Part 3)
IdentityServer in Docker Containers: Handle Logout (Part 4)

If you want to view the final solution, the code for each step and the final code can be found on GitHub here.

Picking up from where we left off, we’ve successfully set up the containers and established communication between them. Next, we turn to user login issues that can arise if we’re not careful! The login form isn’t working when using bob/bob to authenticate. Why is that? Let’s investigate further.

For this example, we’ll use the Chrome browser. Press F12 to open the browser developer console, then navigate to the Network tab.

Try logging in as bob/bob again, and look for the request made to the login URL. Once located, click on the Cookies tab.

Under the Cookies tab, if you enable the option Show filtered out request cookies, you’ll notice several cookies highlighted in yellow. These cookies are rejected or not included in the request. Hover over the info icon next to each cookie to find out why.

The core issue is that we’re using HTTP. Many crucial cookies are blocked due to the SameSite and Secure attributes. These cookies are essential for ASP.NET Core’s CSRF protection, IdentityServer, and the OpenID Connect authentication handler. There is no way around this!

To resolve this, we must use HTTPS for browser-based interactions. The back-channel communication, however, can continue to use HTTP since no cookies are involved in those requests.

For more details about troubleshooting cookie problems, check out my blog post: Debugging Cookie Problems in ASP.NET Core

Why did we start with HTTP? Beginning with HTTP simplifies the initial setup of the containers and ensures that we can quickly establish communication between them. Once everything works correctly with HTTP, it’s easier to transition to the more secure HTTPS configuration.

So, how do we implement this? We’ll address that in the next attempt.

Adding HTTPS to IdentityServer and Client (Attempt #8)

To resolve the cookie issue, we need our application’s client and IdentityService to support HTTPS while keeping HTTP for back-channel communication. This requires exposing port 443 and adding separate port mappings, as shown below:

We begin by updating the two Dockerfiles to expose port 443 and configuring ASP.NET Core to listen on ports 80 and 443. This is done by adding or updating the following lines in each file:

EXPOSE 80 443

ENV ASPNETCORE_URLS=http://+:80;https://+:443

Next, we modify the docker-compose.yml file and map the two HTTPS ports:

services:
  client:
    build:
      context: .
      dockerfile: Dockerfile_Client
    ports:
      - "5000:80"
      - "5001:443"
    depends_on:
      - identity
  identity:
    build:
      context: .
      dockerfile: Dockerfile_Identity
    ports:
      - "7000:80"
      - "7001:443"

Finally, we update the AddOpenIDConnect configuration in the client to use HTTPS for all browser-related interactions:

}).AddOpenIdConnect(options =>
{
    options.Authority = "https://localhost:7001";
    options.MetadataAddress = "http://identity:80/.well-known/openid-configuration";
    ...
    options.Events.OnRedirectToIdentityProvider = context =>
    {
        context.ProtocolMessage.IssuerAddress = "https://localhost:7001/connect/authorize";
        return Task.CompletedTask;
    };
});

If we launch the Docker Compose setup now, it crashes with the following error:

System.InvalidOperationException: Unable to configure HTTPS endpoint. No server certificate was specified, and the default developer certificate could not be found or is out of date.

If this exception doesn’t appear in the logs, consider adjusting the log levels in appsettings.json for more detailed error messages.

Why does this error occur?

This error happens because the application cannot find a valid HTTPS certificate. ASP.NET Core expects a trusted certificate to configure HTTPS endpoints, but it isn’t available. We will resolve this issue by setting up the required certificate in the next attempt.

Adding the certificate to IdentityServer / Client (Attempt #9)

To enable HTTPS, we need to add a TLS certificate to each container. But where do we get such a certificate? We could create a self-signed certificate or use a paid trusted certificate.

However, since this setup is only for local development and we want to keep using the localhost domain, the simplest solution is to use the existing developer certificate that we installed and trusted when setting up ASP.NET Core and Visual Studio.

Run the following command to check if you have a valid development certificate installed:

> dotnet dev-certs httpsA valid HTTPS certificate is already present.

For more information, refer to the official dotnet dev-certs documentation

We then run the following command to export the certificate from the Windows certificate store to a separate file.

> dotnet dev-certs https --export-path ./aspnetcore-dev-cert.pfx --password MyPw123 --format PFX

This command will create a file named aspnetcore-dev-cert.pfx at the root of your project directory. In a real-world scenario, storing this file outside the repository is best to avoid accidental commits. As a best practice, ensure that .pfx files are included in your .gitignore file.

Next, we need to import the certificate into both containers. This is done by mounting the certificate file as a volume in each container. Modify the docker-compose.yml file as follows:

services:
  client:
    build:
      context: .
      dockerfile: Dockerfile_Client
    ports:
      - "5000:80"
      - "5001:443"
    depends_on:
      - identity
    volumes:
      - ./aspnetcore-dev-cert.pfx:/app/aspnetcore-dev-cert.pfx
  identity:
    build:
      context: .
      dockerfile: Dockerfile_Identity
    ports:
      - "7000:80"
      - "7001:443"
    volumes:
      - ./aspnetcore-dev-cert.pfx:/app/aspnetcore-dev-cert.pfx

For more details on setting up HTTPS with Docker Compose, check out the guide on Hosting ASP.NET Core images with Docker Compose over HTTPS

⚠️ Security Warning
This approach works and is used here for simplicity and demonstration purposes. For a more secure setup, store the certificate outside the project folder or inject it from a trusted key vault at runtime.

Upskill With Me: Courses, Workshops & Training

Next, we need to configure ASP.NET Core to use this certificate by setting its path and password as environment variables in the compose.yml file:

services:
  client:
    build:
      context: .
      dockerfile: Dockerfile_Client
    ports:
      - "5000:80"
      - "5001:443"
    depends_on:
      - identity
    volumes:
      - ./aspnetcore-dev-cert.pfx:/app/aspnetcore-dev-cert.pfx
    environment:
      - ASPNETCORE_Kestrel__Certificates__Default__Path=/app/aspnetcore-dev-cert.pfx
      - ASPNETCORE_Kestrel__Certificates__Default__Password=MyPw123
  identity:
    build:
      context: .
      dockerfile: Dockerfile_Identity
    ports:
      - "7000:80"
      - "7001:443"
    volumes:
      - ./aspnetcore-dev-cert.pfx:/app/aspnetcore-dev-cert.pfx
    environment:
      - ASPNETCORE_Kestrel__Certificates__Default__Path=/app/aspnetcore-dev-cert.pfx
      - ASPNETCORE_Kestrel__Certificates__Default__Password=MyPw123

With these steps completed, we have successfully mounted the certificate into each container and configured ASP.NET Core to use it. This allows us to access the services over HTTPS using the following URLs:

https://localhost:5001/ for the client
https://localhost:7001/ for the identity service

Awesome! 🥳

What’s next

We’ve resolved the login issues using HTTPS and secured the communication between the host and containers. In the final post, we’ll address the sign-out challenges and wrap up the key lessons from this series. Stay tuned!

To the next post >>>

Resources

IdentityServer in Docker Containers: Networking (Part 2)

Tore Nestenius — Mon, 25 Nov 2024 00:00:00 GMT

This is part 2 of a blog series on containerizing a Duende IdentityServer and a client application. In this post, we resolve communication challenges that arise when these applications run in separate Docker containers. You’ll learn how to fix back-channel issues, handle localhost conflicts, and establish proper networking between the client and IdentityServer.

This blog has been broken up into four separate posts:

IdentityServer in Docker Containers: Adding Containers (Part 1)
IdentityServer in Docker Containers: Networking (Part 2)
IdentityServer in Docker Containers: HTTPS and SameSite (Part 3)
IdentityServer in Docker Containers: Handle Logout (Part 4)

If you want to view the final solution, the code for each step and the final code can be found on GitHub here.

Fixing the IdentityServer Back-Channel (Attempt #2)

In the previous post, we learned we can’t use localhost from within the containers, so what should we do instead?

Docker Compose automatically creates a default network for all services defined in the docker-compose.yml file. This network allows containers to reach each other using their service names as DNS names.

In our setup, the client container should communicate with the identity container using http://identity:7000 rather than http://localhost:7000.

}).AddOpenIdConnect(options => {     options.Authority = "http://identity:7000";     ... };

Here, identity is the name of the IdentityService container as defined in our Docker Compose file.

But when we run this, we’ll still encounter an error. Why?

The issue lies in how Docker Compose handles container communication. Services within Docker Compose communicate using their service names and the internal container ports they expose, not the external ports.

This means that while external clients (such as a web browser or Postman) outside the Docker network should use port 7000 to reach the IdentityService, containers within Docker should use the internal port, which is 80.

To resolve this, we need to adjust the port in the code to use port 80 instead, like this:

}).AddOpenIdConnect(options =>
{
    options.Authority = "http://identity:7000";
    ...
};

This configuration change ensures that the client container can successfully communicate with the identity container using the correct internal port.

However, this still needs to be fixed!

We end up with the browser trying to reach http://identity/connect/authorize, but obviously, we can’t use this outside Docker. Identity is only a name that can be used within the Docker network.

We could resolve this by adding the Identity hostname to the operating system’s host file. However, I prefer a solution that doesn’t require modifying this file.

The Issue with Setting the Authority in IdentityServer

Setting the authority in the client to http://identity:80 might seem like the obvious solution, but it introduces a few complications!

In our current setup, the Authority configuration serves three distinct purposes:

Retrieving Configuration Documents: It is used by the OpenID Connect authentication middleware in the client container to retrieve the /.well-known/openid-configuration and /.well-known/openid-configuration/jwks documents from IdentityServer.
OpenID Connect Flows: The authority URL is crucial during various OpenID Connect flows, including authentication, token exchange, and sign-out.
Browser Redirection: It also tells the browser where to redirect the user when authentication is required so that the user can authenticate.

The problem arises because the client container needs to use http://identity:80 to reach IdentityServer from within the Docker network. In contrast, the browser (which is outside the Docker network) needs to use http://localhost:7000 to reach IdentityServer.

This mismatch between the internal and external URLs complicates the situation.

Introducing the MetaDataAddress (Attempt #3)

To try to address this, we can introduce the MetadataAddress property in our configuration, as shown below:

.AddOpenIdConnect(options =>
{
    options.Authority = "http://localhost:7000";
    options.MetadataAddress = "http://identity:80";
    ...
};

By setting these two properties, we try to achieve the following:

Authority: This is set to the externally accessible URL of IdentityServer (http://localhost:7000).
MetadataAddress: This points to where the OpenID Connect authentication handler can reach IdentityServer internally (http://identity:80). This allows the client container to correctly obtain the needed configuration documents from IdentityServer.

With this configuration, we maintain compatibility for both internal container-to-container communication and external browser redirects.

The application still does not work, and so we get a new exception in the browser:

JsonException: IDX10805: Error deserializing json: '<!DOCTYPE html> <html lang="en">...

How do we solve this?

Upskill With Me: Courses, Workshops & Training

Fixing the IdentityServer MetadataAddress (Attempt #4)

The MetadataAddress property in OpenID Connect should be set to the absolute URL of the metadata document, not just the base URL. This is an essential distinction because MetadataAddress specifies the exact endpoint from which the OpenID Connect middleware will retrieve the configuration.

The solution is to change the configuration to:

.AddOpenIdConnect(options =>
{
    options.Authority = "http://localhost:7000";
    options.MetadataAddress = "http://identity:80/.well-known/openid-configuration";
    ...
};

Now, retrieving the metadata from IdentityServer should work. However, we are back to the problem where the browser tries to reach http://identity/connect/authorize.

Observing the Back-Channel Communication

The client’s OpenID Connect authentication handler occasionally makes HTTP requests to the authorization server (IdentityServer), which is known as the back channel. By default, this communication could be more visible from the outside. However, implementing a custom backchannel handler to log these interactions can make it more transparent.

To implement this, we create a new delegating handler named BackChannelListener, implemented as follows:

public class BackChannelListener : DelegatingHandler
{
    public BackChannelListener() : base(new HttpClientHandler())
    {
    }

    protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request,
                                                                 CancellationToken token)
    {
        var sw = new Stopwatch();
        sw.Start();
        var result = await base.SendAsync(request, token);
        sw.Stop();
        Log.Logger.ForContext("SourceContext", "BackChannelListener")
                   .Information($"### BackChannel request to {request?.RequestUri?.AbsoluteUri} took {sw.ElapsedMilliseconds.ToString()} ms");
        return result;
    }
}

This implementation will measure the time it takes for each request to complete and log it using Serilog. This will give us insights into the back-channel communication between the client and IdentityServer.

Next, we configure the OpenID Connect handler to use this handler:

.AddOpenIdConnect(options =>
{
    ...
    options.BackchannelHttpHandler = new BackChannelListener();
    options.BackchannelTimeout = TimeSpan.FromSeconds(30);

});

With this setup, we should be able to see in the logs each time the client makes a request to IdentityServer over the back-channel, like the examples below:

### BackChannel request to http://identity/.well-known/openid-configuration took 362 ms
### BackChannel request to http://identity/.well-known/openid-configuration/jwks took 30 ms

These logs provide valuable visibility into internal HTTP communication, helping us better understand the performance and behavior of back-channel requests.

However, our application still can’t authenticate; let’s address that in the next attempt.

Understanding the Discovery Document Issue (Attempt #5)

If we run the application now, we still can’t authenticate successfully because the browser tries to access
http://identity/connect/authorize… instead of the expected URL.

To understand what’s happening, we can add a minor tweak to our BackChannelListener to log the back-channel responses from IdentityServer to the console. This will give us insight into what the client receives.

We add this code to the handler:

// HACK: log the response body; never run this in production
Log.Logger.ForContext("SourceContext", "BackChannelListener")
          .Information("#####################################");

Log.Logger.ForContext("SourceContext", "BackChannelListener")
          .Information(responseContent);

Log.Logger.ForContext("SourceContext", "BackChannelListener")
          .Information("#####################################");

⚠️Important⚠️

The back-channel request and response contain sensitive information, such as tokens or configuration data. Therefore, you should only log this information during troubleshooting and never in a production environment.

With this in place, we can see that the client correctly retrieves the discovery document as expected when we attempt to authenticate. The log shows the following output:

{
  "issuer":"http://identity",
  "jwks_uri":"http://identity/.well-known/openid-configuration/jwks",
  "authorization_endpoint":"http://identity/connect/authorize"
  ...
}

However, when we navigate to the discovery document directly from our browser at
http://localhost:7000/.well-known/openid-configuration, we get a different result:

{
  "issuer":"http://localhost:7000",
  "jwks_uri":"http://localhost:7000/.well-known/openid-configuration/jwks",
  "authorization_endpoint":"http://localhost:7000/connect/authorize"
  ...
}

The issuer URL changes depending on where the request is made:

Inside Docker: http://identity
Outside Docker: http://localhost:7000

This discrepancy occurs because the identity provider’s issuer value is dynamically generated based on the origin of the incoming request URL.

Solving The Initial Authentication Problem (Attempt #6)

The main issue is that when we click the log-in button, the application receives information from IdentityServer indicating that the authorization endpoint is http://identity/connect/authorize. Naturally, it tries to redirect the browser to that URL for user authentication using the authorization code flow.

To address this in a development environment, we can add the following event handler to intercept the redirect and adjust the URL to the correct one:

.AddOpenIdConnect(options =>
{
    ...
    options.Events.OnRedirectToIdentityProvider = context =>
    {
        context.ProtocolMessage.IssuerAddress =
            "http://localhost:7000/connect/authorize";
        return Task.CompletedTask;
    };
	
});

Depending on your deployment setup, you may need to implement a different strategy in production. The key takeaway here is to understand the root cause of the issue.

Important!⚠️

Let me know if you have a better approach to solving this problem!

With this change in place, the application should now correctly redirect to IdentityServer and display the login screen as expected.

Great! Are we done?

Not quite yet! When we try to log in with the default bob/bob user, the form doesn’t work. ☹

What’s next

In the next post, we’ll address the login form issue and introduce HTTPS to secure communication between the host and the containers, enabling successful and secure authentications.

To the next post >>>

IdentityServer in Docker Containers - Part 1

Tore Nestenius — Fri, 22 Nov 2024 00:00:00 GMT

Getting Duende IdentityServer and a client application up and running in separate containers can be challenging. This blog post will provide a step-by-step guide for a smooth setup and show you how to resolve common challenges along the way. We will also learn about security, cookies, ports, containers, and certificates.

This is a big topic, so this blog is divided into four posts. You can get to where you need to be below, but for handy context, it may be helpful to read this post first.

⦁ IdentityServer in Docker Containers: Adding Containers (Part 1)
⦁ IdentityServer in Docker Containers: Networking (Part 2)
⦁ IdentityServer in Docker Containers: HTTPS and SameSite (Part 3)
⦁ IdentityServer in Docker Containers: Handle Logout (Part 4)

If you want to view the final solution, the code for each step and the final code can be found on GitHub here.

Background - containerizing a Duende IdentityServer

I spend quite a bit of my time helping developers on Stack Overflow, and I’ve noticed that many struggle with containerizing a Duende IdentityServer solution. There are numerous pitfalls, gotchas, and misconceptions that we need to understand and address.

The series focuses on deploying Duende IdentityServer locally using Docker Compose, emphasizing the fundamentals rather than a production-ready implementation.

This series takes a step-by-step approach to tackle the challenge, highlighting common mistakes and pitfalls along the way. Rather than simply presenting the final solution, it encourages a shared learning experience, and troubleshooting issues together to build a strong understanding of the fundamentals for containerizing IdentityServer with Docker Compose.

Important – Not for Production

The focus is on getting the application to work locally in a containerized environment using Docker Compose. Making this setup production-ready involves additional considerations beyond the scope of this post.

The Setup – IdentityServer and the Client Application

We have two ASP.NET Core 8 applications: one client application and one IdentityServer application. Both applications have been tweaked to make them more educational.

We name the IdentityServer project IdentityService to avoid potential naming collisions in our code.

The complete source code for this setup and each attempt to create it can be found in my public GitHub repository. The source code in the Start project folder contains the start code, which you can run from within Visual Studio and authenticate using the credentials bob/bob.

The Goal – containerized IdentityServer solution

This setup aims to package two applications into separate containers and run them locally using Docker Desktop with Docker Compose. Authentication against IdentityServer should still work seamlessly after containerization.

Containerize IdentityServer and The Client (Attempt #1)

In our first attempt, we’ll create the following setup using HTTP. Starting with HTTP is beneficial for its simplicity and highlighting some gotchas we’ll explore later in this blog post series. We’ll introduce and use HTTPS later.

We add two Dockerfiles (Dockerfile_Client and Dockerfile_Identity) to containerize the client and IdentityServer projects. The code for them can be found on GitHub.

Next, we add a Docker compose file to launch the two containers and expose ports 5000 and 7000 to the host machine.

services:
  client:
    build:
      context: .
      dockerfile: Dockerfile_Client
    ports:
      - "5000:80"
  identity:
    build:
      context: .
      dockerfile: Dockerfile_Identity
    ports:
      - "7000:80"

In the client application (program class), we modify the OpenID Connect authority as follows:

}).AddOpenIdConnect(options =>
{
    options.Authority = "http://localhost:7000";
    ...
};

To build and deploy the containers, we use the following Docker Compose command:

docker-compose up --build

A simple batch file (RunCompose.bat) has been added that runs the command for us.
When we run the containers, we can observe that both are up and running and can be accessed using http://localhost:5000/ and http://localhost:7000/.

However, when we click on the login button, we get the following error:

IOException: IDX20804: Unable to retrieve document from: 'http://localhost:7000/.well-known/openid-configuration'.

This error occurs because the client application tries to download the IdentityServer’s discovery document and public signing keys from the specified URL but fails to do so. The discovery document is crucial as it contains endpoints and configuration data that the client needs to communicate with IdentityServer securely.

The URL works fine when I go to http://localhost:7000/.well-known/openid-configuration in my browser!

So, why does this not work when it works from the browser?

Upskill With Me: Courses, Workshops & Training

The problem with Localhost and Containers

In our setup, the client attempts to make a cross-container HTTP request like this:

However, when requesting http://localhost:7000/, it is crucial to understand that this URL is resolved within the client container itself, not to the IdentityService that we intended to reach.

The image below shows what happens in our current setup. Obviously, nothing is listening on port 7000 inside the client container.

The issue arises from having multiple isolated localhost instances in the setup, each tied to a specific container:

⦁ Client container has its own localhost.
⦁ Identity container has its own localhost.
⦁ Host machine has yet another localhost.

As a result, when the client container tries to access http://localhost:7000/, the request is confined to the client container itself and never reaches the IdentityServer container.

The image below illustrates how these three separate localhost environments exist in our setup:

The key here is Docker’s network isolation, which prevents containers from communicating with one another using localhost.

What’s next

We’ll resolve this further in my next post, were we will continue refining the communication between the two containers as we work toward building a fully functional, containerized IdentityServer solution.

To the next post >>>

Pushed Authorization Requests (PAR) in ASP.NET Core 9

Tore Nestenius — Mon, 04 Nov 2024 00:00:00 GMT

ASP.NET Core 9 introduces support for Pushed Authorization Requests (PAR) in its OpenIdConnect authentication handler. But what exactly is PAR, and why does it matter? In this post, I’ll explain what PAR is, how it works, how to use it with Duende IdentityServer, and when you should consider using it in your applications.

What is Pushed Authorization Requests (PAR)?

PAR is a relatively new OAuth standard that is designed to enhance the security of OAuth and OpenID Connect (OIDC) flows. Traditionally, authorization parameters (such as client credentials, scopes, and redirect URIs) are passed through the browser (front channel) via URL query strings. This approach exposes sensitive data to potential attackers and increases the risk of tampering. PAR addresses this by shifting the transmission of authorization parameters from the front channel to the back channel through direct machine-to-machine HTTP calls.

This change brings several important benefits:

Improved Security: Since authorization parameters are sent via a secure back-channel request, they are no longer exposed in browser URLs, reducing the risk of sensitive information (like Personally Identifiable Information, or PII) being leaked.
Tamper Resistance: By pushing authorization requests through the back end, attackers are prevented from modifying the parameters, such as the requested scopes or access levels.
Shorter URLs: In complex OAuth/OIDC scenarios (such as when using Rich Authorization Requests, URLs can become excessively long, which can cause issues with some browsers and networking systems.

Why are Pushed Authorization Requests Important?

PAR has gained a lot of traction in industries with stringent security requirements, such as open banking and healthcare. The FAPI 2.0 Security Profile, which is developed by the Financial-grade API (FAPI) working group within the OpenID Foundation, now mandates the use of PAR for increased security.

As a result, many identity providers, including Duende IdentityServer, Curity, Keycloak, and Authlete, now support PAR.

Authenticating without Pushed Authorization Requests (PAR)

When you’re using the Authorization Code flow to authenticate with an authorization server without using PAR, the process typically follows this sequence:

Initial Request to the Authorization Endpoint

When a user needs to authenticate, the OpenID Connect handler in the client initiates the authentication flow by redirecting the user to the authorization endpoint. This request includes all of the necessary authorization parameters, which are sent through the browser’s front channel via the URL, as shown below:

Here’s a sample request:

GET https://myidentityserver.com/connect/authorize
    ?client_id=myclient
    &redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignin-oidc
    &response_type=code
    &scope=openid%20profile%20email%20offline_access
    &code_challenge=mmTnrL97RIKECAhsDKXP0lXubokXxr5tPqq_fOP2rtg
    &code_challenge_method=S256
    &response_mode=form_post
    &nonce=638645055062345714....
    &state=CfDJ8IgPXRNAZH1EkNA0dd....
    &x-client-SKU=ID_NET9_0
    &x-client-ver=8.1.2.0
HTTP/1.1

See my blog post Demystifying OpenID Connect’s State and Nonce Parameters in ASP.NET Core for more details about what the state and nonce contains.

Receiving the Authorization Code

After the user authenticates and consents to the request, the authorization server sends the application an authorization code.

This code is delivered to the redirect_uri (in this example, https://localhost:5001/signin-oidc) through a POST request:

POST https://localhost:5001/signin-oidc HTTP/1.1
Content-Type: application/x-www-form-urlencoded

code=7C6DA4BE86ED80FD9DB9A077320C2DF0FC2B1CD43D742C5CFDD466FF5B850188-1
&scope=openid+profile+email+offline_access
&state=CfDJ8IgPXRNAZH1EkNA0dd3_JvtZYeDos8gQO0om...
&session_state=vXoggS4g5yYhV8pQNnZ5eq5DLC4UKE2Pq4ggWPNEOX8...
&iss=https%3A%2F%2Fmyidentityserver.com

This request also includes the state parameter to ensure the response matches the original request.

Exchanging the Authorization Code for Tokens

Once the client application receives the authorization code, it can exchange it for tokens by making a request to the token endpoint over the back channel.

Here’s an example of that request:

POST https://myidentityserver.com/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=myclient
&client_secret=mysecret
&code=7C6DA4BE86ED80FD9DB9A077320C2DF0FC2B1CD43D742C5CFDD466FF5B850188-1
&grant_type=authorization_code
&redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignin-oidc
&code_verifier=ZQVkrVGSqxYPrPyO1Bjppnd-Kv3rH3LX_8U3Q7ScB5I

If the authorization code exchange is successful, the authorization server responds with the requested tokens:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "id_token":"eyJhbGciOiJSUzI1NiIsImt...",
  "access_token":"eyJhbGciOiJSUzI1NiIsImtpZ...",
  "expires_in":3600,
  "token_type":"Bearer",
  "refresh_token":"CAB1E2AC3A9904AF307F8B7...",
  "scope":"openid profile email offline_access"
}

This flow follows the typical OAuth Authorization Code flow without using PAR. While this approach works well, sending sensitive parameters via the front channel (browser URL) can expose them to potential tampering or leakage. That’s where PAR comes in; instead, it shifts these parameters to a more secure back-channel communication.

Pushed Authorization Requests (PAR) metadata

According to RFC 9126, the discovery document of an identity provider includes new fields related to Pushed Authorization Requests (PAR). These fields help clients to determine if and how to use PAR during user authentications. The relevant new metadata fields are:

pushed_authorization_request_endpoint

The endpoint where the client sends the PAR request.

require_pushed_authorization_requests

A boolean parameter that indicates whether the authorization server only accepts authorization requests via PAR. If omitted, the default value is false

For example, in the discovery document from IdentityServer located at /.well-known/openid-configuration, you might see the following metadata:

{
  ...
  "pushed_authorization_request_endpoint": "https://myidentityserver.com/connect/par",
  "require_pushed_authorization_requests": false,
  ...
}

When a client starts up, it typically downloads this discovery document. By reading these fields, the client can decide whether to use PAR for the authorization request. If require_pushed_authorization_requests is true, then the client must use PAR; otherwise, it can use the standard front-channel authorization request approach.

Configuring Pushed Authorization Requests in IdentityServer

IdentityServer is one of several authorization servers that support PARs. You can configure and control PAR in two key areas: globally during server startup and at the client level in the client definitions.

Global Configuration at Startup
When setting up the server, you can enable and configure PAR globally in IdentityServer by modifying the IdentityServerOptions. Here’s how you can do it:

builder.Services.AddIdentityServer(options =>
{
    ...
    options.Endpoints.EnablePushedAuthorizationEndpoint = true;

    options.PushedAuthorization = new PushedAuthorizationOptions
    {
        // Specifies whether pushed authorization requests are globally required
        // (Default false).
        Required = true,

        // The pushed authorization request's lifetime (Default 10 minutes)
        Lifetime = 10 * 60,

        // Specifies whether clients may use redirect URIs that were not previously
        // (default false)
        AllowUnregisteredPushedRedirectUris = true,
    };
});

**Client-Specific Configuration
**In addition to global settings, you can configure PAR behavior in the client definitions. This allows you to enforce or adjust PAR usage for specific clients as needed.

new Client
{
    ...
    RequirePushedAuthorization = true,
    PushedAuthorizationLifetime = 10*60, // 10 minutes
}

Configuring Pushed Authorization Requests in ASP.NET Core 9

ASP.NET Core 9 introduces Pushed Authorization Requests (PAR) support in its OpenID Connect authentication handler. You can manage how PAR is used using the new PushedAuthorizationBehavior option.

Here’s an example of how to configure it:

.AddMyOpenIdConnect(options =>
{
    options.Authority = "https://myidentityserver.com";

    options.PushedAuthorizationBehavior = PushedAuthorizationBehavior.Disable;
    ...
});

The PushedAuthorizationBehavior option also determines whether and when PAR should be used during the authorization process. This option accepts an enum with the following values:

public enum PushedAuthorizationBehavior
{
   /// <summary>
   /// Use Pushed Authorization (PAR) if the PAR endpoint is available.
   /// This is the default value.
   /// </summary>
   UseIfAvailable,
   
   /// <summary>
   /// Never use Pushed Authorization (PAR), even if the PAR endpoint is available
   /// </summary>
   
   Disable,
   /// <summary>
   /// Always use Pushed Authorization (PAR), and emit errors if there is no PAR endpoint
   /// </summary>
   Require
}

By adjusting this option, you can fine-tune how your application handles authorization requests, enabling both strong security and compatibility with identity providers.

In the next section, we’ll explore how PAR requests work in action.

Pushed Authorization Requests in Action

The authorization process involves multiple steps when you’re using Pushed Authorization Requests (PAR), starting with the initial request that pushes the authorization parameters to the authorization server.

First Request – The Pushed Authorization Request

First, the ASP.NET Core OpenIdConnect handler sends a POST request to the identity provider’s PAR endpoint with the authentication details:

Here’s an example of what that request looks like:

POST https://myidentityserver.com/connect/par HTTP/1.1
User-Agent: Microsoft ASP.NET Core OpenIdConnect handler
Content-Type: application/x-www-form-urlencoded

client_id=localhost-addoidc-client-PAR
&redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignin-oidc
&response_type=code
&scope=openid+profile+email+offline_access
&code_challenge=ZBSpp9z-eMxb3uFOyl8lMLIW7TGERoprxvBH8wMQ444
&code_challenge_method=S256
&response_mode=form_post
&nonce=638645126122011768.MGI2YTg4MmItODA0Ni00NzY2LW...
&state=CfDJ8IgPXRNAZH1EkNA0dd3_JvuMKE37whAZ6E15FtjzZ...
&client_secret=mysecret

This request closely mirrors the parameters used in the traditional (non-PAR) flow, with one key difference: instead of sending the parameters in the URL, they are sent directly from the client in the POST request body.

By pushing the parameters in the body of a POST request, PAR provides several advantages:

Larger Payload:
Unlike URLs, which are limited in length, the body of a POST request can carry a larger payload, making it ideal for more complex authorization requests.
Improved Security:
Since the request parameters, including sensitive data (such as client_secret and code_challenge), are placed in the body rather than the URL, this information is less likely to be logged or exposed. This helps to mitigate the risk of leaking secrets through URL logs or browser history.

The response to this POST request typically looks like this:

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8

{
  "request_uri":
"urn:ietf:params:oauth:request_uri:ED3A57A0CC571379715FBE0C0B62DEF84D903A96B8E1A1D43EDC1D757C828050",
  "expires_in":600
}

In this response:

request_uri:
A unique identifier (or token) that represents the authorization request. This URI will be used in the subsequent requests to the authorization server.
expires_in:
The duration (in seconds) for which the request_uri is valid. In this example, it’s valid for 600 seconds (10 minutes).

The request_uri serves as a reference to the original authorization request sent to the PAR endpoint. This allows the client to send only the request_uri over the front channel, keeping sensitive data securely in the back channel and reducing the risk of exposure.

Second Request – The Authorization Request

In the second step of the PAR flow, the user’s browser is redirected to the authorization endpoint. Instead of including the full authorization parameters in the URL (as in the traditional flow), the client simply uses the request_uri returned earlier.

Here’s an example of what this request looks like:

GET https://myidentityserver.com/connect/authorize?
client_id=localhost-addoidc-client-PAR
&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3A9A7990D0AC4D844FBDB49C9451A23A8C5D41FBCC29BCF1BE201C3338C7099E5D
&x-client-SKU=ID_NET9_0
&x-client-ver=8.1.2.0 HTTP/1.1

User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)...
Referer: https://localhost:5001/

In this request, the request_uri refers to the authorization data previously submitted through the back channel in the first request.

Once the user is redirected, they will go through the usual authentication and consent steps. Upon successful completion, the authorization server will send the authorization code to the client’s redirect URI:

Sample request to the /signin-oidc endpoint:

POST https://localhost:5001/signin-oidc HTTP/1.1
Content-Type: application/x-www-form-urlencoded

code=7A9404B7DA1532A0D836834263AE73CF029AFE819D4AE0A62079C23F6C6452BF-1
&scope=openid+profile+email+offline_access
&state=CfDJ8IgPXRNAZH1EkNA0dd3_Jvv5huWjaDM6DMPX...
&session_state=YiFCBw1ATTffMuEI0SFOPwjnAoorH3Jz_...
&iss=https%3A%2F%2Fmyidentityserver.com

Using this code, the OpenID Connect handler can then exchange it for the real tokens, just like how we did it in the non-PAR example.

Summary

In this blog post, we explored Pushed Authorization Requests (PAR) in ASP.NET Core 9 and how it improves the security of OAuth and OpenID Connect (OIDC) flows. PAR moves sensitive authorization parameters from the browser (front channel) to secure back-channel communication instead, offering several key benefits:

Improved Security: Keeps sensitive data out of URLs.
Tamper Resistance: Prevents attackers from altering authorization parameters.
Cleaner, Shorter URLs: Especially useful in complex authorization scenarios.

Using Duende IdentityServer as an example, we showed how PAR is configured globally and at the client level. Additionally, we walked through the PAR process, including:

The Pushed Authorization Request, where authorization data is securely sent to the server.
The Authorization Request, where the client uses the returned request_uri to complete the authorization flow.

Resources

Introducing the Cloud Debugger for Azure

Tore Nestenius — Mon, 21 Oct 2024 00:00:00 GMT

The Cloud Debugger is an open-source tool for Azure developers to explore, learn, and troubleshoot their Azure cloud environments. Whether preparing for Azure certification, looking to streamline debugging, or aiming to deepen your understanding of Azure, Cloud Debugger provides the tools to make the cloud more discoverable.

Background - Getting Azure certified

As I prepared for the AZ-204 Azure developer certification, I realized that I needed to build something larger to understand the Azure Cloud and the services covered by the Azure Developer certification. Just doing the included exercises was not enough. This led to me creating this open-source tool designed to help learn and simplify the debugging process for Azure applications.

The Mars Rover vs. Azure Analogy

When we explore Mars, we send rovers to measure, observe, and perform experiments to understand the unknown.

Developers also need a systematic approach when navigating Azure’s vast and complex cloud environment. Cloud Debugger is designed to provide this by enabling you to explore, experiment, and gain deeper insights into your cloud setup.

Cloud Debugger as a Teaching Tool for Azure

A secondary purpose of this tool is to serve as an exercise platform for future Azure training. Rather than relying solely on theoretical exercises, Cloud Debugger offers a hands-on environment where developers can actively engage with Azure services, troubleshoot real-world scenarios, and experiment with different configurations, features, and concepts.

What can the Cloud Debugger for Azure do?

The Cloud Debugger offers over 30 specialized tools to help developers explore, diagnose, and understand their Azure environment. These tools include:

HTTP Request tools
- Current request viewer
  View details about the current request.
- Request Logger
  Provides a list of all the received requests.
- Calling External APIs
  Make HTTP requests to external APIs. Useful for testing external communication and tracing in Application Insights.
Azure App Services
- File System
  Explore the local file system.
- Local Cache
  Explore the App Services local cache feature.
Azure Storage tools
- Blob Storage Tools
  Read and create blobs.
- Create a user delegation SAS token
  Create a sample token to access a blob in blob storage.
- File System Explorer
  Explore the local file system.
- Redis Explorer
  Write and read keys from Redis.
- Cosmos DB
  (coming soon)
Azure Events and Messaging
- Event Grid
  Send events to Event Grid
- Event Hubs
  Produce and consume Event Hub events
- WebHooks
  Receive webhook requests from EventGrid and other services.
Azure Identity Tools
- DefaultAzureCredentials
  Explore the inner workings of this TokenCredential.
- Token caching
  Explore how the token caching varies across the different Token Credentials.
- Token Credentials Explorer
  Explore the different Token Credentials.
- Azure.Identity event log viewer
  Explore and view the internal event log.
Diagnostics and system information
- Runtime Details
  Show details about the current runtime and operating system.
- Environment Variables
  View all the environment variables.
- Errors
  Trigger different error pages.
- Network Details
  Show details about the network interfaces.
- Scale-out and load balancing
  Visualize the effects of load-balancing
Azure Logging
- Logging
  Write a message to the standard log
- Log Analytics Workspace
  Write messages to this service.
Other tools
- Caching and CDN
  Explore the effect of caching and CDN.
- Health checks
More tools will be added over time. If you have suggestions, feel free to contact the author, submit an issue, or contribute via a pull request.

Deploying Cloud Debugger for Azure

The Cloud Debugger is also designed to be highly flexible in its deployment options. The same service can be deployed across multiple environments using the provided PowerShell scripts, which makes it versatile for various use cases. It supports the following target environments:
- Azure App Services
  - Windows
  - Linux
  - Linux Containers
- Azure Container Instances
- Azure Container Apps
This allows the service to be deployed across multiple environments, enabling comparisons of application behavior in each. One PowerShell script, BuildAndDeployAll.ps1, will build and deploy to all five environments in one operation.

Equally important is the DeleteAllResources.ps1 script, which will delete the Cloud Debugger resource group and its content. I typically run this script at the end of the day to save money and resources.

Why are we using PowerShell to deploy?

Mastering Azure CLI was essential for the AZ-204 certification, and using PowerShell provided hands-on experience with low-level deployment. This approach prepares me to transition to higher-level tools like Azure Bicep, which I plan to explore by converting these scripts in the future.

Cloud Debugger Implementation Details

The Debugger is implemented as a standard ASP.NET Core 8 application written in C#.

Continious Integration

A GitHub Action is triggered with every commit to automatically verify that the project builds correctly. However, we currently handle deployment to Azure using local PowerShell scripts, rather than deploying directly from GitHub.

Customized ASP.NET Core Libraries

We pulled down the source code for Azure.Identity and HttpLogging then converted them into custom class libraries to get better insights and integration with this tools. We also tweaked the namespaces of these two libraries to avoid naming collisions.
- **Azure.Identity
  **We patched this library to gain better insight into how the different Token Credentials behave internally. You can see this when you use the various Identity tools there.
- Microsoft.AspNetCore.HttpLogging
  This ASP.NET Core class library has been patched to improve the logging of incoming requests to the application, providing better insights into request details.
Secure Development Practices

We try to follow secure development practices, using tools that run with each pull request to prevent bugs, code smells, and security vulnerabilities from entering the cloud environment.

The tools we use are:
- SonarCloud
  Provides cloud-based static code analysis to detect code quality issues and vulnerabilities.
- **SonarLint
  **A lightweight IDE extension that helps catch code issues in real-time during development.
- GitHub Dependabot.
  Automatically updates dependencies to help you avoid security vulnerabilities and outdated libraries.
- **GitHub Code Scanning
  **Identifies potential security issues and bugs in the code by scanning the repository.
- **GitHub Secrets Scanning
  **Detects exposed secrets and sensitive data in the repository to prevent leaks and security breaches.
Here is what it can look like when a pull request does not pass all the checks:

Important Azure Security Consideration

It is important not to run this tool in your production environment because it can expose internal secrets, keys, access tokens, and other sensitive information. The tool can also create or send content to various Azure services, which could lead to unintended changes or security risks if it is misused.

Crucially, you must lock down this tool to ensure that only authorized users can access it. Currently, the tool does not provide any built-in feature to restrict access, so additional security measures must be implemented separately.

Getting Started with the Cloud Debugger for Azure

The tool is now available on GitHub; you can start using it by following the deployment guide.

The extensive documentation offers everything you need to get up and running quickly, focusing on providing the shortest path to value.

Join Us, Feedback and Contribute to the project

Cloud Debugger is open source, and we welcome contributions! Whether you’re interested in adding new features, fixing bugs, or sharing your experiences with us and the community, we’d love to hear from you. Check out our GitHub repository and join our growing community there.

Other Blog Posts by Me
Related Training Workshops
- Introduction to Azure for Developers
Azure Challenges? I’m Here to Help!

Considering using Azure cloud or have a challenge or project on your hands? Need to pave a clear and helpful path for improving cloud skills in your team? If you need some guidance, I’d be happy to help you! I can help you with:
- Navigating Azure cloud migration and deployment challenges.
- Overcoming inefficiencies, debugging and visibility issues in Azure cloud.
- Defining a training pathway for your team to harness Azure effectively.
- Identifying security risks and securing your environment more broadly.
- Organizing projects, testing, production and deployment in Azure.
Feel free to get in touch using the details below, submitting a form on the contact page, or connect with me on LinkedIn.
- tore@tn-data.se
- +46 708 166856
Linkedin Contact

User Delegation SAS Tokens In Azure Explained

Tore Nestenius — Fri, 04 Oct 2024 00:00:00 GMT

I discovered many interesting Azure features while studying for the AZ-204 certification. One of these features is User Delegation SAS tokens, a way to provide access to Azure Blob Storage. In this blog post, I’ll share what I learned about these tokens and how to use them in C#/.NET.

Accessing Azure Storage Accounts

Azure offers various methods to secure, manage, and grant access to storage accounts, from anonymous access to more advanced approaches like Azure Role-Based Access Control (RBAC). Each method has its use case, security level, and limitations.

SAS (Shared Access Signature tokens)

With Shared Access Signatures (SAS), you can securely delegate access to resources within your Azure Storage accounts. They allow you to specify which resources can be accessed, what actions can be taken, and how long the permissions should be valid.

For example, if you have a blob in storage named Myblob.txt and want to grant access to users outside of Azure, you can use SAS tokens.

To do this, you select the blob and specify the desired access level and expiration date, as shown in the image below:

As a result, Azure will generate an SAS token that might look something like this:

sp=r&st=2024-08-21T17:17:21Z&se=2024-08-22T01:17:21Z&spr=https&sv=2022-11-02
&sr=b&sig=T7mWwTfZnvtU%2FuoR1vDAjKX1B7OLl0b6YcHgiJ0SFBw%3D

This token is signed using one of the two access keys associated with the storage account.

Then, you can append this token to the blob resource URL, like this:

https://clouddebuggerstorage.blob.core.windows.net/Data/Myblob.txt
?sp=r&st=2024-08-21T17:17:21Z&se=2024-08-22T01:17:21Z&spr=https&sv=2022-11-02
&sr=b&sig=T7mWwTfZnvtU%2FuoR1vDAjKX1B7OLl0b6YcHgiJ0SFBw%3D

Anyone with this URL can now read the blob from anywhere in the world until the token expires.

Awesome!

The issue with using access keys

Azure provides two access keys for each storage account, often named key1 and key2. These keys provide full access to all services enabled in the storage account, including Blob Storage, File Storage, Queue Storage, and Table Storage. The reason for having two keys is to facilitate key rotation.

These two highly sensitive keys should never be used outside your storage account because they provide full admin access to the entire storage account. You will find these two keys in the Azure Portal under the Access keys blade:

You can create an SAS token by signing the desired access request with one of these keys.

With this concept, you can issue any number of SAS keys with different access levels using the same access key:

What is the problem with SAS tokens?

Although SAS tokens provide essential access controls for Azure storage, they come with certain challenges:

Because SAS tokens are signed with the storage account’s access keys, all issued SAS tokens are jeopardized if these keys are exposed or compromised.
Furthermore, managing SAS tokens can become complex in dynamic environments, especially when customizing access for a growing number of users and applications.
If someone loses or leaks a SAS token, anyone who obtains it can access the storage resources it governs until the token expires or you manually revoke it.

These limitations underscore the need for a more flexible solution, such as User Delegation SAS tokens, which integrate with Azure Active Directory for enhanced security and manageability.

User Delegation SAS tokens

What is the main difference compared to the SAS tokens described above?

The key advantage of User Delegation SAS tokens is that they allow applications to issue their own SAS tokens, offering more granular and secure access controls. This enables applications to define permissions tailored to each user or scenario without relying on the storage account’s access keys.

How does the application obtain the user delegation key?

To start, the application uses its managed identity to authenticate with Entra ID and acquire an access token. Once authenticated, the BlobServiceClient utilizes this access token to request a user delegation key from Entra ID.

var blobStorageUri = $"https://{model.StorageAccountName}.blob.core.windows.net";

// Step #1, get an authentication token from Entra ID
var credentials = new DefaultAzureCredential();

// Step #2, Create a BlobServiceClient with these credentials
var client = new BlobServiceClient(new Uri(blobStorageUri), credentials);

// Step #3, get a user delegation key from Entra ID
var startsOn = DateTimeOffset.UtcNow.AddMinutes(-1); // To avoid clock skew issues
var expiresOn = startsOn.AddDays(1);                 // Max is 7 days

var userDelegationKey = client.GetUserDelegationKey(startsOn, expiresOn);

The image below illustrates how the application acquires the user delegation key:

What is the purpose of the user delegation key?

our application can generate and sign new SAS tokens with the User Delegation Key, without relying on the storage account access keys. This provides an additional layer of security by granting granular permissions. The key is tied to the application and the Azure Active Directory (AAD) identity requesting it. Each time you request a User Delegation Key, a new key is issued, ensuring that permissions are limited to the specific context of the request.

What is inside the delegation key?

The GetUserDelegationKey method provides a UserDelegationType object and the following table shows an example of what is inside this object:

Creating A User Delegation SAS token

With the user delegation key in place, the application can create a new user delegation SAS token using the following code:

// Step #4, Define the permissions for the SAS token
BlobSasBuilder sasBuilder = new BlobSasBuilder()
{
    BlobContainerName = containerName,
    BlobName = blobName,
    Resource = "b",
    StartsOn = DateTimeOffset.UtcNow,
    ExpiresOn = DateTimeOffset.UtcNow.AddHours(1)
};

// Step #5, Specify the necessary permissions
sasBuilder.SetPermissions(BlobSasPermissions.Read);

//// Alternatively, you can combine multiple permissions
//sasBuilder.SetPermissions(BlobContainerSasPermissions.Read |
//                          BlobContainerSasPermissions.Write |
//                          BlobContainerSasPermissions.List |
//                          BlobContainerSasPermissions.Delete);

// Step #6, Build the SAS token
Var SASToken = sasBuilder.ToSasQueryParameters(userDelegationKey,
                                               storageAccountName).ToString();

The SAS token that you generate might look like this:

skoid=1dc7a951-446c-4572-8275-30561ef281f7&sktid=567d82a1-7f61-4da2-b955-d3244ea6e976
&skt=2024-08-22T08%3A01%3A16Z&ske=2024-08-23T08%3A01%3A16Z&sks=b
&skv=2024-08-04&sv=2024-08-04&st=2024-08-22T08%3A02%3A16Z
&se=2024-08-22T09%3A02%3A16Z&sr=b&sp=r&sig=zajbqclywkZvs56T0RIMqcgWa24FHXpFdogV%2F9KMDIQ%3D

If we reformat it, we see the following details

skoid=1dc7a951-446c-4572-8275-30561ef281f7
&sktid=567d82a1-7f61-4da2-b955-d3244ea6e976
&skt=2024-08-22T08%3A01%3A16Z
&ske=2024-08-23T08%3A01%3A16Z
&sks=b
&skv=2024-08-04
&sv=2024-08-04
&st=2024-08-22T08%3A02%3A16Z
&se=2024-08-22T09%3A02%3A16Z
&sr=b
&sp=r
&sig=zajbqclywkZvs56T0RIMqcgWa24FHXpFdogV%2F9KMDIQ%3D

The details for what each parameter represents can be found here.

Using the user-delegated SAS token

With the token in place, you can now, for example, append it to blog storage URLs like this:

https://[MyStorage].blob.core.windows.net/clouddebugger/MyBlob.txt?[SASToken]

The alternative is to pass it as credentials to the BlobServiceClient, like this:

var client = new BlobServiceClient(SASToken);

User Delegation SAS Token permissions

For an application to be able to issue a User Delegation SAS token, it must be granted specific permissions:

To get the delegation key, the application needs one of the following roles assigned against the target storage account:

Contributor
Storage Account Contributor
Storage Blob Data Contributor
Storage Blob Data Owner
Storage Blob Data Reader
Storage Blob Delegator

These roles should be scoped to the storage account, resource group, or subscription level. For more detailed information, visit the official documentation here.

Additionally, the application must possess RBAC permissions to interact with specific resources within the storage account, such as containers or blobs.

What are the Benefits of Using User Delegation SAS Tokens?

Key ManagementThe key used to sign the SAS tokens is obtained from Entra ID using the application’s managed identity, eliminating the need to manage the signing key manually.
Limited Lifetime:
You can configure the tokens to be short-lived, which reduces the window of opportunity for unauthorized access.
Enhanced Auditing:
User Delegation SAS tokens appear in Azure Storage access logs, improving the traceability of access and recorded actions.
Principle of Least Privilege:
Applications issuing these tokens can operate with lower privileges, adhering to the principle of least privilege, which reduces their risk profile.
Access Limitation:
A SAS token cannot grant more access to the storage account than the permissions allocated to the application that issued it, ensuring that privileges are appropriately contained.
**Security Against Key Leakage:**By not depending on account keys, User Delegation SAS tokens significantly reduce the risk associated with key leakage. Exposure of account keys can jeopardize the security of the entire storage account; this risk is mitigated with User Delegation SAS tokens.

Summary

When I first encountered the User Delegation SAS tokens concept, I found the technical documentation overwhelming and lacking in clear use-case descriptions. The initial confusion led to some experimentation and, admittedly, a struggle. However, as I dug deeper and started to apply what I learned practically, the pieces began to fall into place.

Writing this blog post has deepened my understanding of the purpose and applications of User Delegation SAS tokens. I’ve come to appreciate their significance and utility. It’s important to note that User Delegation SAS tokens are limited to Azure Blob Storage.

How Can I Explore Delegation Tokens?

The Cloud Debugger, an exploration tool for Azure cloud developers, includes a feature that allows you to experiment with delegation tokens. The image below shows an example of what it might look like when using this tool:

Resources

Feedback, comments, found any bugs?

Let me know if you have any feedback, If I missed anything or any bugs/typos. You can find my contact details here.

Running Docker in an Azure Windows Virtual Machine – Not so fast!

Tore Nestenius — Tue, 24 Sep 2024 00:00:00 GMT

This blog post describes getting Docker up and running inside an Azure Windows Virtual Machine. This might sound like a simple task, but trust me, there are some surprises on the way that took me a day or so to figure out.

Why run docker in an Azure Virtual Machine?

As a trainer, I need to provide a consistent, pre-configured environment where students can focus on learning without the hassle of setting up their own machines. Many of my exercises rely on Docker, but in environments like government or corporate settings, strict security policies often prevent students from installing Docker Desktop.

By using Azure virtual machines, I sidestep these restrictions, ensuring that everyone has a uniform setup. This approach also helps avoid issues like local firewalls blocking network requests, which is especially important during security training sessions.

Best of all, it allows me to focus on delivering the training itself without worrying about technical setup when I arrive at a customer site.

The Master Image
I update the master image 1-2 times yearly, and the process has worked great! But one day a few years ago, a few days before my next training class, I decided to rebuild the image. I created the virtual machine in the Azure portal asI have always done, like this:

After the image was created, I logged in to the master machine using a remote desktop, applied all the various updates, and installed the various software packages. All going well until it was time to install Docker. Installing Docker has worked fine in the past, but to my surprise, this time, it did not work! Why?

Perhaps I missed some steps in my documented process, so I recreated the VM and tried again. However, it still fails with the same error. From previous experience, I know that that installation of Docker can be a bit unreliable. However, it is still not starting after installation!

I was getting weird errors like this one:

deploying WSL2 distributions
ensuring main distro is deployed: deploying "docker-desktop": importing WSL distro "WSL2 is not supported with your current machine configuration.

Please enable the "Virtual Machine Platform" optional component and ensure virtualization is enabled in the BIOS.
Enable "Virtual Machine Platform" by running: wsl.exe --install --no-distribution

For information please visit https://aka.ms/enablevirtualization
Error code: Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED" output="docker-desktop": exit code: 4294967295:

running WSL command wsl.exe C:\Windows\System32\wsl.exe --import docker-desktop \AppData\Local\Docker\wsl\main C:\Program Files\Docker\Docker\resources\wsl\wsl-bootstrap.tar --version 2:
WSL2 is not supported with your current machine configuration.

Please enable the "Virtual Machine Platform" optional component and ensure virtualization is enabled in the BIOS.
Enable "Virtual Machine Platform" by running: wsl.exe --install --no-distribution
For information please visit https://aka.ms/enablevirtualization
Error code: Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED

: exit status 0xffffffff

checking if isocache exists: CreateFile \\wsl$\docker-desktop-data\isocache\: The network name cannot be found.

When I encountered this issue a few years ago, I didn’t receive an error message as helpful as the one I got today when I tested it for this blog post. The error seems to be related to the BIOS, but since this is a VM, I can’t access the BIOS settings. This feature has worked fine before, so I doubt the BIOS is the problem.

Additionally, the VM type supports nested virtualization, so that isn’t the issue either.

Troubleshooting Docker in Azure Virtual Machine

Ok, so let’s troubleshoot!

The first step is to check what Windows features are installed. Are WSL and Hyper-V installed? Under my Windows Features, everything looks good, nothing out of the ordinary.

Solving the mystery that blocks Docker in an Azure VM

After a long period of searching on Google and reviewing GitHub issues, I began to find indications that suggest an absence of virtualization support. It’s strange because running Docker in Azure Virtual Machine has worked fine for me in the past.

But let’s confirm this by first looking at the Task Manager.

Something is missing here!

The Task Manager of a computer running Docker looks like this:

Why is virtualization disabled?

Apparently, the virtualization feature is not present in my Virtual Machine. Did you notice my mistake when I created the virtual machine above? No, that is easy to miss!

Apparently, a new concept called Trusted Launch Virtual Machines has been introduced. Trusted machines sound like a good idea! This is now the default setting when creating a new virtual machine.

However, when I created my virtual machine, I didn’t notice this new feature or think that it would be a big deal. It turns out that this feature disables virtualization inside the VM. ☹

Restoring Virtualization for Docker in Azure VM

The solution is to select the standard security type when creating a new virtual machine.

Now it works!

Annoying dark patterns in Azure Portal

I find it quite frustrating that when I’m creating a new Virtual Machine in the portal, the default OS disk type is set to the more expensive Premium SSD type. This can be costly when creating non-critical test machines in the cloud. In my opinion, the default setting should be Standard SSD, which is more sensible.

I once received a cloud bill of over 1000 USD because I forgot to delete a bunch of disk images. These images were all on a Premium SSD disk. ☹

Summary

Things like this can really drive you crazy, and these small details can be really hard to find! During this frustrating incident, I spent about a day trying to figure it out. I then coined this quote:

“Cloud development: making developers cry since the early 2000s.”

The experience of developing for the cloud can be pretty challenging. Spending days trying to achieve what seems obvious or simple can be frustrating.

Do you agree with the pain of web development?

(Ps, I didn’t cry 😊)

Feedback, comments, found any bugs?

Let me know if you have any feedback, If I missed anything or any bugs/typos. You can find my contact details here.

Deploy Container to Azure App Services with System-Assigned Identity

Tore Nestenius — Mon, 02 Sep 2024 00:00:00 GMT

In this blog post, I will guide you through deploying a custom container image to Azure App Services from a private container registry using a system-assigned managed identity and the Azure CLI.

We will focus on leveraging the system-assigned managed identity approach in this article. For those interested in using a user-assigned managed identity, a separate post covering that method can be found here.

If you want to know more about managed identities in Azure, visit the article What are managed identities for Azure resources?

Background

In my previous blog post, I covered deploying a container image to Azure App Services using a user-assigned managed identity. This blog post will show how this can be simplified using a system-assigned managed identity.

This blog post will focus on the differences compared with the previous approach, so head over to that one first before you read this blog post.

User vs. system-assigned identity

In the world of Azure identities, it’s crucial to understand the distinction between user-assigned and system-assigned identities. Let’s explore the key differences.

User-Assigned Identities

In our previous post, we explored user-assigned identities. Here’s a recap of the essentials:

Independent Creation: The identity is created separately from the App Service resource.
Flexible Assignment: This identity can be assigned to multiple resources, providing flexibility.
Lifecycle Management: Developers are responsible for managing the identity’s lifecycle.
Longevity: User-assigned identities can be long-lived, making them ideal for applications that require consistent identity usage over time.

System-assigned identities

These identities share similarities with user-assigned identities but with some key differences:

Automatic Creation: Azure creates the identity when the resource is created.
Resource-Specific: The identity is tied to a specific resource.
Automatic Deletion: The identity is deleted when the resource is deleted.
Scoped to Resource: The identity is limited to the specific resource it is assigned to.

The primary advantage of system-assigned identities is the convenience that they offer. Azure manages the creation and deletion of these identities which reduces the manual effort required.

Understanding these differences helps in choosing the right identity type for your Azure resources so that they can be securely and efficiently managed.

Let’s explore how using system assigned identities can simplify the effort to deploy a container image to Azure App Services.

Important:

I am not a regular PowerShell developer.
I would like to get feedback on the script! How can I improve it? Bugs? Style? Or am I doing it wrong?

Part 1 – The settings file

The Settings.ps1 file is almost the same as the one we used before, with the key difference being that we do not need to specify any identityName. The script is as follows:

# resource group name
$rgname = 'MyTestResourceGroup'

# location
$location = 'swedencentral'

# The name of the App Service Plans
$AppServicePlan_linux = 'asp-MyApp-Linux-dev'

# The SKU of the App Service Plans
$AppServicePlanSKU_Linux = 'S1'     # Standard plan

# The name of the App Services
$AppServiceName_container_linux = 'MyApp-Linux-Container-dev'

# Azure container registry name
$ACRName = 'tncontaineregistry'

# AzureRover container image name
$imagename = 'mycontainerimage'

Part 2 – Creating the Azure App Service infrastructure

The script 1-Infrastructure.ps1 that creates the initial infrastructure can be handily reduced to the following:

Step 1: Create the resource group
Write-Host "`n`nCreating the resource group."
$resgroup = az group create `
        --name $rgname `
        --location $location `
        | ConvertFrom-Json
$resId = $resgroup.id
Write-Host "Resource group created, id: ${resId}"

# Step 2: Create Azure Container Registry
Write-Host "`n`nCreating the Azure Container Registry."
$acr = az acr create `
        --resource-group $rgname `
        --name $ACRName `
        --sku Basic `
        --admin-enabled true `
        | ConvertFrom-Json


$acrid = $acr.id
Write-Host "Azure Container Registry created, id: ${acrid}"

Here, the big difference is that we don’t have to create any identity manually. After running the above script, you should only find one resource in your resource group:

Part 3 – Pushing the docker image to the container

Creating the container image locally is beyond the scope of this blog post. However, the script below (found in 2-BuildAndPushDockerImage.ps1) will log in to ACR, tag, and push the image to the ACR.

. .\Settings.ps1

# Step 1: Log in to the Azure Container Registry
Write-Host "`n`nLogging into Azure Container Registry '${ACRName}'."
Write-Host "If this step hangs, ensure Docker is running locally."
az acr login --name $ACRName

# Step 2 Tag the local Docker image with the registry server name of your ACR
$taggedImage = "${ACRName}.azurecr.io/${imagename}:latest"
$localImageName = "mycontainerimage"
Write-Host "`n`nTagging the Docker image '${localImageName}' with '${taggedImage}'."
docker tag $localImageName $taggedImage

# Step 3: Push the local image to Azure Container Registry
Write-Host "`n`nPushing the Docker image '${taggedImage}' to ACR."
docker push $taggedImage

The script above assumes you have an image named “mycontainerimage” in your local Docker environment and this script is the same as we used in the previous blog post.

After you run the script, you should be able to find the image in the registry within the portal:

After this step, we assume that a container image is in a registry with the following URL:
tncontaineregistry.azurecr.io/mycontainerimage:latest

Part 4 – Creating the Azure App Service

This script is simpler compared to the script we used in the previous blog post. The goal of this script is to perform the following steps:

Retrieve the ID of the Azure Container Registry.
Create the Linux App Service Plan.
Create the container App Service.
Set the identity in the App Service to access the ACR.
Verify the ACR identity.
Enable Application Logging (Filesystem).
Enable log streaming (optional).

This script, named 3-CreateAppService-UserAssigned.ps1, is a bit bigger, so we will review it step by step in detail below.

Step #1 – Get the ID of the Azure Container Registry

We first need to retrieve the ID of the registry we created earlier and we can do this by using:

Write-Host "`nQuerying for the container registry ID"
$acr = az acr show `
    --name $acrName `
    --resource-group $rgname `
    --output json | ConvertFrom-Json
$acrId = $acr.id
Write-Host "ACR found with ID: ${acrId}"

Step #2 – Create the Linux App Service Plan

The next step involves creating a Linux-based App Service Plan which is required to host and run your App Services. In this part, we don’t do anything unusual:

Write-Host "`nCreating the Linux App Service Plan"
$servicePlan = az appservice plan create `
    --name $AppServicePlan_linux `
    --resource-group $rgname `
    --is-linux `
    --sku $AppServicePlanSKU_Linux `
    --output json | ConvertFrom-Json
$servicePlanId = $servicePlan.id
Write-Host "App Service Plan created with id: ${servicePlanId}"

Step #3 - Create the Azure Container App Service

The next step is to create the container-based App Service to run on the previously created App Service Plan. This time, we will use a system-assigned identity:

$imagePath = "${acrname}.azurecr.io/${imagename}:latest"
Write-Host "`n`nCreating the container App Service."
Write-Host "With the following image ${imagePath}"
$AppService = az webapp create `
    --name $AppServiceName_container_linux `
    --acr-use-identity `
    --plan $AppServicePlan_linux `
    --resource-group $rgname `
    --container-image-name $imagePath `
    --assign-identity [System] `
    --role "AcrPull" `
    --scope $acrId `
    --output json | ConvertFrom-Json
$hostName = $AppService.defaultHostName
$appServiceID = $AppService.id
Write-Host "App Service created, id: ${appServiceID}"

What has changed compared to the user-assigned identity approach?

Identity Assignment: Instead of manually creating and assigning an identity, we use the —assign-identity [system] parameter. This tells Azure to create a system-assigned identity as part of the service creation.
Role Specification: The role parameter is used to define the role for the identity, ensuring it has the necessary permissions to pull an image from the registry.
Scope Definition: The scope parameter specifies the scope within which the role will be applied, ensuring the identity has access to the container registry.

So in short, this all means a simpler and streamlined setup that works precisely to your needs compared to the approach using user-assigned identity. Pretty cool, right?

Reviewing the Azure App Service identity

In the portal, Azure created a system-assigned identity for us, and we can see this under Settings -> Identity:

This identity was assigned the AcrPull role:

On the Deployment -> Deployment Center page, we see that it is using a system assigned managed identity to access the registry:

Are we done?

Yes, running the script will successfully deploy the container image and we no longer see the dreadful application error page as we did before! We’ve also simplified the deployment script a bit.

Summary

Writing these two blog posts about container deployment to Azure App Services has been both a challenging and educational journey into the intricacies of Azure and PowerShell. If you’re on the journey too, I’d encourage you to read the previous blog post Deploy containers Azure App Services using user-assigned managed identity alongside this one to compare these two approaches.

In conclusion, using the system-assigned identity approach for App Services significantly simplifies the process. However, it would be even more streamlined if Microsoft allowed specifying the ACR identity directly in the az webapp create command. This enhancement would further simplify the deployment process and the developer experience.

You can find the complete scripts here here

Feedback, comments, found any bugs?

Let me know if you have any feedback, if I missed anything, or if you have any bugs/typos. You can find my contact details here

Deploy containers Azure App Services using user-assigned managed identity

Tore Nestenius — Tue, 27 Aug 2024 00:00:00 GMT

This blog post describes my approach to successfully deploying a custom container image to Azure App Services from a private container registry, using a user-assigned managed identity and the Azure CLI.

This blog post will cover how to do this using a user-assigned managed identity, and a separate post will cover how to do this using a system-assigned managed identity.

Why I Did This

For this project my goal was clear: I wanted to deploy a custom Linux container from Azure Container Registry and host it in Azure App Services. Although there are many hosting alternatives in Azure, my focus was on achieving this specific deployment using Azure App Services.

Here’s the constraints I set:

The script should be fully scripted using Azure CLI and PowerShell, not Bicep or ARM templates.
The container image should be hosted in a private repository in an Azure Container Registry.
I want to properly utilize a user-assigned managed identity for my App Service to pull the image from the registry, instead of using the admin username/password approach.
The script should create all the necessary resources, including the resource group, app-service plan, and more.

Out of scope for this blog post:

The creation of the container image.
Proper error handling.
Using deployment slots or using a CI/CD system.

I thought this would be easy, but boy, was I wrong! I assumed it would only take a few hours because I’ve been using Azure App Services for some time. However, this project turned out to be quite challenging. I encountered bugs, unexpected issues, confusing documentation, and frustration.

Eventually, I was able to make something work, and now I’m sharing my findings with you in this blog post so you don’t have to go through the same pain and suffering.

Important:

I am not a regular PowerShell developer.
I would like to get feedback on the script! How can I improve it? Bugs? Style? Or am I doing it wrong?
I did all of this as part of my AZ-204 certification study.

Part 1 – The Settings file

I will be utilizing multiple scripts to accomplish my objectives and all the scripts can be found here. To get started, I created a shared Settings.ps1 file that consolidates all the settings for this deployment. This script should be fairly self-explanatory and it looks like this:

# resource group name
$rgname = 'MyTestResourceGroup'

# location
$location = 'swedencentral'

# My identity name
$identityName = 'MyAppIdentity'

# The name of the App Service Plans
$AppServicePlan_linux = 'asp-MyApp-Linux-dev'

# The SKU of the App Service Plan
$AppServicePlanSKU_Linux = 'S1'     # Standard plan

# The name of the App Services
$AppServiceName_container_linux = 'MyApp-Linux-Container-dev'

# Azure container registry name
$ACRName = 'tncontaineregistry'

# AzureRover container image name
$imagename = 'mycontainerimage'

Part 2 – Creating the infrastructure

Next, we need to do the following:

Create a resource group.
Create a managed identity.
Create an Azure Container Registry.
Assign the AcrPull role to the identity to pull images from the registry.

I will call this script “1-Infrastructure.ps1,” and it looks like this:

#Run the settings script
. .\Settings.ps1

# Step 1: Create the resource group
Write-Host "`n`nCreating the resource group."
$resgroup = az group create `
        --name $rgname `
        --location $location `
        | ConvertFrom-Json
$resId = $resgroup.id
Write-Host "Resource group created, id: ${resId}"

# Step 2: Create a managed identity
Write-Host "`nCreating a managed identity."
$identity = az identity create `
        --name $identityName `
        --resource-group $rgname `
        --output json | ConvertFrom-Json
$identityId = $identity.id
$principalId = $identity.principalId
Write-Host "User-assigned managed identity created"
Write-Host "name: ${identityName}"
Write-Host "id: ${identityId}"h
Write-Host "PrincipalId: ${principalId}"

Write-Host "`nWaiting 30s to ensure the identity is fully registered and propagated in Azure AD..."
# The AcrPull assignment might otherwise fail.
Start-Sleep -Seconds 30

# Step 3: Create Azure Container Registry
Write-Host "`n`nCreating the Azure Container Registry."
$acr = az acr create `
        --resource-group $rgname `
        --name $ACRName `
        --sku Basic `
        --admin-enabled true `
        | ConvertFrom-Json

$acrid = $acr.id
Write-Host "Azure Container Registry created, id: ${acrid}"

# Step 4: Assign the AcrPull role to the managed identity on the ACR
Write-Host "`n`nAssigning AcrPull role to the managed identity."
$role = az role assignment create `
        --assignee $principalId `
        --role "AcrPull" `
        --scope $acrid `
        --output json `
        | ConvertFrom-Json

In the script above, everything is standard, except that I needed to include a delay to ensure that the identity is registered and propagated correctly in Azure before assigning the role to it.After that, you can expect to find these two items in your resource group in the portal:

The MyAppIdentity identity should also have been assigned the AcrPull role:

Awesome! So far so good!

Part 3 – Pushing the image to the container

Creating the container image locally is beyond the scope of this blog post. However, the script (found in 2-BuildAndPushDockerImage.ps1) to log in to ACR, tag, and push the image is below.

. .\Settings.ps1

# Step 1: Log in to the Azure Container Registry
Write-Host "`n`nLogging into Azure Container Registry '${ACRName}'."
Write-Host "If this step hangs, ensure Docker is running locally."
az acr login --name $ACRName

# Step 2 Tag the local Docker image with the registry server name of your ACR
$taggedImage = "${ACRName}.azurecr.io/${imagename}:latest"
$localImageName = "mycontainerimage"
Write-Host "`n`nTagging the Docker image '${localImageName}' with '${taggedImage}'."
docker tag $localImageName $taggedImage

# Step 3: Push the local image to Azure Container Registry
Write-Host "`n`nPushing the Docker image '${taggedImage}' to ACR."
docker push $taggedImage

The script above assumes you have an image named “mycontainerimage” in your local Docker environment.

After you run the script, you should be able to find the image in the registry in the portal:

After this step, we assume that a container image is in the registry with the following URL: tncontaineregistry.azurecr.io/mycontainerimage:latest

Part 4 – Creating the App Service

This part was challenging as I spent much time on trial and error. The goal of this script is to perform the following steps:

Retrieve details about the existing managed identity.
Create the Linux App Service Plan.
Create the container App Service.
Set the identity in the App Service to access the ACR.
Verify the ACR identity.
Enable Application Logging (Filesystem).
Enable log streaming (optional).

This script, named 3-CreateAppService-UserAssigned.ps1, is a bit bigger, so we will review it step by step in detail below.

Step #1 – Getting the Managed Identity details

Firstly, we retrieve the required details about the managed Identity we created earlier.

#Run the settings script
. .\Settings.ps1

# Step 1: Get the details about the existing managed identity
Write-Host "`nRetrieving the managed identity '${identityName}'."
$identity = az identity show `
        --name $identityName `
        --resource-group $rgname `
        --output json | ConvertFrom-Json

$identityId = $identity.id
$principalId = $identity.principalId
$clientId = $identity.clientId
Write-Host "Managed identity retrieved"
Write-Host "id: ${identityId}"
Write-Host "PrincipalId: ${principalId}"
Write-Host "ClientId: ${clientId}"

Step #2 – Create the Linux App Service Plan

The next step involves creating a Linux-based App Service Plan, which is required to host and run our App Services. In this part, we don’t do anything unusual.

Write-Host "`nCreating the Linux App Service Plan"
$servicePlan = az appservice plan create `
    --name $AppServicePlan_linux `
    --resource-group $rgname `
    --is-linux `
    --sku $AppServicePlanSKU_Linux `
    --output json | ConvertFrom-Json

$servicePlanId = $servicePlan.id
Write-Host "App Service Plan created with id: ${servicePlanId}"

Step #3 - Create the container App Service

The next step is to create the container-based App Service to run on the previously created App Service Plan.

$imagePath = "${acrname}.azurecr.io/${imagename}:latest"
Write-Host "`n`nCreating the container App Service."
Write-Host "With the following image ${imagePath}"
$AppService = az webapp create `
    --name $AppServiceName_container_linux `
    --acr-use-identity `
    --plan $AppServicePlan_linux `
    --resource-group $rgname `
    --container-image-name $imagePath `
    --assign-identity $identityId `
    --output json | ConvertFrom-Json

$hostName = $AppService.defaultHostName
$appServiceID = $AppService.id
Write-Host "App Service created, id: ${appServiceID}"

Here we do a few important things:

We set the acr-use-identity flag to indicate that we want to pull the image from Azure Container Registry using a managed identity.
We assign our managed identity to the service using the assign-identity flag.

It might seem like these steps are all it takes to create a new App Service and have it pull the image from our container registry. But I was so wrong here! Now we are getting into the ugly parts☹If you run the commands above, then it will fail with this error:

In the logs, you may encounter various image pull failures, such as the following:

WARN  - Image pull failed. Defaulting to local copy if present.
ERROR - Image pull failed: Verify docker image configuration and credentials (if using private repository)
INFO  - Stopping site myapp-linux-container-dev because it failed during startup.
ERROR - DockerApiException: Docker API responded with status code=InternalServerError,
  response={"message":"Head \"https://tncontaineregistry.azurecr.io/v2/mycontainerimage/manifests/latest\":
  unauthorized: authentication required, visit https://aka.ms/acr/authorization for more information."}

The Azure App Service setup so far

So far, we have this setup:

The service has a user-assigned managed identity (found under Settings->Identity). This means we created the user and then assigned that user to the app service. The user’s lifetime is independent of the app service itself, and the identity might be associated with multiple Azure services.

So this is good!

Under Deployment -> Deployment Center, we see the following:

So, it correctly understands that we want to use managed identity, which is good! But the identity is wrong! The identity here should be set to this:

Wait, what? Do we have two different identities in our App Service?

Yes, the hidden truth is that we have two different identities to deal with and we need to specify both identities to get this to work as the image below shows:

The frustrating part is that we cannot specify the ACR identity in the az webapp create command we used earlier. If we could do that, it would have prevented a lot of pain and suffering, which we will explore later in this blog post (feel free to correct me if I am wrong here).

Step #4 – Setting the ACR identity

Here comes the most challenging part: How do we set this second identity using Azure CLI? There are various methods to accomplish this.

If you consult the documentation, you may come across several solutions, such as this one:

az resource update --ids $Webapp_Config --set properties.AcrUserManagedIdentityID=$ClientID

Or this one here:

az webapp config set --resource-group <group-name> --name <app-name> --generic-configurations '{"acrUserManagedIdentityID": "<client-id>"}'

Neither will, however, work! What is the solution?

For the first example, the location of the setting seems to have changed. A working solution is:

$property = "properties.siteConfig.AcrUserManagedIdentityID=${ClientID}"
$tmp = az resource update `
    --ids $appServiceID `
    --set $property `
    --output json | ConvertFrom-Json

And using JSON in the second example, you can fix it by doing it like this:

$data="{\""acrUserManagedIdentityID\"": \""${clientId}\""}"
$tmp = az webapp config set `
    --resource-group $rgname `
    --name $AppServiceName_container_linux `
    --generic-configurations $data `
    --output json | ConvertFrom-Json

The solution here is that you need to double-encode the JSON due to an issue in PowerShell. You can find more information about it here, here, and here.

Step #5 – Verify the ACR identity

To ensure that it is setup correctly, we can query the App Service configuration using:

$settings = az webapp config show `
    --resource-group $rgname `
    --name $AppServiceName_container_linux `
    --output json | ConvertFrom-Json
Write-Host "`nThese two settings must be set for successful ACR pull:"
Write-Host "acrUseManagedIdentityCreds='$($settings.acrUseManagedIdentityCreds)'"
Write-Host "acrUserManagedIdentityID='$($settings.acrUserManagedIdentityId)'"

The acrUseManagedIdentityCreds should be set to true and the acrUserManagedIdentityID should contain the GUID for your managed identity.

You can also verify this in the portal under App Service -> Deployment- > Deployment center:

Great, now the ACR identity has been successfully set!

Step #6 – Enable Application Logging (Filesystem)

To help with debugging our container, we can enable both the application and container logs to be sent to the filesystem using:

$tmp = az webapp log config `
      --name $AppServiceName_container_linux `
      --resource-group $rgname `
      --application-logging filesystem `
      --docker-container-logging filesystem `
      --level verbose `
      --output json | ConvertFrom-Json

*Please note that these settings may need to be adjusted when running in a production environment.*

Step #7 – Enable log streaming (optional)

Adding the following command at the end of an Azure deployment script enables real-time monitoring of application logs to start after the script is completed. This allows for immediate detection and troubleshooting of any issues during deployment. This is useful for local debugging!

# Optionally enable this to run log stream for debugging purposes
az webapp log tail `
        --name $AppServiceName_container_linux `
        --resource-group $rgname

Are we done?

If you run the above script, your container should eventually appear! Great! It works! However, can we improve it?

The current developer experience is not good, because the current experience for the first deployment is like this:

Upon attempting to access your new deployment as a developer, you will initially encounter the application error page. This page will remain visible until the container is successfully pulled from the registry, which could take 2-5 minutes.

This lack of visibility creates uncertainties such as:

Is the deployment broken?
Is my application broken?
Is something else broken?
Or is it simply busy with the deployment process?

How can we enhance this experience?

Improving the script

One option that I came up with is to do the following:

First deploy the built-in .NET Core 8 runtime instead of my container.
Set the ACR Identity as we did above.
Replace the runtime with my custom container image.

By doing this change, we will get this user experience instead: This user experience is much more user and developer-friendly than the previous approach. The script that implements this is named 4-CreateAppService-UserAssigned-version2.ps1 and it contains the following two changes:First, we create the App Service using:

# Step 3: Create the App Service
Write-Host "`n`nCreating the App Service with the default runtime 'DOTNETCORE:8.0'."
$AppService = az webapp create `
    --name $AppServiceName_container_linux `
    --acr-use-identity `
    --plan $AppServicePlan_linux `
    --resource-group $rgname `
    --runtime 'DOTNETCORE:8.0' `
    --assign-identity $identityId `
        --output json | ConvertFrom-Json
$hostName = $AppService.defaultHostName
$appServiceID = $AppService.id
Write-Host "App Service created, id: ${appServiceID}"

The key difference is that we replaced —container-image-name with —runtime ‘DOTNETCORE:8.0’. This will start up the App Service with a more friendly welcome message. Then, at the end of the script, after we have properly set up the ACR identity, we switch to use the container image instead by using this command:

$imagePath = "${acrname}.azurecr.io/${imagename}:latest"
Write-Host "`n`nChange the service to use the container ${imagePath}."
az webapp config container set `
  --name $AppServiceName_container_linux `
  --resource-group $rgname `
  --container-image-name $imagePath `
  --output json | ConvertFrom-Json

The only drawback is that the total deployment time will be slightly longer.

Tips and tricks

In your logs, you might find the Kudulite logo displayed when the service starts up, like this:

How can you do that yourself?

To generate a logo, visit this site and create your own logo. Then I simply print it out to the console in start startup, like this:

Log.Information("AzureRover starting up");
Log.Information("");
Log.Information(@"       _____                             __________                          ");
Log.Information(@"      /  _  \ __________ _________   ____\______   \ _______  __ ___________ ");
Log.Information(@"     /  /_\  \\___   /  |  \_  __ \_/ __ \|       _//  _ \  \/ // __ \_  __ \");
Log.Information(@"    /    |    \/    /|  |  /|  | \/\  ___/|    |   (  <_> )   /\  ___/|  | \/");
Log.Information(@"    \____|__  /_____ \____/ |__|    \___  >____|_  /\____/ \_/  \___  >__|   ");
Log.Information(@"            \/      \/                  \/       \/                 \/       ");
Log.Information("");

This will show up in the log like this:

Isn’t this a useful thing to have? Don’t you agree? (AzureRover is just the name of an internal project)

Summary and the scripts

Getting this to work was a painful experience and hopefully, this post can help others to have a much smoother process.The complete scripts can be found here

A separate blog post will cover how this can be slightly simplified using a system-assigned managed identity.

Feedback, comments, found any bugs?

Let me know if you have any feedback, if I missed anything, or if you have any bugs/typos. You can find my contact details here.

Discovering .NET codebases using code coverage and NCrunch

Tore Nestenius — Thu, 04 Jul 2024 00:00:00 GMT

Exploring and discovering unfamiliar codebases is always a challenge. In this blog post, I will introduce a novel way to explore a new codebase by looking at the code coverage using NCrunch.NET.

Background

As a developer, you’re often challenged to understand new libraries; you ask: ‘how does it work’, ‘what makes it tick?’, what parts are involved in this operation?’

I’ve found that usually just reading the documentation or doing tutorials isn’t enough to really grasp how a given code or library works. The goal is actually to get a good mental model for how a codebase works.

This is especially true when I create training material and teaching concepts for my training classes at tn-data.se

Example: The library to understand

In my case, I wanted to understand how the Microsoft Authentication Library works under the hood. We can use this library to acquire access tokens from Azure Entra ID using OpenID-Connect.

The most obvious option is to step through the code using the debugger, which always works. But what are the alternatives? Can they be faster and more insightful?

The first step I usually take is to download the library’s source code and create my own “class library” based on it. This allows me to step through the code, explore it, and introduce debug statements more easily. In my case, I did this by downloading the code from https://github.com/AzureAD/microsoft-authentication-library-for-dotnet

I find having the source code locally is really helpful because I can easily step through the code and add debug statements or minor modifications to improve my understanding of the codebase. I used this technique when I wrote the DefaultAzureCredentials Under the Hood blog post.

Exploring the code base

After creating the class library locally, the next step is analyzing its structure. Where should I start?

An obvious starting point for exploring an existing code base is to use NDepend . NDepend is an incredible static analysis tool that helps monitor and improve the quality of .NET code through in-depth reporting, code metrics, and visualizations.

The diagram below shows the complexity of the library that we are currently investigating.

Using NDepend, I can quickly drill down into the structure of this code library and analyze its dependencies, structure, and more. This provides a static view of the codebase that makes understanding complex and unfamiliar systems much easier.

This is a good starting point, but what else can I do and how can code coverage help me to understand a codebase?

Introducing NCrunch - the Live Testing Tool for .NET

NCrunch is an automated continuous testing tool for .NET that integrates with Visual Studio and JetBrains Rider. It provides real-time code quality and performance feedback by running tests concurrently as you type. It tracks code coverage, collects performance metrics, and displays exceptions inline, making test-driven development fun!

But wait a minute, this is a code-coverage tool. How can this tool help me understand a codebase better?

Now typically, you run all your tests against your application and track the code coverage using NCrunch or similar tools.

From these runs, you can get the code coverage metrics per project, for example:

This is all good, but I don’t want the total code coverage when exploring and understanding a new codebase; I want something else!

Can I use NCrunch in some other way to help me discover a new codebase?

What if I only have one single test? What would that enable?

Using NCrunch with just one test

Code coverage with just one test might seem ridiculous, but let’s explore this scenario.

Having just one test would allow me to see the entire code path through the application for a specific operation like this:

But wait a minute? A code coverage tool only returns me the coverage numbers. Like this?

How would this help me to understand a codebase?

The advantage of NCrunch is that it tracks my code coverage in real-time and visually shows the coverage in my editor, like this:

Simple code coverage example

Let’s look at a simple example. Let’s say we have this calculator:

public class Calculator
{
    public int MagicAdd(int x, int y)
    {
        if (x > 0 && y > 0)
        {
            int result = x + y;
            PrintAnswer(result);
            return result;
        }
        else
        {
            return 0;
        }
    }

    private void PrintAnswer(int result)
    {
        if (result > 0)
            Console.WriteLine($"Positive: {result}");
        else
            Console.WriteLine($"Negative: {result}");
    }
}

Let’s add a single simple test:

public class UnitTest1
{
    [Fact]
    public void Test1()
    {
        var sut = new Calculator();

        int result = sut.MagicAdd(10, 20);
    }
}

If we enable NCrunch on this project, we will see the following code coverage:

Using the green and black dots, I can see which part of the codebase was executed when I did this operation.

Ok, this is so cool! But can we do even better?

Runtime Data Inspection (RDI)

The Runtime Data Inspection (‘RDI’) is a real-time analysis system in NCrunch that brings runtime data values and detailed code control flow inline into the IDE. You can read more about this feature here.

If we enable this feature in our simple example, we get this result:

When enabled, I can get a visual representation of the code execution while editing my code.

Clicking on the green marker above a given variable allows me to view its value, as shown below:

Hotspots are marked in the left column, and the execution of a given statement is displayed, allowing you to pinpoint bottlenecks in your application.

You can read more about the Runtime Data Inspection (RDI) features here.

Back to MSAL.NET

So back to my example with MSAL.NET. Using this technique, I can write a unit test for one specific usage of this library like this:

[Fact]
public async Task MyTest()
{
    string tenantID = "xxxxxxxxxxxxxxx";
    string clientID = "xxxxxxxxxxxxxxx";
    string secret = "xxxxxxxxxxxxxxx";
	
    string apiUrl = "https://graph.microsoft.com/";
	
    var authority = new Uri($"https://login.microsoftonline.com/{tenantID}");
	
    var app = ConfidentialClientApplicationBuilder.Create(clientID)
                                        .WithClientSecret(secret)
                                        .WithAuthority(authority)
                                        .Build();
    
	var scopes = new string[] { $"{apiUrl}.default" };
	
    var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
    
	var accessToken = result.AccessToken;
}

Then, I can enable the RDI overlay and easily navigate the codebase without running the debugger!

When visualizing the content of a given variable, NCrunch will call ToString on that given type.

To see what is inside the variable, you can change the type to a record type or manually override ToString. When overriding ToString, it can look like this:

Further improvements can be made by tweaking the RDI data limits. You can read more about this here.

Conclusions

In all, using NCrunch for code coverage and real-time data inspection simplifies understanding new codebases. With this tool, developers can see code execution and inspect data as they write, making learning and understanding the codebase easier. This method is efficient and makes exploring complex codebases more accessible and engaging.

NDepend also works well with NCrunch; for example, you can import NCrunch code coverage data into NDepend for further analysis. Examples of what you can extract from this information can be found here: , here and here.

These are two tools that I highly recommend every developer should have in their toolbox.

Resources

Feedback, comments, found any bugs?

Let me know if you have any feedback, anything I missed or any bugs/typos. You can find my contact details here.

DefaultAzureCredentials Under the Hood

Tore Nestenius — Thu, 18 Apr 2024 00:00:00 GMT

The DefaultAzureCredentials is key for using Azure services, but how exactly does it work and when should you use it? In this post, we’ll break down how it operates, its challenges, and other ways to access Azure services. This guide will help you get a clearer picture of how to handle Azure authentication simply and effectively.

Authenticating to Azure

When an application wants to access resources in Azure such as storage or databases, it needs to authenticate itself. To do this, the application must obtain an access token from Entra ID. This token allows the application to securely access resources in Azure, such as your Azure Storage Account.

Alternative ways to access resources exist, such as using Shared Access Signature (SAS) tokens, but that is beyond the scope of this blog post.

For example, to access Azure BlobStorage, a TokenCredential is required during client creation. This ensures secure access by authorized users. Here’s an example of that:

TokenCredential credentials = ??HowToCreate??; var client = new BlobServiceClient(new Uri("https://myblogstorage.blob.core.windows.net"),                                    credentials);

What does the TokenCredential class represent?

The TokenCredentials type in C# is an abstract base class that contains two methods to request an access token:

/// <summary>
/// Represents a credential capable of providing an OAuth token.
/// </summary>
public abstract class TokenCredential
{
    /// <summary>
    /// Gets an Azure.Core.AccessToken for the specified set of scopes.
    /// </summary>
    /// <returns>A valid Azure.Core.AccessToken.</returns>
    public abstract ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext,
                                                         CancellationToken cancellationToken);

    public abstract AccessToken GetToken(TokenRequestContext requestContext,
                                         CancellationToken cancellationToken);
}

Microsoft provides many types that implement this abstract class, including:

var c1 = new AuthorizationCodeCredential(tenantId: "",
                                         clientId: "",
                                         clientSecret: "",
                                         authorizationCode: "");

var c2 = new AzureCliCredential();

var c3 = new AzureDeveloperCliCredential();

var c4 = new AzurePowerShellCredential();

var c5 = new ChainedTokenCredential();

var c6 = new ClientAssertionCredential(tenantId: "",
                                       clientId: "",
                                       assertionCallback: x => Task.FromResult(""));

var c7 = new ClientCertificateCredential(tenantId: "",
                                         clientId: "",
                                         clientCertificatePath: "");

var c8 = new ClientSecretCredential(tenantId: "",
                                    clientId: "",
                                    clientSecret: "");

var c9 = new DefaultAzureCredential();

var c10 = new DeviceCodeCredential();

var c11 = new EnvironmentCredential();

var c12 = new InteractiveBrowserCredential();

var c13 = new ManagedIdentityCredential();

var c14 = new OnBehalfOfCredential(tenantId: "",
                                   clientId: "",
                                   clientSecret: "",
                                   userAssertion: "");

var c15 = new SharedTokenCacheCredential();

var c16 = new UsernamePasswordCredential(username: "",
                                         password: "",
                                         tenantId: "",
                                         clientId: "");

var c17 = new VisualStudioCodeCredential();

var c18 = new VisualStudioCredential();

var c19 = new WorkloadIdentityCredential();

What do all these TokenCredentials do?

Each TokenCredential type employs its own approach to acquiring the access token needed to access services in Azure. Whether searching for credentials in your system or launching a separate program, the key aim is to obtain this token safely and effectively, ensuring smooth and reliable access to Azure.

For example, the EnvironmentCredential type will look for credentials in one of these sets of environment variables:

ClientSecret based
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET
UserName/Password based
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_USERNAME
- AZURE_PASSWORD
Certificate based
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_CERTIFICATE_PATH
- AZURE_CLIENT_CERTIFICATE_PASSWORD

Then it will use these credentials to try to acquire an access token from Entra ID.

VisualStudioCredential is another type that attempts to launch Microsoft.Asal.TokenService.exe, which is an application located in this folder:

C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\AsalTokenService

It is an executable that manages token-based authentication for Microsoft services. It’s essential for enabling secure user access to Microsoft Azure and Office 365, and it is also utilized by Visual Studio to authenticate users with Microsoft accounts. This component facilitates secure single sign-on and integrates with Entra ID.

This means that the BlobServiceClient shown before accepts any of the above credentials. For example:

var blobUri = new Uri("https://myblogstorage.blob.core.windows.net");

var client1 = new BlobServiceClient(blobUri, new AzureCliCredential());
var client2 = new BlobServiceClient(blobUri, new AzureDeveloperCliCredential());
var client3 = new BlobServiceClient(blobUri, new EnvironmentCredential());
var client4 = new BlobServiceClient(blobUri, new WorkloadIdentityCredential());

TokenCredentials in practice

We have a problem: depending on where our app executes, we need to use different TokenCredentials, depending on where it runs. This means that our code might look something like this:

TokenCredential credentials = null;
switch (environment)
{
    case "dev-visualstudio":
        credentials = new VisualStudioCredential();
        break;
    case "dev-visualstudiocode":
        credentials = new VisualStudioCodeCredential();
        break;
    case "production":
        credentials = new ManagedIdentityCredential();
        break;
    default:
        credentials = new AzurePowerShellCredential();
        break;

This works, but it’s hard to maintain; especially if we want to add more options in the future, like using Azure CLI or WorkloadIdentity with Kubernetes. We need a simpler approach that can work across different environments.

Introducing DefaultAzureCredential

To solve the above problem, Microsoft introduced the DefaultAzureCredential type.
How does it work?

It contains a predefined list of TokenCredential types, which it calls in a specific sequence. DefaultAzureCredential systematically checks each one on this list until it successfully finds a matching set of credentials in your environment, as shown in the following picture:

By using this credential type instead of the others, you don’t need to worry about having to specify what credentials to use, as shown in this example below:

var client = new BlobServiceClient(
             new Uri("https://myblogstorage.blob.core.windows.net"),
             new DefaultAzureCredential());

The above code will automatically work well in most environments because it tries to locate a valid set of credentials and then retrieve a valid access token.

What happens if DefaultAzureCredentials can’t find any credentials?

The first thing you notice is that it is slow! It will take 3-8 seconds to execute all the TokenCredentials on a machine without credentials.

An exception is thrown when it can’t find any valid credentials, and you can see the details in the debugger foreach failed attempt:

There is a built-in option to disable specific TokenCredentials, like this:

var options = new DefaultAzureCredentialOptions
{
    ExcludeAzureCliCredential = true,
    ExcludeVisualStudioCodeCredential = true
    //..
};

var cred = new DefaultAzureCredential(options);
...

Caching of the access token in DefaultAzureCredentials

It’s best to create a single instance of DefaultAzureCredential and reuse it throughout your application. This approach is more efficient because it leverages the credential’s internal token cache, reducing the need for repeated authentication calls.

For example:

// Create a shared DefaultAzureCredential instance
var sharedCredential = new DefaultAzureCredential();

// Use this shared instance wherever needed
var client1 = new BlobServiceClient(
    new Uri("https://example.blob.core.windows.net"),
    sharedCredential);

var client2 = new SecretClient(
    new Uri("https://example.vault.azure.net"),
    sharedCredential);

…

What does the access token look like?

A sample access token can look like this:

{
  "aud": "https://storage.azure.com/",
  "iss": "https://sts.windows.net/567d82a1-7f61-4da2-b955-xxxxxxxxxxxx/",
  "iat": 1712047403,
  "nbf": 1712047403,
  "exp": 1712051303,
  "aio": "E2NgYKh17fZg9vvfwCmWxW+7xxxxxx==",
  "appid": "9bfc7d58-9841-415c-9b60-xxxxxxxxxxxx",
  "appidacr": "1",
  "idp": "https://sts.windows.net/567d82a1-7f61-4da2-b955-xxxxxxxxxxxx/",
  "oid": "1e7e2541-1297-4e1a-8b15-xxxxxxxxxxxx",
  "rh": "0.AQwAoYJ9VmF_ok25VdMkTqbpdoGmBuTU86hCkLxxxxxxxxxxxx.",
  "sub": "1e7e2541-1297-4e1a-8b15-xxxxxxxxxxxx",
  "tid": "567d82a1-7f61-4da2-b955-xxxxxxxxxxxx",
  "uti": "NpJBNp_iWUql96nbQP4xQA",
  "ver": "1.0",
  "xms_tdbr": "EU"
}

The access token above has a lifetime of 65 minutes, and the library will be in charge of refreshing it when needed.

How do I know which credential was used?

You might have several credentials saved on your computer. Sometimes, this can cause a problem where the wrong one gets used, leading to access issues that can be tricky to figure out. Enabling logging is one approach to knowing which one was used.

But digging through the logs is perhaps not the most optimal approach. Unfortunately, it does not provide any official other way to tell which credential was actually used. However, using some reflection magic, we can extract this information using the following hack:

TokenCredential? GetSelectedCredentials(DefaultAzureCredential? credential)
{
    // This is a hack to get the selected token from DefaultAzureCredential.
    // The goal is to get the value from this private field found inside DefaultAzureCredential:
    //private readonly AsyncLockWithValue<TokenCredential> _credentialLock;

    try
    {
        var credType = credential?.GetType();
        
        if (credType != null)
        {
            var _credentialLockField = credType.GetField("_credentialLock", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
            if (_credentialLockField != null)
            {
                var _credentialLock = _credentialLockField.GetValue(cred);
                var _credentialLockType = _credentialLock?.GetType();
                if (_credentialLockType != null)
                {
                    var _valueField = _credentialLockType.GetField("_value", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
                    if (_valueField != null)
                    {
                        var selectedCredential = _valueField.GetValue(_credentialLock);
                        // Use selectedCredential here
                        return selectedCredential as TokenCredential;
                    }
                }
            }
        }

        return null;
    }
    catch (Exception ex)
    {
        Console.WriteLine("Failed to get selected credential");
        return null;
    }
}

The above method can then be used like this:

var credentials = new DefaultAzureCredential();

TokenCredential? selectedCredential = GetSelectedCredentials(cred);

Console.WriteLine("selectedCredential " + selectedCredential.GetType().Name);

What are the problems with DefaultAzureCredential?

While it is highly convenient and user-friendly, it also has its drawbacks. A notable issue arises in debugging: pinpointing which one was used becomes challenging if it selects an incorrect or unexpected credential.

Pro tip #1: I have created a handy open-source Cloud Debugger for Azure which can help with this and more. I also teach devs how to use it in my upcoming course ‘Introduction to Azure for Developers’.

Pro tip #2: Stay Updated with the Latest .NET News & Azure

Upskill With Me: Courses, Workshops & Training

What are the alternatives to DefaultAzureCredential?

An alternative is the ChainedTokenCredential type. It functions similarly to DefaultAzureCredential, with the key difference being that it starts with an empty list of TokenCredentials. With ChainedTokenCredential, you can add only the credential types relevant to your needs in the order that works best for you.

This approach can be particularly advantageous for production environments, as it puts you in complete control and limits the credentials to only those you actively use.

For instance, you could set it up like this:

var cred = new ChainedTokenCredential(
    new EnvironmentCredential(),
    new ManagedIdentityCredential(),
    new VisualStudioCodeCredential());
…

Logging and diagnostics

A simple way to get insights into what happens under the hood is to add the following code to the start of your application:

var listener = new AzureEventSourceListener((e, message) =>
    {
        Console.WriteLine(e.EventSource.Name);
        if (e.EventSource.Name.StartsWith("Azure"))
        {
            Console.WriteLine($"{DateTime.Now} {message}");
        }
    },
    level: EventLevel.Verbose);

var totalTimeSw = new Stopwatch();
totalTimeSw.Start();

This allows you to capture the internal events produced by the Azure libraries, which can give you valuable insights into their inner workings.

Final gotcha

A common issue encountered with these credential helpers revolves around the TenantId. Often, difficulties with these types stem from a missing TenantId. To mitigate this, the TenantId can typically be specified through an optional options object or by setting environment variables. For instance, when using VisualStudioCredential:

var options = new VisualStudioCredentialOptions()
{
    TenantId = "xxxxx"
};

var credentials = new VisualStudioCredential(options);

Summary

Writing this blog post has been a great learning experience for me. It’s helped me better understand TokenCredential types, especially about when to use DefaultAzureCredential and ChainedTokenCredential.

I gained deeper insights by downloading the Azure Identity source code from GitHub and turning it into my own class library. With this in place, I could add my own logging and diagnostic code. These additions really helped me get a better grasp of how everything functions.

Feedback, comments, found any bugs?

Let me know if you have any feedback, anything I missed or any bugs/typos. You can find my contact details here.

Azure Cloud Development Services
Developer Coaching (IdentityServer, .NET, ASP.NET Core, and Azure)
Duende IdentityServer Consulting Services
.NET Development Services

Introducing the Data Protection API Key Ring Debugger

Tore Nestenius — Tue, 12 Mar 2024 00:00:00 GMT

When you’re working with the Data Protection API in ASP.NET, you quickly notice how powerful and simple this service is. At the same time, you have little insight into how it operates. In this blog post, I will introduce a simple debugger I wrote to better demonstrate how it operates in my training classes.

Head over to my previous blog post, Persisting the ASP.NET Core Data Protection Keys Ring in Azure Key Vault, for details about how this API works.

Introducing the DPAPI Debugger

The debugger is implemented as a plain ASP.NET Core MVC Controller alongside a corresponding razor view page that will display some of the inner details of the DPAPI.

On a high level, the architecture of the part of DPAPI that we are interested in, looks like this:

The encryptor and repository being used are not public information, so to extract this information, we used the new UnsafeAccessor attribute introduced in .NET 8. You could get the same information using reflection if you don’t want to use this approach.

[UnsafeAccessor(UnsafeAccessorKind.Method, Name = "get_KeyEncryptor")]
extern static IXmlEncryptor GetKeyEncryptorField(XmlKeyManager @this);

[UnsafeAccessor(UnsafeAccessorKind.Method, Name = "get_KeyRepository")]
extern static IXmlRepository GetKeyRepositoryField(XmlKeyManager @this);

Creating and revoking ASP.NET Core Data Protection keys

The debugger allows you to create a new key and revoke all the existing keys as well.

Viewing the currently used encryptor and repository

The debugger will show which encryptor and XmlRepository that is currently being used in your application.

Upskill With Me: Courses, Workshops & Training

Viewing the raw persisted keys

This view will show you what the key ring looks like when stored in a suitable system. We can see here, for example, that a key from Azure Key Vault encrypts the keys.

Viewing the unprotected data protection keys

In the final view, you can see more details about the keys, including expiration time and if they are revoked.

Source code

A sample implementation and example project can be found in my GitHub repository here. Feel free to submit a pull request if you have ideas for improving the code.

Conclusions

Writing and using this debugger has given me a better insight into how the DPAPI works and operates and hopefully it can help you too, to get a better understanding and help you to troubleshoot DAPAI problems.

Feedback, comments, found any bugs?

Let me know if you have any feedback, anything I missed or any bugs/typos. You can find my contact details here.

Persisting the ASP.NET Core Data Protection Key Ring in Azure Key Vault

Tore Nestenius — Thu, 22 Feb 2024 00:00:00 GMT

The ASP.NET Core Data Protection API (DPAPI) is an essential service in ASP.NET Core that is often overlooked. This post will give an overview of what it does and how we can persist the encryption keys in Azure Key Vault.

The API’s main purpose is to encrypt and decrypt data. For example, it is used to:

Protect the various cookies issued by ASP.NET Core.
I blogged about how the cookies are protected in the Exploring what is inside the ASP.NET Core cookies blog post.
Protecting the OpenID Connect state and nonce parameters.
You can read about these two parameters in my blog post here.

The API is primarily designed to encrypt and secure short-lived data (from minutes to months), but it can also be used to encrypt data for long-term storage if needed.

How can you use the Data Protection API to protect your own data?

The API is typically used in ASP.NET Core applications, but nothing prevents you from using it in, for example, a console application. Just add the Microsoft.AspNetCore.DataProtection.Extensions NuGet package, and then you can start using it right away.

Here is a sample console application using the Data Protection API to protect and unprotect a string:

// Initialize the Data Protection system and store the keys c:tempkeys
var provider = DataProtectionProvider.Create(new DirectoryInfo(@"c:tempkeys"));

// Create a data protector
var protector = provider.CreateProtector("MyAppName");

string encryptedData = protector.Protect("Hello DPAPI");
string decryptedData = protector.Unprotect(encryptedData);

Console.WriteLine(encryptedData); //CfDJ8PEJDb99-ddAhkM_GeKgmn1fcrWF9LGi10rTkU1f7IbW2y
                                  //282ISIXZTgBBy_cL9iQ2RzxCyKbLlku7PlWVcTJw11NylWVCDq
                                  //kdpjmsbm9U1chfg-rYUeBNFGwB-Q5q9b1w
                                  
Console.WriteLine(decryptedData); //Hello DPAPI

Interestingly, the API only works with strings, making it very easy to use. If you need to protect binary data, you can base64 encode it before you protect it.

How to use the Data Protection API in ASP.NET Core?

Using it in ASP.NET Core is also straightforward, as the Data Protection API is typically included by default in most ASP.NET Core projects. To use it in a controller, you can ask the Dependency Injection container for an instance of IDataProtectionProvider. Like this:

public class HomeController : Controller
{
    private readonly ILogger<HomeController> _logger;

    public HomeController(ILogger<HomeController> logger,
                          IDataProtectionProvider protectionProvider)
    {
        _logger = logger;
        
        // Create a data protector
        var protector = protectionProvider.CreateProtector("MyAppName");
        var encryptedData = protector.Protect("Hello DPAPI");
        var decryptedData = protector.Unprotect(encryptedData);
        
        Console.WriteLine(encryptedData);
        //CfDJ8Dsx1cA547pJnoAz-iXx9XYVi8GMYBHcEU9ceuB4Ep75Yr1I4pX4Rw3DWIE4H4cigg_
        //-NvixoAoR5vl641cT-FEagETLBRoecfX011zsX7aPqf4OjxGNpCh-Bk6qfxgphw

        Console.WriteLine(decryptedData); //Hello DPAPI
    }
    ... 
}

The Data Protection Key Ring

To protect the data, DPAPI uses an encryption key; if no key is found, it will automatically create one for us. DPAPI will introduce new keys regularly (default once every 90 days), meaning many keys will be involved over time. All these keys are stored in a key ring, and this key ring contains both the active key and the past keys.

You need to keep the old keys around if you want to be able to decrypt already encrypted data.

Persisting the Data Protection key King

The key ring should be persisted somewhere outside of your application, and there are many ready-made options to choose from, many are provided by Microsoft and the community.

However, one missing option is Azure Key Vault. In this post, we’ll write a sample provider for Azure Key Vault to showcase how simple it is to implement.

Why store the Data Protection Key Ring in Azure Key Vault?

Most services typically require some or all of the following items to operate: HTTPS/TLS certificates, the Data Protection Key Ring (DPAPI), encryption and signing keys, as well as secrets and configuration settings:

Azure Key Vault can securely store all of these items, helping to streamline your infrastructure and simplify key management.

It can even create some items for you; for example, if you use services like IdentityServer, it can generate token signing keys. This post will focus on persisting the key ring in Azure Key Vault.

Encrypting the keys in the key ring

Optionally, the keys inside the key ring can be encrypted at rest (when stored), and there is already support for that provided by using the Azure.Extensions.AspNetCore.DataProtection.Keys Nuget package from Microsoft. However, storing the key ring and the encryption key in the same location might be overkill.

The ASP.NET Core Data Protection API and security

Don’t forget to always ensure that you use separate key rings for your different environments so that if one of the key rings is compromised, it can’t be used against the other environments.

What does a key in the Data Protection key ring look like?

The key ring is by default represented as an XML document, and here’s a sample unencrypted key when it is stored in Azure Key Vault:

<root>
  <key id="66533236-1e0f-40cb-b6ca-3cdb3f942331" version="1">
    <creationDate>2024-02-12T15:47:21.2522781Z</creationDate>
    <activationDate>2024-02-12T15:47:19.8787424Z</activationDate>
    <expirationDate>2024-05-12T15:47:19.8787424Z</expirationDate>
    <descriptor deserializerType="Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.
    ConfigurationModel.AuthenticatedEncryptorDescriptorDeserializer, Microsoft.AspNetCore.DataProtection, 
    Version=8.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60">
      <descriptor>
        <encryption algorithm="AES_256_CBC" />
        <validation algorithm="HMACSHA256" />
        <masterKey p5:requiresEncryption="true" xmlns:p5="http://schemas.asp.net/2015/03/dataProtection">

          <value>xtlj8GlTE2t4OeoabEBG7Ry8XVXYzaTvxsM4UPs8kQYlepNM2/6FsmxRVE+BavFKj3ULwAiuqKmyC47QmCPLYw==</value>
        </masterKey>
      </descriptor>
    </descriptor>
  </key>
</root>

You can see above that the key is not encrypted at rest.

An example of a key ring where the keys are encrypted using a separate key in Azure Key Vault can look like this:

<root>
  <key id="77f04bd2-3394-4e2c-a101-d47a0cb9f04c" version="1">
    <creationDate>2024-02-13T08:30:51.9976822Z</creationDate>
    <activationDate>2024-02-13T08:30:50.8851358Z</activationDate>
    <expirationDate>2024-05-13T08:30:50.8851358Z</expirationDate>
    <descriptor deserializerType="Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel
      .AuthenticatedEncryptorDescriptorDeserializer, Microsoft.AspNetCore.DataProtection, 
      Version=8.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60">
      <descriptor>
        <encryption algorithm="AES_256_CBC" />
        <validation algorithm="HMACSHA256" />
        <encryptedSecret decryptorType="Azure.Extensions.AspNetCore.DataProtection.Keys.AzureKeyVaultXmlDecryptor, 
        Azure.Extensions.AspNetCore.DataProtection.Keys, Version=1.2.2.0, Culture=neutral, 
        PublicKeyToken=92742159e12e44c8" xmlns="http://schemas.asp.net/2015/03/dataProtection">
          <encryptedKey xmlns="">

            <kid>https://dpapikeyvault.vault.azure.net/keys/MyDPAPIKey/c07cda675a3446f6a752a1e50c17c0c7</kid>
            <key>ZSWcsd302ouGxLFtx26MeuioxCRFhcwKxNTK7qL6TrG0d7GoiHV2B/Xtjr9CKNPgwkIUXv/mhTb/+lvwL15i/hh4kyYAPD
            /OftQjaHy3RRvHSTtkWZiCivyQr6PD8LbbZ4Wkznayzla60Ulwi+1TGhmUaGMTvpSo1mERVCK8iUEU7l8k1BCvJbEGn721nYvdB
            ZQlBraPYNLaRDxQ3JCi6Brl4UImQwetByip2YPDWcKOMVMTH+JliVGrdZclLHk97E5MCIq1G4l+C5urQ6c8C1h+vJYQJ+5581eu
            bGLXbC5pATa5bY8xCGObVj/6mZ5k9poOo+iKOU2OzL0N1h/leA==</key>
            <iv>M/Jh3zr94JYs2BYikdmJiA==</iv>
            <value>3lR+foXTx4awY5KbSNzZLGXfxtu0M9vaN0gc7XBDUwwbtcDloQyuHLI9T7l/FDmtdi/KO9pas1V5VBq/yVSdufmu6JnQm
            VIA8oHDodBD+T7+h5pM9zfP6Z6n7LcMuAxFv4T9PUEZIpThVB2dlC3pW5RNEWuFYP6oMPbk5RZw8V6dSydpBr6GWZXLUuFB3oAJB
            7+R/VCPtZypdYElZPVywdoEnLYarsoMuloqYAFz+3oP/y1XmHOZx5z1uYBw5B/3r851mYm9r7B5qU5LEV2Jq5CDMUbHgZAmca1cx
            uM5LKrBim74hYY03vtYulfxvae76aI2qNs91LmUfQTZklMskY+WA3AbEt0aUCo49n5mA+Ywffh1vpukoYRiC+7F1uC82Fea1GO0m
            HeGYzhHC517xbgQSON0PS3QxpOqkr8b7f8=</value>
          </encryptedKey>
        </encryptedSecret>
      </descriptor>
    </descriptor>
  </key>
</root>

Does Azure Key Vault Have Limitations?

Yes, Azure Key Vault has some limitations around storing the key ring as a secret. The two main things to keep in mind are:

We should store the key ring as one big secret in AKV, not the keys individually. This is to avoid making too many requests to AKV.
There is an upper size limitation of around 25KB for a secret, meaning that there is an upper limit on the number of keys to keep in the key ring. My calculation estimates that this gives us enough space to hold about 12-13 keys, which should be sufficient for the most common use cases. This might, however, be a problem if you want to persist all the keys long-term and rotate them or revoke them regularly. Applying compression could increase this number.

Implementing the Azure Key Vault store

Implementing a key-ring store is very simple; all you need to do is implement the following interface:

/// <summary>
/// The basic interface for storing and retrieving XML elements.
/// </summary>
public interface IXmlRepository
{
    /// <summary>
    /// Gets all top-level XML elements in the repository.
    /// </summary>
    IReadOnlyCollection<XElement> GetAllElements();

    /// <summary>
    /// Adds a top-level XML element to the repository.
    /// </summary>
    /// <param name="element">The element to add.</param>
    void StoreElement(XElement element, string friendlyName);
}

A sample implementation and example project can be found in my GitHub repository here . Feel free to submit a pull request if you have ideas for improving the code.

Conclusions

Using Azure Key Vault to store the key ring is possible and implementing the persitence layer to support this is straight foward.

Feedback, comments, found any bugs?

Let me know if you have any feedback, anything I missed or any bugs/typos. You can find my contact details here.

Improving ASP.NET Core Security By Putting Your Cookies On A Diet

Tore Nestenius — Mon, 22 Jan 2024 00:00:00 GMT

In this blog post, we’ll explore a practical way to enhance the security of your ASP.NET Core applications by reducing the size of authentication cookies. Large cookies can lead to performance issues and security risks, especially when using OpenID Connect or storing sensitive information. By implementing these optimizations, you can keep your application secure, streamlined, and efficient.

**Problem #1 - Large cookies in ASP.NET Core

When you work with authentication in ASP.NET Core, you typically use the Cookie handler to sign in the user. As a result of the sign-in, it will issue an authentication session cookie and store it in the browser.

However, It is crucial to manage the size of this cookie to prevent it from becoming too large. If you add OpenID Connect support, the cookie can grow even more. The code below shows a typical setup for using OpenID Connect together with the Cookie handler in ASP.NET Core:

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = "cookie";
    options.DefaultChallengeScheme = "oidc";
})
.AddCookie("cookie", o =>
{
    //...
})
.AddOpenIdConnect("oidc", o =>
{
    o.Authority = "https://myidentityserver.com";
    o.ClientId = "client";
    o.ClientSecret = "mysecret";
    o.ResponseType = "code";
    o.Scope.Clear();
    o.Scope.Add("openid");
    o.Scope.Add("profile");
    o.Scope.Add("email");
    o.Scope.Add("offline_access");
    o.GetClaimsFromUserInfoEndpoint = true;
    o.SaveTokens = true;
    //...
});

When the user has authenticated successfully at the authorization server, the user is redirected back to the OpenIdConnect handler. As a result of this redirect, it will issue an AuthenticationTicket [https://github.com/dotnet/aspnetcore/blob/main/src/Http/Authentication.Abstractions/src/AuthenticationTicket.cs\]. This ticket contains the following information:

It will then ask the Cookie handler to sign in the user represented in this ticket. When it signs in the user, it encrypts this ticket and stores it in the session cookie, as shown in the picture below:

Bild:

When we set the SaveTokens flag to true, we ask the OpenIdConnect handler to include the received tokens (id, access, refresh) inside the AuthenticationProperties object.

This means that the following is included in the authentication session cookie:

Storing all this data may lead to a significant increase in its size.

We should remember that cookies have a maximum size limit of about 4096 bytes. To learn more about cookie limitations, visit the Browser Cookie Limits page and test it yourself.

When the cookie grows too large, the payload is broken up into multiple cookies, as shown in the image below:

(Yes, the cookie example above is a bit extreme ????)

Internally, the ChunkingCookieManager oversees this.

Having too many large cookies will affect the overall web performance because all of these cookies will be included in every request to the server. With HTTP/2 and HTTP/3, large cookies are slightly less of a performance problem due to the various internal performance optimizations that they bring.

We will look at how we can reduce the size of the cookies later in this blog post.

**Problem #2 - Signout in ASP.NET Core

In a typical application, when you sign in the user, the issued cookie contains everything about the user, including the ClaimsPrincipal user object, the authentication properties, and optionally, the tokens. So far, so good!

Head over to my blog post: Exploring what is inside the ASP.NET Core cookies if you want to know more about what is stored inside the authentication cookies.

What happens when you do a signout in ASP.NET Core?

All that happens is that the cookie handler asks the browser to delete the cookie. That’s all. You can see for yourself in the source code here.

The cookie is deleted, but what is the security issue here?

The problem is that the cookie can still be used even after the user has signed out. This means that if you copy the cookie to another browser (or if a hacker gets hold of it), it can still be used to access the associated web application services until the data found inside the cookie expires.

Another complexity is that multiple items have different expiration policies inside the authentication cookie. We have the “user session” and the tokens. These have all different lifetimes and give you access to different things.

So, even though you disable all the tokens or they have expired, your authentication session will still be valid. It can also be possible to still access some resources with just the session alone.

How can we improve this?

**Introducing the SessionStore

As mentioned earlier, the authentication ticket is typically stored inside the cookie by default. However, instead of storing it directly in the cookie, we can move this data to a separate session store on the backend, reducing the cookie size and enhancing security.

When implemented, the cookie handler will send the ticket to the store, and in return, it gets a session key back. This key is then stored in the cookie, and this substantially reduces the size of the cookie.

By disabling the cookie encryption as described in my blog post Exploring what is inside the ASP.NET Core cookies, we can see that the content of the cookie is the following:

.....cookie..............Microsoft.AspNetCore.Authentication.Cookies-Session Id$e51c403c-ab75-4df2-9c6e-167abdb60ac8..................

(The non-printable characters have been replaced with a dot).

Implementing the ITicketStore

To implement the session store, we need to implement the ITicketStore [https://github.com/dotnet/aspnetcore/blob/main/src/Security/Authentication/Cookies/src/ITicketStore.cs\] interface, which is defined as follows:

/// <summary>
/// This provides an abstract storage mechanic to preserve the identity
/// information on the server while only sending a simple identifier
/// key to the client. This is most commonly used to mitigate
/// issues with serializing large identities into cookies.
/// </summary>
public interface ITicketStore
{
    /// <summary>
    /// Store the identity ticket and return the associated key.
    /// </summary>
    Task<string> StoreAsync(AuthenticationTicket ticket);

    /// <summary>
    /// Tells the store that the given identity should be updated.
    /// </summary>
    Task RenewAsync(string key, AuthenticationTicket ticket);

    /// <summary>
    /// Retrieves an identity from the store for the given key.
    /// </summary>
    Task<AuthenticationTicket?> RetrieveAsync(string key);

    /// <summary>
    /// Remove the identity associated with the given key.
    /// </summary>
    Task RemoveAsync(string key);
}

Implementing this interface allows you to store the data in any backend storage of your choice, as demonstrated below:

Here’s an example of a simple in-memory store implementation in ASP.NET Core:

internal class MySessionStore : ITicketStore
{
    private ConcurrentDictionary<string, AuthenticationTicket> mytickets = new();

    public MySessionStore()
    {
    }

    public Task RemoveAsync(string key)
    {
        Log.Debug("MySessionStore.RemoveAsync Key=" + key);
        if (mytickets.ContainsKey(key))
        {
            mytickets.TryRemove(key, out _);
        }
        return Task.FromResult(0);
    }

    public Task RenewAsync(string key, AuthenticationTicket ticket)
    {
        Log.Debug("MySessionStore.RenewAsync Key=" + key + ", 
		          ticket = " + ticket.AuthenticationScheme);
        mytickets[key] = ticket;
        return Task.FromResult(false);
    }

    public Task<AuthenticationTicket> RetrieveAsync(string key)
    {
        Log.Debug("MySessionStore.RetrieveAsync Key=" + key);
        if (mytickets.ContainsKey(key))
        {
            var ticket = mytickets[key];
            return Task.FromResult(ticket);
        }
        else
        {
            return Task.FromResult((AuthenticationTicket)null!);
        }
    }

    public Task<string> StoreAsync(AuthenticationTicket ticket)
    {
        var key = Guid.NewGuid().ToString();
        var result = mytickets.TryAdd(key, ticket);
        if (result)
        {
            string username = ticket?.Principal?.Identity?.Name ?? "Unknown";
            Log.Debug("MySessionStore.StoreAsync ticket=" + username + ", key=" + key);
            return Task.FromResult(key);
        }
        else
        {
            throw new Exception("Failed to add entry to the MySessionStore.");
        }
    }
}

That’s it!

One implementation using the .NET MemoryCache can be found here. More implementations can be found on Github and on NuGet.

Using the Session Store

To use it, we need to create an instance and pass it to the SessionStore property of the cookie authentication handler, as shown below:

.AddCookie("cookie", o =>
{
    //...
    o.SessionStore = new MySessionStore();
})

Why using a session store improves security

As discussed, when you sign out, the cookie is removed from the browser by default. However, the cookie is still valid and can be reused until its content expires.

By introducing the session store, the entry stored in it is automatically removed at sign-out. This means that even if the cookie is stolen, it can’t be reused! The cookie handler does this for us automatically.

**Additional Possibilities with a Session Store

What other possibilities does the introduction of the session store enable?

We can create a “Where you’re signed in” page, like this page on Google:

Metrics and audit logs We could add logging or metrics of all the method calls to the session store to get insights into how the users use our system.
Sign out users remotely For example, if an employee leaves your company, you can then delete all the entries in the database for this employee.

Resources

Feedback, comments, found any bugs?

Let me know if you have any feedback, anything I missed, or any bugs/typos. You can find my contact details here.

Demystifying OpenID Connect's State and Nonce Parameters in ASP.NET Core

Tore Nestenius — Wed, 13 Dec 2023 00:00:00 GMT

In the world of web application security, OpenID Connect plays a key role in streamlining authentication processes. But what makes it really tick? In this blog post, we dive deep into two critical security features of OpenID Connect – the state and nonce parameters – and how they are used in ASP.NET Core.

This simplified diagram tries to show how the state and nonce are used when a user authenticates using OpenID Connect:

In the image above, the client should verify that the returned state value matches the expected value and that the nonce inside the ID-token also matches the expected value.

Challenging the user in ASP.NET Core

In ASP.NET Core, when a user attempts to access a secured part of your application, the OpenID Connect handler initiates a challenge request. This can happen automatically via the authorization middleware or manually through the ChallengeAsync method:

[HttpGet]
public async Task Login()
{
    if (User.Identity.IsAuthenticated == false)
    {
        await HttpContext.ChallengeAsync();
    }
}

This challenge triggers a redirect to the authorization server, such as Duende IdentityServer, with a URL crafted with various parameters, including the client_id, redirect_uri, response_type, and, notably, the state and nonce parameters.

The redirect URL can look something like this:

https://identityservice.secure.nu/connect/authorize?
client_id=localhost-addoidc-client
&redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignin-oidc
&response_type=code
&prompt=consent
&scope=openid%20profile%20email%20employee_info%20offline_access%20api
&code_challenge=3LEckeTVCxl4TD12nxptlbiIgTzEEMfUqBa-sZo8foY
&code_challenge_method=S256
&response_mode=form_post
&nonce=638357382195073041.NzViMTM2MzktNWFhMi00MDhjLWIzODYtMDBkYzAxMDE2MmR
kYjY3NzdhYTEtZGQ0Mi00MTM4LWIwOTgtZjMyNmFlOTFjYzZk
&state=AQAAAAQAAAAJLnJlZGlyZWN0DC9Vc2VyL0xvZ2luPw1jb2RlX3ZlcmlmaWVyK3pPNzREaFJI
NndPbTdOSWZHZDZ3bkc0MDB0MEdNR3dMRGtmblF6NnVOMzgFLnhzcmYra2Q3OXk2N2E3Nk5DZ
3ZuY1RfNGdMQVgyeHVhMW12YjFrTkRwdnJBUXVpbx5PcGVuSWRDb25uZWN0LkNvZGUuUmVkaX
JlY3RVcmkiaHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zaWduaW4tb2lkYw
&x-client-SKU=ID_NET8_0
&x-client-ver=7.0.0.0

The exact content depends on your OpenID-Connect middleware configuration.

The state parameter in OpenID Connect

The state parameter is crucial to an OpenID Connect authorization request. But what is its main purpose?

In OpenID Connect, the state parameter serves as an opaque value created by the client. Its primary function is maintaining the state between the initial request and the callback, acting as a shield against cross-site request forgery attacks during the authentication process.

While some implementations keep the state as a random value, that is verified during the callback. Other implementations injecting “data” into the state parameter. By doing this, the client doesn’t have to remember this information elsewhere, making the client stateless.

Looking inside the state parameter

The OIDC handler in ASP.NET Core stores data in the state parameter, which is encrypted and secured using the Data Protection API.

However, we can “bypass” this encryption and issue an unencrypted state parameter. To do this, we can add our own transparent data protector and implement it like this:

public class MyDataProtector : IDataProtector
{
    public IDataProtector CreateProtector(string purpose)
    {
        return new MyDataProtector();
    }

    public byte[] Protect(byte[] plaintext)
    {
        return plaintext;
    }

    public byte[] Unprotect(byte[] protectedData)
    {
        return protectedData;
    }
}

Then, we can tell the OpenIDConnect handler to replace the default encryption protector with this one instead:

}).AddOpenIdConnect("oidc", o =>
{
    //...
    o.StateDataFormat = new PropertiesDataFormat(new MyDataProtector());
});

Adding this allows us to peek inside the state parameter:

GET https://identityservice.secure.nu/connect/authorize?
    client_id=localhost-addoidc-client
    ...
    &state=AQAAAAQAAAAJLnJlZGlyZWN0DC9Vc2VyL0xvZ2luPw1jb2RlX3ZlcmlmaWVyK0dISVBiMmJG
           SHNfWDdGRjRmSm1aZDBKR1BXbm5BeXllVWlsUXJnMjE2NE0FLnhzcmYrLTMxWktMb0N3TlVUcnd
           EQTVfSHRkZExPbUtVbTVkM0piMC14X3ZmSm1RWR5PcGVuSWRDb25uZWN0LkNvZGUuUmVkaXJl
           Y3RVcmkiaHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zaWduaW4tb2lkYw

If we decode the state parameter using a tool like base64 decode https://www.base64decode.org , then we get a state that looks like this:

.................redirect./User/Login? 
code_verifier+GHIPb2bFHs_X7FF4fJmZd0JGPWnnAyyeUilQrg2164M..xsrf+- 
31ZKLoCwNUTrwDA5_HtddLOmKUm5d3Jb0- 
x_vfJmQY.OpenIdConnect.Code.RedirectUri"https://localhost:5001/signin-oidc

(The non-printable characters have been replaced with a dot).The above can be a bit hard to read, a cleaned-up version looks like this:

[0]: {[.redirect, /User/Login?]}
[1]: {[code_verifier, GHIPb2bFHs_X7FF4fJmZd0JGPWnnAyyeUilQrg2164M]}
[2]: {[.xsrf, -31ZKLoCwNUTrwDA5_HtddLOmKUm5d3Jb0-x_vfJmQY]}
[3]: {[OpenIdConnect.Code.RedirectUri, https://localhost:5001/signin-oidc]}

Can I add custom properties here?

Yes, if you provide an instance of the AuthenticationProperties with the challenge, like this:

[HttpGet]
public async Task Login()
{
    if (User.Identity.IsAuthenticated == false)
    {
        var properties = new AuthenticationProperties()
        {
            RedirectUri = "/",
            Items =
            {
                { "IpAddress", "192.168.0.3" },
                { "ComputerName", "MyComputer" },
                { "ApiKey", "Summer2023" },
                { "Language", "English" }
            }
        };
        await HttpContext.ChallengeAsync(properties);
    }
}

Then you might end up with a state parameter that looks like this:

… &state=AQAAAAgAAAAJLnJlZGlyZWN0AS8JSXBBZGRyZXNzCzE5Mi4xNjguMC4zDENvbXB1dGVyTm 
FtZQpNeUNvbXB1dGVyBkFwaUtleQpTdW1tZXIyMDIzCExhbmd1YWdlB0VuZ2xpc2gNY29kZV92ZXJ 
pZmllcitpVGw1UnczYno1SnYxNm90ektIbHpHT0RGSjczblJ6dzRSbDQ4Zkh4RGFFBS54c3JmK1hOd3R 
fd3otMjlpVGtGYklXN2ZsWGNwdmplenF1bElWYkt5alQzWWIzZ00eT3BlbklkQ29ubmVjdC5Db2RlLlJl 
ZGlyZWN0VXJpImh0dHBzOi8vbG9jYWxob3N0OjUwMDEvc2lnbmluLW9pZGM …

If you base64 decode it and then clean it up, you will get the following information:

[0]: {[.redirect, /]}
[1]: {[IpAddress, 192.168.0.3]}
[2]: {[ComputerName, MyComputer]}
[3]: {[ApiKey, Summer2023]}
[4]: {[Language, English]}
[5]: {[code_verifier, iTl5Rw3bz5Jv16otzKHlzGODFJ73nRzw4Rl48fHxDaE]}
[6]: {[.xsrf, XNwt_wz-29iTkFbIW7flXcpvjezqulIVbKyjT3Yb3gM]}
[7]: {[OpenIdConnect.Code.RedirectUri, https://localhost:5001/signin-oidc]}

The AuthenticationProperties that you passed to the initial challenge, will later be available in the ClaimsPrincipal user object after the user is signed in.

The nonce parameter in OpenID Connect

The nonce parameter in OpenID Connect is crucial for associating a client session with the ID token and is used to mitigate replay attacks.

In ASP.NET Core, it’s generated by the GenerateNonce method, as shown below:

public virtual string GenerateNonce()
{
    LogHelper.LogVerbose(LogMessages.IDX21328);
    string nonce = Convert.ToBase64String(Encoding.UTF8.GetBytes(Guid.NewGuid().ToString() +
                                                                 Guid.NewGuid().ToString()));

    if (RequireTimeStampInNonce)
    {
        return DateTime.UtcNow.Ticks.ToString(CultureInfo.InvariantCulture) + "." + nonce;
    }

    return nonce;
}

The method is found in the OpenIdConnectProtocolValidator class.

The nonce generated by this method is a string that consists of a timestamp and a random value; it can look like this:

638357413236076453.NjY2MmZlZTctOTU2OC00ZmNlLTk5NWUtMWRmODMxZDY4NTFhYmRmYjI3ODgtN TU3ZS00NjZiLWJjMGMtNWFlOWNkOGQ3M2Vi

How is the nonce parameter handled in ASP.NET Core?

Upon challenging the user, a nonce is generated and stored as a cookie, as shown below:

Set-Cookie:  
.AspNetCore.OpenIdConnect.Nonce 
.NjM4MzU3NDE2MTcwODk2NjQ2LllUWmtOak5qWm1RdE5UTmpaUzAwTkRNeExUZzBNRFV0Wm1aalpHVmxOekk 
1WlRsak5XWmhaR000TmpndFpEY3pPQzAwTXpRd0xXRTFNR010TTJRd01qQm1aV0kzT1ROag=N;
expires=Thu, 16 Nov 2023 14:42:08 GMT; path=/signin-oidc; secure; samesite=none; httponly

The cookie name is “.AspNetCore.OpenIdConnect.[Nonce]” and the interesting thing here is that the cookie name contains the nonce value. The nonce here is also protected using the Data Protection API.

Similar to what we did before, we can introduce the transparent protector by setting the StringDataFormat property.

}).AddOpenIdConnect("oidc", o =>
{
	//...
    o.StateDataFormat = new PropertiesDataFormat(new MyDataProtector());
    o.StringDataFormat = new SecureDataFormat<string>(new StringSerializer(),
    new MyDataProtector());
});

Adding this will make the handler store the nonce in the cookie in unprotected form. However, this is not useful, as there’s little interesting information to see in the nonce cookie.

Besides storing the nonce in the cookie, it is also included in its raw form in the authentication request to the authorization server:

GET https://identityservice.secure.nu/connect/authorize
    ?client_id=localhost-addoidc-client
    ...
    &nonce=638357416170896646.YTZkNjNjZmQtNTNjZS00NDMxLTg0MDUtZmZjZGVlNzI5ZTljNWZhZGM4NjgtZD
          czOC00MzQwLWE1MGMtM2QwMjBmZWI3OTNj
    ...

Conclusions

In this blog post, we have explored what is inside the encrypted state parameter that is passed to the authorization server when the user is challenged. We also saw that we can pass custom AuthenticationProperties to the challenge operation, and these properties will later end up in the ClaimsPrincipal user object.

We also explored the nonce, a random string that we store securely in a cookie and pass in its raw form to the authorization server. The nonce ties the ID-token to the initial request made to the authorization server. With the nonce, the client knows the token is generated for itself, and it won’t consume a token injected by a malicious party.

Resources

Feedback, comments, found any bugs?

Let me know if you have any feedback, anything I missed, or any bugs/typos. You can find my contact details here.

Exploring what is inside the ASP.NET Core cookies

Tore Nestenius — Wed, 22 Nov 2023 00:00:00 GMT

ASP.NET Core generates various types of cookies, such as authentication, antiforgery, and session cookies. In this blog post, we’ll take a closer look at what information these cookies store, how they function, and the security measures used to protect them, including encryption and the Data Protection API.

Protecting The ASP.NET Core Cookies

The content of these cookies is protected through a combination of encryption and signing mechanisms. These protective measures ensure the confidentiality and integrity of the information stored within the cookies.

The protection is managed by the Data Protection API (DPAPI) as shown below:

The Data Protection API in ASP.NET Core is a framework for securing sensitive data, managing encryption, and facilitating key rotation. It offers a unified interface for encryption, decryption, and signing that enhances application data security. How the Data Protection API works is beyond the scope of this blog post.

The Authentication Cookie in ASP.NET Core maintains user authentication across HTTP requests. When a user logs in, the authentication system typically issues a cookie to the client, appearing as follows:

Set-Cookie: .AspNetCore.cookie=CfDJ8MSO_2XEvwalH...; 
expires=Thu, 30 Nov 2023 09:38:16 GMT; path=/; secure; samesite=lax; httponly

The Data Protection API encrypts this cookie, making its contents inaccessible and tamperproof.

So, how can we peek inside this cookie?

Luckily for us, we can turn off this protection by providing a custom transparent data protector, as shown below:

public class MyDataProtector : IDataProtector
{
    public IDataProtector CreateProtector(string purpose)
    {
        return new MyDataProtector();
    }

    public byte[] Protect(byte[] plaintext)
    {
        return plaintext;
    }

    public byte[] Unprotect(byte[] protectedData)
    {
        return protectedData;
    }
}

We can then add this protector to the authentication cookie handler:

builder.Services.AddAuthentication("cookie")
.AddCookie("cookie", o =>
{
    o.DataProtectionProvider = new MyDataProtector();
});

This means that the issued cookies will not be protected at all. To test this and issue a new unsecured cookie, we first need to sign in a user. Wecan do this by using this simple test code:

app.MapGet("/login", async context =>
{
    var claims = new Claim[]
    {
        //Standard claims
        new Claim(ClaimTypes.Name, "Tore Nestenius"),
        new Claim(ClaimTypes.Country, "Sweden"),
        new Claim(ClaimTypes.Email, "tore@tn-data.se"),
		
        //Custom claims
        new Claim("JobTitle", "Consultant and trainer"),
        new Claim("JobLevel", "Senior"),
        new Claim("webpage", "https://www.tn-data.se"),
    };
	
    var identity = new ClaimsIdentity(claims: claims,
                                      authenticationType: "cookie");
									  
    var user = new ClaimsPrincipal(identity: identity);
	
    var authProperties = new AuthenticationProperties
    {
    };
	
    //Sign-in the user
    await context.SignInAsync("cookie", user, authProperties);
	
    await context.Response.WriteAsync("<!DOCTYPE html><body>");
    await context.Response.WriteAsync("Logged in!");
});

In the code above, we create a ClaimsPrincipal user object and ask the cookie handler to sign this user. By doing so, the handler will issue a new unprotected authentication cookie.

Running this code will issue a new cookie that can look like this:

Set-Cookie:  .AspNetCore.cookie=BQAAAAZjb29raWUBAAAABmNvb2tpZQEAAQAGAAAAAQAOVG9yZSBOZXN0
ZW5pdXMBAAEA AQAAAAAAPWh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2x
haW1zL2NvdW50 cnkGU3dlZGVuAQABAAEAAAAAAEJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1Lz
A1L2lkZW50aXR5L2 NsYWltcy9lbWFpbGFkZHJlc3MPdG9yZUB0bi1kYXRhLnNlAQABAAEAAAAAAAhKb2JUaXRsZ
RZDb25zdWx0YW50IGFuZ CB0cmFpbmVyAQABAAEAAAAAAAhKb2JMZXZlbAZTZW5pb3IBAAEAAQAAAAAAB3dlYnBh
Z2UWaHR0cHM6Ly93d3c udG4tZGF0YS5zZQEAAQABAAAAAAAAAAEAAAADAAAACy5wZXJzaXN0ZW50AAcuaXNzdWV
kHVRodSwgMTYgTm92 IDIwMjMgMDk6NTc6MDQgR01UCC5leHBpcmVzHVRodSwgMzAgTm92IDIwMjMgMDk6NTc6MD
QgR01U; expires=Thu, 30 Nov 2023 09:57:04 GMT; path=/; secure; samesite=lax; httponly

To peek inside the cookie, we need to first base64 decode it. We can do that using a tool like Base64Decode, and if we do that, we will see the following:

......cookie.....cookie...........Tore Nestenius..........=
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country.Sweden..........B
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.tore@tn-data.se
...........JobTitle.Consultant and trainer...........JobLevel.Senior...........
webpage.https://www.tn-data.se......................persistent...issued.
Thu, 16 Nov 2023 09:57:04 GMT..expires.Thu, 30 Nov 2023 09:57:04 GMT

(The non-printable characters have been replaced with a dot).

This shows that inside the cookie we find the entire authentication ticket (consisting of the ClaimsPrincipal and the AuthenticationProperties).

The session service in ASP.NET Core is a mechanism for managing user-specific data across requests, often being used for scenarios like maintaining a shopping cart. This service issues a protected cookie to the browser to keep track of the data. It is important to know that this cookie and its purpose are unrelated to the earlier authentication cookie.

Your application can ask the session service to remember temporary data for the current user, as shown below:

To implement the session service, register the service and add it to the request pipeline:

// Register the service
builder.Services.AddSession(options =>
{
    //...Options…
});

//..
app.UseSession();

A sample session cookie could look like:

Set-Cookie:
.AspNetCore.Session=CfDJ8MSO%2F2XEvalHlF%2Fgv69RLqD6mFWeTVC1MG3dYxNWftq625VyGyqF%2BeIq2
xaqgm1cd4McTp0ydSLcRYraIA4%2F%2Bn89FKFhz567AcC%2FeSnwabg4eRrlFAeWLFBq0K8zl2ISdMPcY0pj%
2BtAJQgC5NIte76QR4TlheM1ZhsD98WAdAvKM; path=/; samesite=lax; httponly

This cookie is also protected using the Data Protection API; however, there is no way to provide a custom transparent data protector, as we did in the previous example.

One option is to download and modify the code for the session middleware. The source code is found on GitHub, and it is straightforward to modify. When I introduce the transparent protector, the unencrypted cookie will look like this:

Set-Cookie: .AspNetCore.Session=Y2M1NGVjZGItZDhjNi0yYTI1LTM2N2UtMjhhNmM4ZWRhMzMw;
path=/; samesite=lax; httponly

This cookie is also base64 encoded, so decoding the cookie will result in the following data:

cc54ecdb-d8c6-2a25-367e-28a6c8eda330

This GUID acts as a session key used to look up the session object for the current request. Where the data is stored depends on how you have configured the session system.

The session system in ASP.NET Core provides various storage options, including in-memory storage, distributed cache, and external storage providers, which allowsdevelopers to choose the most suitable method for their application’s scalability and performance needs.

Upskill With Me: Courses, Workshops & Training

This cookie is crucial forsafeguarding against Cross-site Request Forgery (CSRF) attacks. This cookie operates on a token-based system, where the token is stored within the cookie and also embedded in HTML forms. When a form is submitted, the token in the form data must correspond with the token in the cookie to ensure security.

Additionally, the Data Protection API secures this cookie. The implementation of this protection is handled by the DefaultAntiforgeryTokenSerializer class, which you can explore in detail here .

Here’s an example of how this cookie can beset in ASP.NET Core:

Set-Cookie: .AspNetCore.Antiforgery.YCD23e8AirM=CfDJ8MSO_2XEvalHlF_gv69RLqDarftldkzWvbxvac
LnZ4WtaTDcgSCPmxQdmK8OHbGfMIUvV0VhcFkx4Ys8jPppklGBUGWRTsXcwxhMBl7nqZA0s_xYN5jJq3J7
LrH8EikY82bOYmSoA_wEYCxkcrBEEAs; path=/; samesite=strict; httponly

				
			

While this blog post does not go into the specifics of the token's internal structure, those interested in this 
can refer to the Default [Antiforgery Token Serializer](https://github.com/dotnet/aspnetcore/blob/main/src/Antiforgery/src/Internal/DefaultAntiforgeryTokenSerializer.cs) 
class for an in-depth understanding of how the token is constructed.

## Conclusions

This post covers ASP.NET Core cookies, specifically the authentication, session, and antiforgery cookies, 
shedding light on their contents. It emphasizes the security aspects involving encryption and signing through the Data Protection API.

- **The authentication cookie**  
    This cookie contains the entire ClaimsPrincipal user object and the associated authentication properties.
- **The antiforgery cookie**  
    The token of this cookie is used to protect HTML forms.
- **The session cookie**  
    This cookie contains the session key that the session service can use to look up the stored data for a given user.

Remember that you should never disable data protection in real production applications!

## Resources

- [How to: Use Data Protection](https://learn.microsoft.com/en-us/dotnet/standard/security/how-to-use-data-protection)
- [Configure ASP.NET Core Data Protection](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview)
- [Storing the ASP.NET Core Data Protection Key Ring in Azure Key Vault](https://www.edument.se/post/storing-the-asp-net-core-data-protection-key-ring-in-azure-key-vault?lang=en)
- [Use cookie authentication without ASP.NET Core Identity](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/cookie)

## More posts by the author

- [Persisting the ASP.NET Core Data Protection Key Ring in Azure Key Vault](/net/persisting-the-asp-net-core-data-protection-key-ring-in-azure-key-vault/)
- [BearerToken: The new Authentication handler in .NET 8](/net/bearertoken-the-new-authentication-handler-in-net-8/)
- [Debugging JwtBearer Claim Problems in ASP.NET Core](/net/debugging-jwtbearer-claim-problems-in-asp-net-core/)
- [Debugging OpenID Connect Claim Problems in ASP.NET Core](/net/missing-openid-connect-claims-in-asp-net-core/)
- [Introducing the Cloud Debugger for Azure](/azure/introducing-the-cloud-debugger-for-azure/)

## Related Training Workshops

- [Building ASP.NET Core APIs](https://tn-data.se/courses/building-asp-net-core-apis/)
- [ASP.NET Core fundamentals](https://tn-data.se/courses/asp-net-core-fundamentals/)
- [Web security fundamentals](https://tn-data.se/courses/web-security-fundamentals/)

## Feedback, comments, found any bugs?

Let me know if you have any feedback, anything I missed, or any bugs/typos. You can find my contact details [here](/contact/).

Debugging cookie problems in ASP.NET Core

Tore Nestenius — Mon, 09 Oct 2023 00:00:00 GMT

Having answered over 1000 questions on Stack Overflow, I’ve found that cookie-related issues are a frequent challenge for developers using ASP.NET Core, especially when implementing authentication and OpenID Connect.

Cookie problems can, in my experience, be categorized into the following categories:

Browser Rejection
Cookies provided by the server that aren’t accepted by the browser.
Browser Omission
Cookies in the browser are not included in requests to the server.
Lost cookies
Cookies that are lost on the way to the server.

In this post, we’ll explore common ASP.NET Core cookie problems, such as browser rejection, missing cookies in requests, and lost cookies. You’ll learn practical tips to identify, diagnose, and resolve these issues, ensuring smoother authentication flows and a more reliable application experience.

Cookies rejected by the browser

When setting a cookie, we use the set-cookie response header, often accompanied by the secure and samesite attributes. Below is an example illustrating the setting of five common cookies:

HTTP/1.1 200 OK Set-Cookie: NormalCookie=NormalValue;Path=/ 
Set-Cookie: NormalCookieWitSecure=NormalValueSecure;Path=/;
secure Set-Cookie: StrictCookie=StrictValue;Path=/;SameSite=Strict 
Set-Cookie: LaxCookie=LaxValue;Path=/;SameSite=Lax 
Set-Cookie: NoneCookie=NoneValue;Path=/;SameSite=None;Secure …

(Note: This article will not discuss the details of the path, domain, and the HttpOnly attribute. The HttpOnly attribute is all about restricting JavaScript from accessing cookies.). I recommend setting the HttpOnly attribute on every cookie that never needs to be accessed by JavaScript.

The first step in troubleshooting cookie problems is to verify that the browser has accepted the cookie.

To see which cookies it has received and accepted, open the browser developer tools (F12) in Chrome and look under Application -> Storage -> Cookies.

If the expected cookies are not found here, then head over to the Network tab, locate the request that sets the cookie, and then click on the Cookies sub-tab:

Rejected cookies are highlighted in yellow. Hovering over the information (i) icon displays reasons for the blockage. As shown in the example below:

You can also activate the “Has blocked cookies” checkbox to only show requests with blocked response cookies.

Some of the most common reasons for blocking are:

Using samesite=none without the secure attribute
Trying to set a cookie with the secure attribute over HTTP://
Too large cookies; keep the cookie size below 4000 bytes for maximum browser compatibility.

Cookies not included in requests

If you have concluded that the browser has accepted the cookie and it is found under Application -> Storage, great! One step forward! What’s next?

There are a few reasons why the browser might decide not to include cookies in outgoing requests:

Some of the reasons for blocking are:

Protocol Mismatch
Cookies with the secure attribute will not be included in requests over HTTP.
Incorrect samesite
For cross-site requests, you must use:
- samesite=none;secure when you need to support GET & POST in requests to another site
- samesite=lax when you only need to support GET requests across sites.
**Cross-Origin Resource Sharing (CORS)
**We won’t go into CORS in this blog post. CORS can be problematic when you do API requests from JavaScript using the XMLHttpRequest or Fetch APIs.

Under the network tab, you can see why a cookie was not included in the request, as shown in the example below:

Some of the common samesite problems that I see are:

SameSite=none cookies
Cookies set with the samesite=none attribute must also be marked with the secure attribute. This means that they must always be used over HTTPS, a common problem, for example, when working with OpenID Connect.
Missing samesite header?
All cookies that you set should have a samesite attribute. Otherwise, you might end up with unexpected issues where browsers will start to block them in certain circumstances.

For example, Firefox writes this warning to the console when you try to set a cookie without a valid samesite attribute:

Cookie “NormalCookie” does not have a proper “SameSite” attribute value. Soon, cookies without the “SameSite” attribute or with an invalid value will be treated as “Lax”. This means that the cookie will no longer be sent in third-party contexts. If your application depends on this cookie being available in such contexts, please add the “SameSite=None“ attribute to it. To know more about the “SameSite“ attribute, read https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie/SameSite

Which samesite value should you use?

Some guidance about what value to use:

Strict
Use this value for cookies that should only be used within the same site. For example, consider using this value for your session cookie. Using strict cookies provides the maximum protection against Cross-Site Requests.
**Lax
**This is the new default for cookies, which only includes the cookie GET requests across sites.
**None
**Use this value for cookies that should be included in all site requests. This value must be set together with the secure attribute. This is the least secure option. This makes the cookies behave like they behaved before the samesite concept was introduced.

Cookies in ASP.NET Core

What can go wrong when we use cookies in ASP.NET Core?

When you use the cookie authentication handler, the default session cookie is set as follows:

Set-Cookie: .AspNetCore.Cookies=xxxxxxx; path=/; secure; samesite=lax; httponly

This is a sensible default. You might be tempted to set the session cookie to samesite=strict, as follows:

builder.Services.AddAuthentication()
       .AddCookie(opt =>                 
	   {
           opt.Cookie.SameSite = SameSiteMode.Strict;                 
       });

If you just use local authentication (like ASP.NET Core Identity), that is usually fine. But, when you use it together with OpenID Connect, you will have problems, as shown in the image below:

OpenID Connect, cookies, and IdentityServer

When you work with OpenID Connect, plenty of cookies will be involved. For example, if you use Duende IdentityServer, then the following cookies are involved during authentication:

Not properly configuring and understanding these cookies is a common source of problems.

Same domain but different ports

You might think that when you have multiple sites on the same domain but on different ports, they would have separate cookie jars:

But it turns out that they will all share the same cookie jar. The cookies are tied to the domain, not the port or scheme.

Summary

I hope the steps outlined above can help you troubleshoot your cookie problems. Here are some tips for healthier and more secure cookies:

**Always use HTTPS
**Most cookie problems will go away when you move your traffic to HTTPS. Using HTTPS today is also a must If you care about security.
Set samesite
Always add the correct samesite attribute; this is a must today.
Add the secure and HttpOny attribute
Securing our cookies and all sensitive cookies should always have these two attributes set.
Do research the path and domain attributes
They can be used to further restrict to what domain (including sub-domains) and path the cookies should be included on.

Resources

Feedback, comments, found any bugs?

Let me know if you have any feedback, anything I missed, or any bugs/typos. You can find my contact details here.

BearerToken: The new Authentication handler in ASP.NET Core 8

Tore Nestenius — Tue, 29 Aug 2023 00:00:00 GMT

Microsoft introduced the new BearerToken authentication handler in ASP.NET Core 8 as part of an initiative to streamline and modernize authentication processes. This blog post dives into how the BearerToken in ASP.NET Core handler works, its key features, and how it differs from existing authentication handlers like Cookie and JwtBearer.

Head over to the blog post Improvements to auth and identity in ASP.NET Core 8 to read more about their effort to improve ASP.NET Core authentication.

Background

In the past, after you authenticated as a user, your application typically issues a session cookie. This cookie contains your user identity in the form of a ClaimsPrincipal. The content of the cookie is protected and encrypted using the built-in Data Protection API.

The issuer of this cookie is the Cookie authentication handler. This handler has two main purposes:

When a user has been authenticated, the handler issues a new session cookie based on the provided user details, as shown in the picture below:

Authenticating all incoming requests by looking for a session cookie. If a valid cookie is found, it will create a ClaimsPrincipal user object based on the information inside the cookie. This user object is then passed along the request pipeline in ASP.NET Core.

Why do we need a new authentication handler?

Today, systems typically rely on the session cookie to authenticate user requests. This means that you are usually forced to use the user interface as provided by the backend server, with few options for customization. This often results in an inconsistent experience for users when they transition from a browser-based app experience to a server-rendered one.

Some of the goals by Microsoft are:

Improve Cookie-Based Authentication: Introduce more customization and consistent user experience between single-page and server-rendered apps.
Introduce Token-Based Authentication: Shift from cookies to the more flexible and widely-used, token-based authentication system.

The BearerToken handler is a core component of this effort.

What does the BearerToken handler in ASP.NET Core do?

The new BearerToken handler can be seen as an alternative to the cookie handler, but with a twist..

Instead of issuing cookies, it will issue an access and refresh token. These tokens are not JWT tokens (for accessing external APIs). Instead, they are meant to be used between the client and web applications.

The BearerToken handler is not meant to be a stand-alone component. Instead, it is meant to be used with the ASP.NET Core Identity or a similar library.

Sample ASP.NET Core BearerToken Application

I created a tiny sample application that shows the BearerToken handler in action. You can find the source code on GitHub

Running the Sample Application Do the following steps to use the application:

Start a web client, like Postman.
Start the application and click on the Login link.
As a result, you will be presented with the access and refresh token in JSON.
In Postman:
- Make a GET request to the site homepage at https://localhost:5001
- Choose Auth -> Bearer Token
- Copy/paste the access token from the page.
Press Send to send the request to the site

As a result, you should get an HTML page back. Click on the Preview tab to view the page in Postman, as shown below. On the page, you will see the claims extracted from the access token you sent to the application.

Why can’t I run this directly in the browser?

The BearerToken handler is meant for clients who prefer to do authentication programmatically instead of going through the usual UI pages. That is why you must use tools like Postman so that you can get the token to be included in the authorization header.

Feel free to replace the BearerToken handler with the cookie handler in the source code. If you do, it will work as a normal web application using a session cookie.

What’s inside the tokens provided by the BearerToken handler?

We saw that the result of a sign-in is this JSON document:

{
  "token_type": "Bearer",
  "access_token": "CfDJ8F2Y2KDGq...",
  "expires_in": 3600,
  "refresh_token": "CfDJ8F2Y2KDG..."
}

What’s inside the access token? Can we look inside it?

By default, it is encrypted using the Data Protection API, but with a little code, we can make a transparent data protector that will not perform any encryption. This allows us to peek inside the tokens.
To do this, we can implement a custom transparent IDataProtector:

public class MyDataProtector : IDataProtector
{
    public IDataProtector CreateProtector(string purpose)
    {
        return new MyDataProtector();
    }

    public byte[] Protect(byte[] plaintext)
    {
        return plaintext;
    }

    public byte[] Unprotect(byte[] protectedData)
    {
        return protectedData;
    }
}

Then, we configure the BearerToken handler to use this custom protector instead:

.AddBearerToken(o =>
{
    o.BearerTokenProtector = new TicketDataFormat(
                                    new MyDataProtector()
                                        .CreateProtector(""));
    o.RefreshTokenProtector = new TicketDataFormat(
                                    new MyDataProtector()
                                        .CreateProtector(""));
});

Now, when we sign-in again, we get the same JSON structure as before:

{
  "token_type": "Bearer",
  "access_token": "BQAAABdCZWFyZXJUb2tlbjpBY2Nlc3NUb2tlbgEAAAALQmVhcmVyVG9rZW4BAAEABgAAAAEADl
RvcmUgTmVzdGVuaXVzAQABAAEAAAAAAD1odHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR
5L2NsYWltcy9jb3VudHJ5BlN3ZWRlbgEAAQABAAAAAABCaHR0cDovL3NjaGVtYXMueG1sc29hcC5vcmcvd3MvMjAwNS8w
NS9pZGVudGl0eS9jbGFpbXMvZW1haWxhZGRyZXNzD3RvcmVAdG4tZGF0YS5zZQEAAQABAAAAAAAISm9iVGl0bGUWQ29uc
3VsdGFudCBhbmQgdHJhaW5lcgEAAQABAAAAAAAISm9iTGV2ZWwGU2VuaW9yAQABAAEAAAAAAAd3ZWJwYWdlFmh0dHBzOi
8vd3d3LnRuLWRhdGEuc2UBAAEAAQAAAAAAAAABAAAAAgAAAAsucGVyc2lzdGVudAAILmV4cGlyZXMdTW9uLCAyMSBBdWc
gMjAyMyAxNDo1MTozOSBHTVQ",
  "expires_in": 3600,
  "refresh_token": "BQAAABhCZWFyZXJUb2tlbjpSZWZyZXNoVG9rZW4BAAAAC0JlYXJlclRva2VuAQABAAYAAAABA
  A5Ub3JlIE5lc3Rlbml1cwEAAQABAAAAAAA9aHR0cDovL3NjaGVtYXMueG1sc29hcC5vcmcvd3MvMjAwNS8wNS9pZGVu
  dGl0eS9jbGFpbXMvY291bnRyeQZTd2VkZW4BAAEAAQAAAAAAQmh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzI
  wMDUvMDUvaWRlbnRpdHkvY2xhaW1zL2VtYWlsYWRkcmVzcw90b3JlQHRuLWRhdGEuc2UBAAEAAQAAAAAACEpvYlRpdG
  xlFkNvbnN1bHRhbnQgYW5kIHRyYWluZXIBAAEAAQAAAAAACEpvYkxldmVsBlNlbmlvcgEAAQABAAAAAAAHd2VicGFnZ
  RZodHRwczovL3d3dy50bi1kYXRhLnNlAQABAAEAAAAAAAAAAQAAAAEAAAAILmV4cGlyZXMdTW9uLCAwNCBTZXAgMjAy
  MyAxMzo1MTozOSBHTVQ"
}

The tokens are still a bit scrambled, so this didn’t help us that much!
However, what is the first thing you check when you have a string of random characters? You check if it is base64 encoded, and there are plenty of online tools to do that. One is https://www.base64decode.org

If we do that, we can see the data stored inside the access token:

.....BearerToken:AccessToken.....BearerToken...........Tore Nestenius..........=
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country.Sweden..........B
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.tore@tn-data.se...........
JobTitle.Consultant and trainer...........JobLevel.Senior...........
webpage.https://www.tn-data.se......................persistent...expires.Mon, 21 Aug 2023 14:51:39 GMT

(Replaced all non-ASCII characters with a .)

What is inside the BearerToken refresh token?

If you base64 decode the refresh token, you will find:

.....BearerToken:RefreshToken.....BearerToken...........Tore Nestenius..........=
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country.Sweden..........B
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.tore@tn-data.se...........
JobTitle.Consultant and trainer...........JobLevel.Senior...........
webpage.https://www.tn-data.se......................expires.Mon, 04 Sep 2023 13:51:39 GMT

Comparing the two tokens, you will see they contain the same user information except for the token type and expiration time (Highlighted in bold above). The expiration time can be customized in the BearerToken options.

What is the purpose of the refresh token?

As we see above, the refresh token contains the same user information as the access token. One observation when reviewing the source code for the BearerHandler is that it only issues refresh tokens, but it does not contain any code to handle them. Instead, this token is meant to be consumed by another library (like ASP.NET Core Identity). For more details, see this GitHub issue:
Add token refresh endpoints to identity

Another observation is that these tokens are not JWT-tokens, which are usually a common format to transfer user information between systems.

In ASP.NET Core, we now have three handlers that do almost the same thing. The picture below tries to summarize the differences:

All three aim to authenticate user requests, while two of them also handle user sign-in information.

What about security? From a security perspective, I have mixed feelings about issuing and storing tokens in the client and if this can be done securely. As we all know, public clients (like mobile and browser-based apps) can’t handle secrets. However, this is all new for us as .NET developers, so we must see what patterns will emerge. Personally, I would probably introduce some BFF-style proxy between the client and server, as excellently explained in these two videos:

Issues with the BearerToken handler in ASP.NET Core

Working on this blog post has also raised a few questions, including:

Token size: The tokens can get quite large when they are filled with user claims, and there is no option to add a SessionStore(ITicketStore) like we can when we use the Cookie handler.
No way to customize the content of the refresh token: I am a bit curious why the content of it is the same as in the access token. I would assume we need less information in the refresh token.

Conclusions

I hope you now better understand the purpose of the new BearerToken handler in ASP.NET Core, how it works, and its limitations. This handler is part of ASP.NET Identity, so it will be interesting to see how this all turns out. However, that is a subject for another blog post.

What is new in ASP.NET Core 9?

ASP.NET Core 9 introduces two significant features aimed at enhancing support for OpenID Connect: Pushed Authorization Requests (PAR) and the AdditionalAuthorizationParameters option. PAR helps improve security and performance by allowing confidential clients to initiate authorization requests directly with the authorization server. The AdditionalAuthorizationParameters option provides flexibility for developers, enabling custom parameters to be passed during authorization. Both features are crucial for developers working with advanced OpenID Connect scenarios. To dive deeper into PAR, check out my blog post: Pushed Authorization Requests (PAR) in ASP.NET Core 9.

Resources

Debugging JwtBearer Claim Problems in ASP.NET Core

Tore Nestenius — Fri, 02 Jun 2023 00:00:00 GMT

A common problem when protecting your ASP.NET Core APIs is that expected claims are not found in the user object. In this blog post, I will give you some ideas for how to diagnose these types of problems. If you have claim problems related to the OpenIDConnect handler, head over to the blog post about Debugging OpenID Connect Claim Problems in ASP.NET Core.

What is the purpose of the JwtBearer handler?

We use the JwtBearer authentication handler to protect ASP.NET Web APIs. Its primary purpose is to look for an access token in the incoming request, and if one is found, validate it and create a user object of type ClaimsPrincipal. JwtBearer only deals with access tokens, and it is essential to remember that you should never try to send an ID or refresh tokens to APIs.

First problem: Are the expected claims inside the received access token?

Using a tool like Fiddler, you can capture the raw access token from the incoming request and then use a site like jwt.io to inspect what the access token contains.

The token is typically included in the Authorization header, as shown below:

GET https://api.tn-data.se:7001/api/payments HTTP/1.1 
Host: api.tn-data.se 
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjU1...

If the token is not found here, then you have problems with the client that sends the token and how to troubleshoot that is beyond the scope of this blog post.

How can I see the received access token using .NET code?

If you can’t use a tool like Fiddler to capture the access token, then you can for example, add the following event handler to the JwtBearer handler:

.AddJwtBearer(opt =>
{
    //...
    opt.Events = new JwtBearerEvents()
    {
        OnMessageReceived = msg =>
        {
            var token = msg?.Request.Headers.Authorization.ToString();
            string path = msg?.Request.Path ?? "";
            if (!string.IsNullOrEmpty(token))
            {
                Console.WriteLine("Access token");
                Console.WriteLine($"URL: {path}");
                Console.WriteLine($"Token: {token}rn");
            }
            else
            {
                Console.WriteLine("Access token");
                Console.WriteLine("URL: " + path);
                Console.WriteLine("Token: No access token providedrn");
            }
            return Task.CompletedTask;
        }
    };
});

(Alternatively, you can send the information to the log if writing to the console is not possible.)

A sample output when using the code above:

Access token URL: /api/payments 
Token: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjYwODE2RTk1MUU5NEJDMjEzNzEzN0Y0MUNGN0YwRDg3IiwidHlwIjoiYXQrand0In0.eyJpc3MiOiJodHRwczovL2lkZW…

It is important to not include this code in production, as writing to the console can result in a performance hit and writing to the console is an expensive operation.

How can I view the claims that the JwtBearer handler received?

To see a list of all the received claims, you can add the following event handler to JwtBearer:

.AddJwtBearer(opt =>
 {
     //...

     opt.Events = new JwtBearerEvents()
     {
         //...

         OnTokenValidated = ctx =>
         {
             Console.WriteLine();
             Console.WriteLine("Claims from the access token");
             if (ctx?.Principal != null)
             {
                 foreach (var claim in ctx.Principal.Claims)
                 {
                     Console.WriteLine($"{claim.Type} - {claim.Value}");
                 }
             }
             Console.WriteLine();
             return Task.CompletedTask;
         }
     };
 });

Running this code, you should see a list of the claims extracted from the access token written to the console. For example, it could look like this:

Claims from the access token
iss - https://localhost:6001
nbf - 1682863284
iat - 1682863284
exp - 1682923284
aud - payment
aud - invoice
aud - order
scope - openid
scope - profile
scope - email
scope - employee_info
scope - api
http://schemas.microsoft.com/claims/authnmethodsreferences - pwd
client_id - missingjwtbearer-claims-client
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier - 2
auth_time - 1682863282
http://schemas.microsoft.com/identity/claims/identityprovider - local
name - Bob Smith
seniority - Senior
contractor - no
http://schemas.microsoft.com/ws/2008/06/identity/claims/role - ceo
http://schemas.microsoft.com/ws/2008/06/identity/claims/role - finance
http://schemas.microsoft.com/ws/2008/06/identity/claims/role - developer
sid - C3768153BD5988F9B8B56D4A3AD518A1
jti - 5DB88EE876EF1B449E86930CE747AF3B

As you might notice above, some claims have been renamed to what Microsoft thinks the claims should be named.

You can disable this renaming by setting this flag to false:

.AddJwtBearer(opt =>
{
    // ...
    opt.MapInboundClaims = false;
    // ...
});

If you set the MapInboundClaims flag to false, then the output in my sample application changes to:

Claims from the access token
iss - https://localhost:6001
nbf - 1682863284
iat - 1682863284
exp - 1682923284
aud - payment
aud - invoice
aud - order
scope - openid
scope - profile
scope - email
scope - employee_info
scope - api
amr - pwd
client_id - missingjwtbearer-claims-client
sub - 2
auth_time - 1682863282
idp - local
name - Bob Smith
seniority - Senior
contractor - no
role - ceo
role - finance
role - developer
sid - C3768153BD5988F9B8B56D4A3AD518A1
jti - 5DB88EE876EF1B449E86930CE747AF3B

Upskill With Me: Courses, Workshops & Training

Fixing the ASP.NET Core username and roles properties

The next problem is fixing the name and roles of the user. Again, this is a common problem that I see on Stack Overflow.

To demonstrate this, I have created the following API action method:

[Authorize]
public ActionResult<Result> Get()
{
    var result = new Result();

    result.Name = User?.Identity?.Name ?? "Unknown Name";
    result.IsInRoleCEO = User?.IsInRole("ceo");

    result.Claims = User?.Claims.Select(c => c.Type + ":" + c.Value)?.ToList();

    return Ok(result);
}

public class Result
{
    public string? Name { get; set; }
    public bool? IsInRoleCEO { get; set; }
    public List<string>? Claims { get; set; }
}

The Name and IsInRoleCEO does not work. Why?

The short answer is that Microsoft has a different opinion of what the name of the claims should be when it looks for the name and role.

By default, it will look for these two claim types:

They are defined in the .NET source code here

To verify this, you can add the following code to a controller method, and it will print the name of the role/name claim type that it looks for:

var user = (ClaimsIdentity)User.Identity;
Console.WriteLine("Name claim type: " + user.NameClaimType);
Console.WriteLine("Role claim type: " + user.RoleClaimType);

This is the output:

Name claim type: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Role claim type: http://schemas.microsoft.com/ws/2008/06/identity/claims/role

To fix this, we need to set the name of your name/role claim to match what the claims are named inside the token. For example, in my case, the claims are named name and role:

.AddJwtBearer(opt =>
{
    // ...
    opt.TokenValidationParameters.RoleClaimType = "role";
    opt.TokenValidationParameters.NameClaimType = "name";
    // ...
});

With the code above in place, the code below should start to work as expected:

result.Name = User?.Identity?.Name ?? "Unknown Name";
result.IsInRoleCEO = User?.IsInRole("ceo");

In my example application, they will return:

…
"name": "Bob Smith",
"isInRoleCEO": true,
…

Final ASP.NET Core code:

The code for the API startup and sample controller:

Program class:

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(opt =>
    {
        opt.Authority = "[MyAuthority]";
        opt.Audience = "myaudience";

        opt.TokenValidationParameters.RoleClaimType = "role";
        opt.TokenValidationParameters.NameClaimType = "name";

        opt.MapInboundClaims = false;

        opt.Events = new JwtBearerEvents()
        {
            OnMessageReceived = msg =>
            {
                var token = msg?.Request.Headers.Authorization.ToString();
                string path = msg?.Request.Path ?? "";
                if (!string.IsNullOrEmpty(token))
                {
                    Console.WriteLine("Access token");
                    Console.WriteLine($"URL: {path}");
                    Console.WriteLine($"Token: {token}rn");
                }
                else
                {
                    Console.WriteLine("Access token");
                    Console.WriteLine("URL: " + path);
                    Console.WriteLine("Token: No access token providedrn");
                }
                return Task.CompletedTask;
            }
            ,

            OnTokenValidated = ctx =>
            {
                Console.WriteLine();
                Console.WriteLine("Claims from the access token");

                if (ctx?.Principal != null)
                {
                    foreach (var claim in ctx.Principal.Claims)
                    {
                        Console.WriteLine($"{claim.Type} - {claim.Value}");
                    }
                }
                Console.WriteLine();

                return Task.CompletedTask;
            }
        };
    });

Payment controller:

[Route("api/[controller]")]
[ApiController]
public class PaymentsController : ControllerBase
{
    [Authorize]
    public ActionResult<Result> Get()
    {
        var user = (ClaimsIdentity)User.Identity;
        Console.WriteLine("Name claim type: " + user.NameClaimType);
        Console.WriteLine("Role claim type: " + user.RoleClaimType);

        var result = new Result();

        result.Name = User?.Identity?.Name ?? "Unknown Name";
        result.IsInRoleCEO = User?.IsInRole("ceo");

        result.Claims = User?.Claims.Select(c => c.Type + ":" + c.Value)?.ToList();

        return (result);
    }
}

public class Result
{
    public string? Name { get; set; }
    public bool? IsInRoleCEO { get; set; }
    public List<string>? Claims { get; set; }
}

Claims diagnostic endpoint

It can be useful to create a diagnostic endpoint for debugging purposes that simply returns the claims found in the User object. Here’s a sample endpoint for ASP.NET Core:

[Authorize]
[Route("/api/tokendiagnostics")]
public IActionResult GetClaims()
{
    var result = new TestResult()
    {
        Name = User.Identity?.Name ?? "Unknown Name",
        Claims = (from c in User.Claims select c.Type + ":" + c.Value).ToList()
    };

    return new JsonResult(result);
}

public class TestResult
{
    public string? Name { get; set; }
    public List<string>? Claims { get; set; }
}

Conclusions

I hope the above steps can help you troubleshoot your JwtBearer claim problems. If you have any suggestions for this blog post, feedback, questions, or would like to get in touch, you can find my contact details here.

Debugging OpenID Connect Claim Problems in ASP.NET Core

Tore Nestenius — Tue, 28 Mar 2023 00:00:00 GMT

Missing claims in the ClaimsPrincipal user object is a frequent problem when using OpenID Connect authentication in ASP.NET Core. In this blog post, we’ll explore common causes behind these claim issues and provide troubleshooting steps to help you identify and resolve them effectively.

What is the purpose of the OpenIDConnect handler?

The handler has two main tasks:

When the user is challenged (requested to log in), it will redirect the user to the authorization provider, for example, Duende IdentityServer.

2. When the user is returned to the handler, it will request the tokens from the authorization provider using the authorization code and create an authentication ticket. This ticket is typically passed to the cookie handler, setting the session cookie.

Does the authorization server actually provide the claims?

The OpenIDConnect handler will get the claims from two sources:

The ID-Token
Optionally, from the UserInfo endpoint.

Using a tool like Fiddler, you can capture the ID token and the optional request to the UserInfo endpoint.

Why does it use two sources? One reason is that it reduces the size of the ID token. The UserInfo endpoint is also helpful because it lets the client get the latest user details when needed. You can read more about the specification for the UserInfo endpoint here.

If the expected claims are not found in the ID token, then enabling the GetClaimsFromUserInfoEndpoint flag will tell the OIDC handler to make an additional request to this endpoint.

.AddOpenIdConnect(options =>
{
    ...
    options.GetClaimsFromUserInfoEndpoint = true;
	...
}

For example, when using IdentityServer, the request to this endpoint and its response can look like this:

Request:

GET https://identityservice.secure.nu/connect/userinfo HTTP/1.1
Host: identityservice.secure.nu
Authorization: Bearer <accesstoken>
User-Agent: Microsoft ASP.NET Core OpenIdConnect handler

Response:

{
  "name": "Bob Smith",
  "given_name": "Bob",
  "family_name": "Smith",
  "email": "BobSmith@email.com",
  "email_verified": true,
  "website": "http://bob.com",
  "employment_start": "2019-01-02",
  "seniority": "Senior",
  "contractor": "no",
  "role": [
    "ceo",
    "finance",
    "developer"
  ],
  "sub": "2"
}

How can I see these raw claims using code?

One approach is to add this piece of configuration code that sends all the claims received from the ID token and UserInfo endpoint to the console:

.AddOpenIdConnect("oidc", options =>
{
    //...
    options.Events.OnUserInformationReceived = ctx =>
    {
        Console.WriteLine();
        Console.WriteLine("Claims from the ID token");
        foreach(var claim in ctx.Principal.Claims)
        {
            Console.WriteLine($"{claim.Type} - {claim.Value}");
        }
        Console.WriteLine();
        Console.WriteLine("Claims from the UserInfo endpoint");
        foreach (var property in ctx.User.RootElement.EnumerateObject())
        {
            Console.WriteLine($"{property.Name} - {property.Value}");
        }
        return Task.CompletedTask;
    };
};

Notice that all claims received are listed above. However, some claims might have been renamed internally.

In my sample application, I will see the following claims written to the console:

Claims from the ID token
iss - https://identityservice.secure.nu
nbf - 1679224115
iat - 1679224115
exp - 1679224415
aud - missingclaims-client
http://schemas.microsoft.com/claims/authnmethodsreferences - pwd
nonce - 638148209061465255...
at_hash - htlWY11Ch-wCFfRAlusRRw
sid - 04D122AC27794662F59D55E9D6E85022
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier - 2
auth_time - 1679224111
http://schemas.microsoft.com/identity/claims/identityprovider - local

Claims from the UserInfo endpoint
name - Bob Smith
given_name - Bob
family_name - Smith
email - BobSmith@email.com
email_verified - True
website - http://bob.com
employment_start - 2019-01-02
seniority - Senior
contractor - no
role - ["ceo","finance","developer"]
sub - 2

As you noticed above, some claims have been renamed to what Microsoft thinks the claims should be named internally.

You can disable this renaming by setting this flag to false:

.AddOpenIdConnect("oidc", options =>
{
    //...
    options.MapInboundClaims = false;
}

You can move to the next step if the expected claims are found above. Otherwise, you have a configuration issue in your authorization server or are asking for the wrong scopes.

If you’re curious, the actual mapping logic is found in the JwtSecurityTokenHandler class, and the source code for it can be found here.

What about the claims in the access token?

The access token is only used to access APIs. This means the handler does not care what is inside the access token. So, we will ignore what it contains. I have written a blog post about debugging JwtBearer API claim problems.

OpenID Connect handler and the authentication ticket

You have determined that the claims you are looking for are passed to the OpenIConnect handler as expected.
Great! So, why are the claims not part of the User object? First, let’s explore the Cookie handler.

When the OpenID Connect handler is done, it will create an authentication ticket and ask the cookie handler to sign in the user using this ticket. The ticket contains the claims and other details about the user, as shown below:

By adding the following event handler to the Cookie handler, we can see what claims it has received:

.AddCookie("cookie", options =>
{
    ...
    options.Events.OnSigningIn = ctx =>
    {
        Console.WriteLine();
        Console.WriteLine("Claims received by the Cookie handler");
        foreach (var claim in ctx.Principal.Claims)
        {
            Console.WriteLine($"{claim.Type} - {claim.Value}");
        }
        Console.WriteLine();
        return Task.CompletedTask;
    };
})

In my example, I get the following:

Claims received by the Cookie handler
amr - pwd
sid - 233D90C7590B9405E6EAFBE8BBF9A167
sub - 2
auth_time - 1679224198
idp - local
name - Bob Smith
given_name - Bob
family_name - Smith
email - BobSmith@email.com

I would expect something else! So, what is going on here?

Inside the OpenID Connect handler is a separate ClaimsMapper function that will remove unnecessary claims and only include some specific ones.

The default mapping is found in the OpenIdConnectOptions class, and it looks like this:

...
ClaimActions.DeleteClaim("nonce");
ClaimActions.DeleteClaim("aud");
ClaimActions.DeleteClaim("azp");
ClaimActions.DeleteClaim("acr");
ClaimActions.DeleteClaim("iss");
ClaimActions.DeleteClaim("iat");
ClaimActions.DeleteClaim("nbf");
ClaimActions.DeleteClaim("exp");
ClaimActions.DeleteClaim("at_hash");
ClaimActions.DeleteClaim("c_hash");
ClaimActions.DeleteClaim("ipaddr");
ClaimActions.DeleteClaim("platf");
ClaimActions.DeleteClaim("ver");

// http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
ClaimActions.MapUniqueJsonKey("sub", "sub");
ClaimActions.MapUniqueJsonKey("name", "name");
ClaimActions.MapUniqueJsonKey("given_name", "given_name");
ClaimActions.MapUniqueJsonKey("family_name", "family_name");
ClaimActions.MapUniqueJsonKey("profile", "profile");
ClaimActions.MapUniqueJsonKey("email", "email");

To get the desired claims to be added, we need to explicitly map the ones that we want:

AddOpenIdConnect("oidc", options =>
{
    //...
    options.ClaimActions.MapUniqueJsonKey("employment_start", "employment_start");
    options.ClaimActions.MapUniqueJsonKey("seniority", "seniority");
    options.ClaimActions.MapUniqueJsonKey("contractor", "contractor");
    options.ClaimActions.MapUniqueJsonKey("employee", "employee");
    options.ClaimActions.MapUniqueJsonKey("management", "management");
    options.ClaimActions.MapUniqueJsonKey(JwtClaimTypes.Role, JwtClaimTypes.Role);
};

What is the result if we do this?

Claims received by the Cookie handler
amr - pwd
at_hash - nlHaI2Y0sZo6B2rctDULnw
sid - 01616A969D17F7F92EEEDF7B7CA18BEC
sub - 2
auth_time - 1679224524
idp - local
name - Bob Smith
given_name - Bob
family_name - Smith
email - BobSmith@email.com
email_verified - True
website - http://bob.com
employment_start - 2019-01-02
seniority - Senior
contractor - no
role - ["ceo","finance","developer"]

Alternatively, we can do the following as a shortcut:

options.ClaimActions.MapAllExcept("iss", "nbf", "exp", "aud", "nonce", "iat", "c_hash");

Doing so will result in the following:

Claims received by the Cookie handler
amr - pwd
at_hash - nlHaI2Y0sZo6B2rctDULnw
sid - 01616A969D17F7F92EEEDF7B7CA18BEC
sub - 2
auth_time - 1679224524
idp - local
name - Bob Smith
given_name - Bob
family_name - Smith
email - BobSmith@email.com
email_verified - True
website - http://bob.com
employment_start - 2019-01-02
seniority - Senior
contractor - no
role - ["ceo","finance","developer"]

Fixing the user name and roles claims

The next problem is to fix the User name and roles. Again, this is a common problem on Stack Overflow.

To get the name of the user, or check if the user is in a given role, you add the following code to any of your action methods:

public IActionResult Index()
{
    if (User.Identity.IsAuthenticated)
    {
        var name = User.Identity.Name;
        var isCeo = User.IsInRole("ceo");
		
        Console.WriteLine(name);    //null
        Console.WriteLine(isCeo);   //false
    }
	
    return View();
}

So, let’s fix this!

One problem is the claims mapping. Microsoft has a different opinion of what the name and role claim should be named, and out of the box, it will just ignore your name and role claims because it thinks they should have a different name.

By default, it will look for these two claim types:

OpenID Connect claim type	Microsoft claim type
role	http://schemas.microsoft.com/ws/2008/06/identity/claims/role
name	http://schemas.microsoft.com/ws/2008/06/identity/claims/name

They are defined in the .NET source code here.

To verify this, you can run this code, It will print the name of the expected role/name claim, like this:

if (User.Identity.IsAuthenticated)
{
    var user = (ClaimsIdentity)User.Identity;
    Console.WriteLine(user.NameClaimType);
    Console.WriteLine(user.RoleClaimType);
}

It will print:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name 
http://schemas.microsoft.com/ws/2008/06/identity/claims/role

To fix this, we need to set the name of your name and role claim as:

.AddOpenIdConnect(options =>
{
    ...
    options.TokenValidationParameters = new TokenValidationParameters
    {
        NameClaimType = "name",
        RoleClaimType = "role"
    };
    ...
}

If we log in again, we will see this code:

if (User.Identity.IsAuthenticated)
{
    var user = (ClaimsIdentity)User.Identity;
    Console.WriteLine(user.NameClaimType);    //name
    Console.WriteLine(user.RoleClaimType);    //role

    var name = User.Identity.Name;
    var isCeo = User.IsInRole("ceo");

    Console.WriteLine(name);                 //Bob Smith
    Console.WriteLine(isCeo);                //false
    //....
}

Which will print the following:

name
role
Bob Smith
False

We fixed the name, but the role check still fails. Strange!

Fixing the roles claim

To fix the roles, we must first examine the claims provided to the Cookies handler.

Claims received by the Cookie handler
…
contractor - no
role - ["ceo","finance","developer"]

Here we see that all of our roles are added as an array to the role claim, and that is now what the IsInRole method expects.

What is the problem here?

The first problem is this statement:

options.ClaimActions.MapAllExcept("iss", "nbf", "exp", "aud", "nonce", "iat", "c_hash");

It will map multiple claims with the same name into an array.

Let’s remove it and replace it with the mapping we used earlier:

options.ClaimActions.MapUniqueJsonKey("employment_start", "employment_start");
options.ClaimActions.MapUniqueJsonKey("seniority", "seniority");
options.ClaimActions.MapUniqueJsonKey("contractor", "contractor");
options.ClaimActions.MapUniqueJsonKey("employee", "employee");
options.ClaimActions.MapUniqueJsonKey("management", "management");
options.ClaimActions.MapUniqueJsonKey(JwtClaimTypes.Role, JwtClaimTypes.Role);

Using this code will result in the same result. So, this is clearly not a fix!

The problem is the MapUniqueJsonKey method that will map duplicate claims into an array. So, we should use is the MapJsonKey method instead, like this:

options.ClaimActions.MapUniqueJsonKey("employment_start", "employment_start");
options.ClaimActions.MapUniqueJsonKey("seniority", "seniority");
options.ClaimActions.MapUniqueJsonKey("contractor", "contractor");
options.ClaimActions.MapUniqueJsonKey("employee", "employee");
options.ClaimActions.MapUniqueJsonKey("management", "management");
options.ClaimActions.MapJsonKey(JwtClaimTypes.Role, JwtClaimTypes.Role);

If we log in again, we will see the following claims in the Cookies handler:

Claims received by the Cookie handler … seniority - Senior contractor - no role - ceo role - finance role - developer

Now, the IsInRole (“ceo”) check will also work!

Summary

The final code for the OpenID Connect handler is as follows:

.AddOpenIdConnect("oidc", options =>
{
    //...
    options.GetClaimsFromUserInfoEndpoint = true;
	
    options.TokenValidationParameters = new TokenValidationParameters
    {
        NameClaimType = JwtClaimTypes.Name,
        RoleClaimType = JwtClaimTypes.Role,
    };
	
    options.ClaimActions.MapUniqueJsonKey("employment_start", "employment_start");
    options.ClaimActions.MapUniqueJsonKey("seniority", "seniority");
    options.ClaimActions.MapUniqueJsonKey("contractor", "contractor");
    options.ClaimActions.MapUniqueJsonKey("employee", "employee");
    options.ClaimActions.MapUniqueJsonKey("management", "management");
	
    options.ClaimActions.MapJsonKey(JwtClaimTypes.Role, JwtClaimTypes.Role);
	
    options.MapInboundClaims = false;
    //...
});

Conclusions

I hope the steps outlined above can help you troubleshoot your claim problems. If you have any suggestions for this blog post, feedback, questions on this blog post, or would like to get in touch, you can find my contact details here.

Troubleshooting JwtBearer authentication issues in ASP.NET Core

Tore Nestenius — Tue, 21 Feb 2023 00:00:00 GMT

One of the most frequent questions I encounter on Stack Overflow is how to troubleshoot JwtBearer authentication issues in ASP.NET Core. In this post, I’ll share top tips and solutions to help you resolve common JwtBearer handler problems effectively.

The JwtBearer handler

We add the JwtBearer handler to the authentication middleware in our ASP.NET Core request pipeline, as shown in the picture below:

The main purpose of this handler is to look for an access token in the incoming HTTP request and if it is found, create an authenticated ClaimsPrincipal user instance, as shown below:

Troubleshooting JwtBearer authentication problems

The first thing to look at is the status code that is returned in the response from your API, as it will guide you to where to start looking for the problem.

401 UnauthorizedThis error is typically generated by the JwtBearer handler, and it means that the incoming token is not found, valid or accepted.
403 ForbiddenThis error is returned if the token is accepted but the user is not authorized to access the API resource. The authorization handler typically generates this error, and a common problem here is that the user object does not contain some of the required claims. Debugging authorization problems are not covered in this blog post.

If you get other status codes, this means it is likely that problem is elsewhere. Such as, 400 bad request or 500 server error.

Verify the order of the middleware modules.

The next thing is to ensure that the order of the authentication and authorization middleware in your request pipeline is correct. You must do authentication before you can do authorization.

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

The JwtBearer WWW-Authenticate header

If you have verified that the returned status code is 401, then the next step is to look at the WWW-Authenticate response header.

By default, the JwtBearer handler will include a WWW-Authenticate header in the response, as shown below:

HTTP/1.1 401 Unauthorized Date: Sun, 02 Aug 2020 11:19:06 GMT WWW-Authenticate: Bearer

By default, this header does not say that much, but you can get a more detailed error message by setting the IncludeErrorDetails flag to true, as shown below:

.AddJwtBearer(opt =>
{
    opt.IncludeErrorDetails = true;
    ...
}

Enabling this flag will result in that a more detailed error message in the WWW-Authenticate header, as shown below:

HTTP/1.1 401 Unauthorized Date: Sun, 02 Aug 2020 11:19:06 GMT WWW-Authenticate: Bearer error="invalid_token", error_description="The signature is invalid"

Most of the time, this can give you a good clue about the source of the problem.

Don’t forget to make sure this flag is set to false in production, as it might otherwise leak clues to an attacker attacking your API.

You can read more about the purpose of this header here:

Exploring the JwtBearer logs

If the previous steps did not identify the problem, then the next step is to look at the log statements generated by the authentication and authorization middleware in ASP.NET Core.

If you manage your logging in appsettings.json files, then you can add and lower the logging levels to debug or trace, like this:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.AspNetCore.Authentication": "debug",
      "Microsoft.AspNetCore.Authorization": "debug"
    }
  }
}

Follow this link for more details about how logging works in ASP.NET Core.

If I don’t have any logging infrastructure ready, I typically use Serilog and send all my log entries to Seq for further analysis.

JwtBearer Claim problems

If you have problems with your User or Claims, then head over to my blog post Debugging JwtBearer Claim Problems in ASP.NET Core

Conclusions

I hope the steps outlined above can help you troubleshoot your APIS and If you have any suggestions for this blog post, feedback, or questions on this blog post or would like to get in touch, you can find my contact details here.

IdentityServer - IdentityResource vs. ApiResource vs. ApiScope

Tore Nestenius — Thu, 02 Feb 2023 00:00:00 GMT

Understanding the differences between IdentityResource, ApiResource, and ApiScope in Duende IdentityServer is a common question among developers, often seen on platforms like Stack Overflow.

My answer to this question has gained significant traction as one of my most upvoted responses. In this blog post, I’ll dive deeper into these resource types, explaining what they are, how they function, and their impact on your IdentityServer setup.

Back to basics

In IdentityServer, there are three types of resources

IdentityResources
ApiScopes
ApiResources

How are these related, and what do they control?

Before we can answer this, we need to take one step back and talk about scopes.

**Scopes in OpenID Connect

When the client application authenticates, it will ask Duende IdentityServer for a set of scopes, as the picture below shows:

The list of scopes represents a mixed list of what the client wants to get back. So far, so good!

As the picture shows above, we can divide the list of scopes into two categories:

**Identity scopes
**Scopes that are all about what information the client wants to know about the user
**Access scopes
**Scopes that represent what the client wants to have access to.

These two categories control what goes into the id and access token.

Identity Scopes

The Identity scopes control what goes into the ID token (or is available from the UserInfo endpoint). In IdentityServer, we define these scopes using IdentityResources.

The three identity scopes in our example above can, in code, be defined as follows:

_identityResources = new List<IdentityResource>()
{
    new IdentityResources.OpenId(),
    new IdentityResources.Email(),
    employeeInfoScope
};

var employeeInfoScope = new IdentityResource()
{
    Name = "employee_info",
    DisplayName = "Employee information",
    Description = "Employee information including seniority and status...",
};

In the code above, we define that clients can ask for the standardized openid and email scope and a custom scope named employee_info.

The employee_info scope, as defined above, is pretty useless. We also typically want to add what claims this scope represents.

The following picture shows how the identity resources are connected to a set of claims:

The list of requested claims represents what claims will end up in the ID token. Don’t forget that only the claims found in the user database will be included.

In code, this means that we will add a list of user claims to our custom scope:

var employeeInfoScope = new IdentityResource()
{
    Name = "employee_info",
    DisplayName = "Employee information",
    Description = "Employee information including seniority and status...",
    UserClaims = new List<string>
    {
        "employment_start",
        "seniority",
        "contractor"
    }
};

Access scopes

The access scopes control what APIs and services the client application wants to access and what should go into the access token. In IdentityServer, we define these scopes using ApiScopes.

In code, we can define them as shown in this example:

_apiScopes = new List<ApiScope>()
{
    new ApiScope()
    {
        Name = "payment",
        DisplayName = "Payments access",
        Description = "Access to the payment related services.",
        UserClaims = new List<string>
        {
            //These claims will be added to the access token, not the ID-token!
            "bonuslevel",
            "sendpayments"
        }
    },
	
    new ApiScope()
    {
        Name = "invoice",
        DisplayName = "Invoices access",
        UserClaims = new List<string>
        {
            "approveinvoices",
            "sendinvoices"
        }
    }
};

The image below shows how the APIScopes and user claims are related based on the code above:

The requested claims will be added to the access token, not the id token. These claims are useful when, for example, services and APIs need to authorize received access tokens.

Also, it is important to note that the requested scopes (IdentityResources and ApiScopes) are what the user will give consent to during authentication:

**API Resources in IdentityServer

Defining IdentityResources and ApiScopes is a good start, but we can improve our setup by introducing API Resources.

One problem with the current setup is that the aud claim inside the access token contains a generic value:

{
"iss": "https://identity.secure.nu:6001",
"aud": "https://identity.secure.nu:6001/resources",
"scope": [
  "openid",
  "email",
  "employee_info",
  "payment",
  "invoice"
],

If we set the EmitStaticAudienceClaim setting to false in IdentityServer:

builder.Services.AddIdentityServer(options =>
{
    options.EmitStaticAudienceClaim = false;
})

Then the aud claim is not even included:

{
"iss": "https://identity.secure.nu:6001",
"scope": [
  "openid",
  "email",
  "employee_info",
  "payment",
  "invoice"
],
...

The access tokens above are a bit too generic, and we often want a more “targeted” access token. That allows the intended service receiving the token to verify that the service is the intended target for the token.

Introducing IdentityServer API Resources

By introducing APIResources, we can control what goes into the audience (aud) claim and further improve our setup. For example, we can define two ApiResources as follows:

var paymentApi = new ApiResource()
{
    Name = "paymentapi",
    Scopes = new List<string> { "payment" },
    UserClaims =
    {
        //Custom user claims that should be provided when requesting access to this API.
        //These claims will be added to the access token, not the ID token!
        "employee",
        "contractor"
    }
};

var invoiceApi = new ApiResource()
{
    Name = "invoiceapi",
    Scopes = new List<string> { "invoice" },
};

_apiResources = new List<ApiResource>()
{
    paymentApi,
    invoiceApi,
};

The image below shows the relationship between the ApiScopes and ApiResources as defined in the code above:

When adding these two APIResources, the access token will now contain the following:

{
  "iss": "https://identity.secure.nu:6001",
  "aud": [
    "paymentapi",
    "invoiceapi"
  ],
  "scope": [
    "openid",
    "email",
    "employee_info",
    "payment",
    "invoice"
  ],
  "contractor": "no",
  "employee": "yes",
  "approveinvoices": "no",
  "sendinvoices": "yes",
  "sendpayments": "yes",
  "bonuslevel": "42",
...

The API can verify if it is the intended target by checking the aud claim inside the received access tokens. In addition, the use claims defined in the ApiScopes and ApiResources are also included in the access token.

As described in the Duende IdentityServer documentation, adding ApiResources gives you these additional benefits:

support for the JWT aud claim. The value(s) of the audience claim will be the name of the ApiResource(s)
support for adding common user claims across all contained scopes
support for introspection by assigning an API secret to the resource
support for configuring the access token signing algorithm for the resource

Resources

Feedback, comments, found any bugs?

If you have any feedback or questions on this blog post or would like to get in touch, you can find my contact details here.

I was interviewed by RetroRGB

Tore Nestenius — Wed, 23 Feb 2022 00:00:00 GMT

After my blog post about my Sega Mega Drive project, RetroRGB contacted me and wanted to interview me on their YouTube channel.

This was my first major podcast/interview and was a very fun experience. You can view the interview here.

ASP.NET Core 6 - JwtBearer library: what’s new?

Tore Nestenius — Fri, 04 Feb 2022 00:00:00 GMT

As a developer and trainer, it is hard to keep up with all the changes in all the libraries. In this blog post, I will summarize the recent key changes that I have found in the ASP.NET Core JwtBearer library versions 3.1.22, 5.0.13, and 6.0.1.

The JwtBearer library is distributed in the Microsoft.AspNetCore.Authentication.JwtBearer NuGet package. The corresponding source code can be found in the /src/Security/Authentication/ folder in the ASP.NET Core repository on GitHub.

What is the purpose of the ASP.NET Core JwtBearer library?

The library is implemented as an ASP.NET Core request pipeline middleware, and its sole purpose is to authenticate incoming requests. It will look for JW bearer tokens in the request and, if a token is found, validate it and create a ClaimsPrincipal User instance. The authorization handler can then authorize the user to get access to the requested resource.

What runtime does each version target?

The different versions of the JwtBearer NuGet package target different runtimes:

Version 3.x.x targets .NET Core 3.1
Version 5.x.x targets .NET 5.x
Version 6.x.x targets .NET 6.x

That sounds obvious and logical, but the annoying thing with Visual Studio (as of today) is that, even if you have a .NET Core 3.1 application, it still tells you that version 6 is available, even though it should know that version 6.x.x is not compatible with your current project:

As a good developer, you want to keep your packages up to date, but trying to update it will result in the following error:

This sure is a bit annoying 🙄

Comparing the editions of JwtBearer

To do the research, I really like to get down to the true source, and the best source is of course the ASP.NET source code. So I downloaded it for the three different versions and then compared the result using Araxis merge. I could have done the same comparisons using NDepend, but I chose to use Araxis merge because it gave me the best overview for this blog post. Using Araxis merge I can compare all three versions at the same time as shown below:

The interesting source code for the authentication handlers in ASP.Net Core is found in the /src/Security/Authentication/ directory on GitHub.

What has changed between the revisions of JwtBearer?

There are, of course, plenty of small changes in this library, and many of the changes consist of added XML comments and improved support for non-nullable reference types.

But let’s look at the ones that actually matter for us using this library:

Map inbound claims option

This feature, which was introduced in version 5, allows us to very easily disable one of the most annoying features in the .NET authentication stack, and that is the automatic renaming of some of the claims found in the token.

The flag is by default set to true, but can now easily be disabled using:

services.AddAuthentication()        .AddJwtBearer(options =>{    options.MapInboundClaims = false;    //...});

Let’s compare the result when this flag is false or true. If we send the following access token in a request to the library:

{    
    "nbf": 1642960856,
	"exp": 1642964456,
	"iss": "https://localhost:6001",
	"aud": "paymentapi",
	"client_id": "client",
	"managment": "yes",
	"email": "tn@tn-data.se",
	"name": "tore nestenius",    
	"role": [ "admin", "developer", "support" ],  
	"website": "https://www.tn-data.se",    
	"jti": "9320D007CFA6EF1C21ACA09908216BC7",    
	"iat": 1642960856,    
	"scope": [ "payment" ]

Then the resulting ClaimsPrincipal User will contain the following set of claims:

MapInboundClaims = false

Claims 
 - nbf=1642960856
 - exp=1642964456
 - iss=https://localhost:6001
 - aud=paymentapi
 - client_id=client
 - managment=yes
 - email=tn@tn-data.se
 - name=tore nestenius
 - role=admin
 - role=developer
 - role=support
 - website=https://tn-data.se
 - iat=1642960856
 - scope=payment

MapInboundClaims = true

Claims
 - nbf=1642961012
 - exp=1642964612
 - iss=https://localhost:6001 
 - aud=paymentapi
 - client_id=client
 - managment=yes
 - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress=tn@tn-data.se
 - name=tore nestenius
 - http://schemas.microsoft.com/ws/2008/06/identity/claims/role=admin
 - http://schemas.microsoft.com/ws/2008/06/identity/claims/role=developer
 - http://schemas.microsoft.com/ws/2008/06/identity/claims/role=support
 - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage=https://tn-data.se
 - iat=1642961012
 - scope=payment

I have answered questions about claims mapping on Stack Overflow for quite some time now and I wish this flag was set to false by default. This would have made life so much easier for developers working with claims.

Customizing the JwtBearer back channel HttpClient

The JwtBearer will, via the Configuration Manager, make HTTP(s) requests to our identity provider through the back channel. For example, it will use this channel to download the openid-configuration and the public keys from the authorization provider (for example IdentityServer).

Before version 6, we could provide our own HttpMessageHandler to customize the BackChannel request and response, by for example:

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)        .AddJwtBearer(opt =>{   opt.BackchannelHttpHandler = new MyBackChannelListener();   //...};

Why would you want to provide your own? Some of the use-cases can be:

Improve logging of the backchannel requests
Add custom headers to the outgoing request
Inspect the response
Implement automatic retry when a request fails, perhaps using the Polly Project library.

In version 6 they also introduced the option to provide your own HttpClient instance. This was added as a response to GitHub issue #27426.

This allows us to provide our own client like this:

builder.Services.AddAuthentication()       .AddJwtBearer(options =>{      options.Backchannel = new HttpClient()        {              //Custom client options        };});

Why would you want to provide your own client?

Work with the HttpClientFactory
Better control of the HTTP protocol to be used
(i.e., only use HTTP/2 or HTTP/1.1)

Some related resources

Customizing the configuration refresh intervals

In .NET 5 they introduced two new options to control the backchannel refresh intervals and you define them in code using:

 services.AddAuthentication().AddJwtBearer(options =>
 {
     //.NET 5 defaults        
	 options.AutomaticRefreshInterval = new TimeSpan(1, 0, 0, 0);   //24 hours        
	 options.RefreshInterval = new TimeSpan(0, 0, 0, 30);           //30 seconds

     //.NET 6 defaults
     options.AutomaticRefreshInterval = new TimeSpan(0, 12, 0, 0);  //12 hours      
	 options.RefreshInterval = new TimeSpan(0, 0, 5, 0);            //5 minutes   
});

In .NET 6 they changed the default values as shown above, but the main question is of course, what do they control?

Automatic refresh interval

This parameter will control how often it will download and refresh the cached openid-configuration and the JWKS signing keys.

Refresh interval

If a back channel request to the identity provider fails, then this value will control the wait time between retries. If it fails to refresh the configuration, then it will keep using the existing configuration that was retrieved earlier.

JwtBearer Dependencies

The JwtBearer also depends on a few other libraries, which are:

These three libraries are all located in a different repository named azure-activedirectory-identitymodel-extensions-for-dotnet. It is not located under the ASP.NET Core, instead it is located under the AzureAD organization.

The versioning of these packages does not follow the same versioning pattern as ASP.NET Core does, so in my investigation, I used the following versions:

ASP.NET Core 3.1 -> JwtBearer (3.1.22) -> …OpenIDConnect (5.5.0)
ASP.NET 5.0-> JwtBearer (5.0.13) -> …OpenIDConnect (6.7.1)
ASP.NET 6.0 -> JwtBearer (6.0.1) -> …OpenIDConnect (6.10.0)

Naturally there have been numerous improvements here too, but for those of us who are working with APIs, the TokenValidationParameters is the most interesting one for us.

services.AddAuthentication().AddJwtBearer(options =>
{
    //For example      
	options.TokenValidationParameters.ValidateIssuer = false;
    ...
}

What interesting changes are here? If we compare version 5.5.0 with 6.10.0, we see that some of the most interesting changes are the following:

New validation delegates
- AlgorithmValidator
  By providing a custom delegate to this parameter, you can do your own validation of the cryptographic algorithm used. If provided, then the valid algorithms provided in the ValidAlgorithms parameter will be ignored. Discussions about this delegate can be found here.
- TypeValidatorBy providing a custom delegate to this parameter, you can do your own token type validation instead of the built-in default one. Discussions about this delegate can be found in Issue 1378 and Issue #1385
New properties
- IgnoreTrailingSlashWhenValidatingAudience
  Setting this property will control if a ’/’ is significant at the end of the audience or not. (default true)
- TryAllIssuerSigningKeysWill control whether all the signing keys should be tried during signature validation when the referred key in the token is not found. (default true)
- ValidAlgorithms
  Contains a list of the valid algorithms for cryptographic operations.
- ValidTypes
  Contains a list of the valid token types.

Conclusion

Keeping up with all the changes in the .NET stack is hard and using Araxis merge allowed me to quickly compare three versions of the code base at the same time. The most annoying thing when dealing with the authentication stack is that the code involved is located in two different repositories and it is really annoying that the code in the AzureAD repository is not covered by https://source.dot.net/, which otherwise is very handy when searching the Microsoft code base.

When I create my training materials I often do dive deep into the .NET source code, and looking under the hood gives you another perspective on how things actually work and the amazing work the .NET developers put into the stack!

While browsing the source code I found some inaccuracies in the code XML comments, so I filed an issue to the ASP.NET Core team on GitHub here and it was quickly resolved within a few days.

I have built training courses about this topic and it has helped several companies move forward with their journey. Check out the courses here.

How I built my own Sega Mega Drive hardware dev kit from scratch

Tore Nestenius — Tue, 18 Jan 2022 00:00:00 GMT

Introduction

Over 30 years ago, I decided to take on the challenge of building my own Sega Mega Drive hardware dev kit from scratch. At the time, I was eager to develop games and wanted to target a powerful platform beyond the Atari 1040 STE I had. After discovering the Sega Mega Drive and getting hooked on its incredible hardware and games like Sonic and Revenge of Shinobi, I set out to create a dev kit without official documentation or a development kit, just a Sega Mega Drive and a lot of determination.

Eventually, I got the crazy idea that I wanted to develop games for this machine. But surely I would need some crazy expensive and hard-to-get hardware to do that? I had no official developer kit, no money to buy one, no documentation, just a Mega Drive.

So I thought, how hard can it be to build my own kit?

First some sanity checks

But wait? Was I crazy or what? Why did I think I would be able to pull this off?

The Sega Mega Drive is based around the Motorola MC68000 CPU, a CPU that I was very familiar with on the lowest chip level. It also has a separate Z80 co-processor for audio and other tasks that I was slightly familiar with.
I was very familiar with the MC68000 assembly language, after many years of low-level assembly demo-programming on the Atari ST home computer. I am one of the original members of SYNC, an Atari ST demo group in Sweden. You can read more about SYNC here and here, and we sure did some quite crazy things on the Atari ST back in the day.

I had tinkered and played with electronics and built small computers for a long time – here are some of the random projects from back in the day. However, I don’t remember what they do :-)

How to approach the challenge?

My goal was to design and build a kit that, without modifying the Sega Mega Drive, would allow me to “simulate” a game cartridge using static ram memory. The kit would then be connected to my Atari ST computer where I would be doing the actual programming. An overview of the kit:

The Sega Mega Drive Cartridges

The first challenge was to reverse engineer a game cartridge and figure out the pin layout of the edge connector. The circuit board inside a cartridge looks like this:

After a lot of research in various chip reference books, I eventually figured out it was a standard ROM chip. With that knowledge it made it pretty simple to figure out what most pins on the edge connector were.

However, there were still some other pins that I needed to figure out to be able to do a complete development kit.

The Sega Mega Drive Game Slot

Figuring out what the pins meant on the cartridge connector inside the Mega Drive was the next challenge. Inside the console, the connector is located next to the 68K CPU and it looks like this:

Using my multimeter, I was able to trace most of the connectors directly to the well-known pin layout of the CPU

However, there were one or two pins where I could not figure out what they did. And without a proper logic analyzer, it would have been pretty hard to figure out what they did. As I was on a very tight budget, I decided to build my own. How hard could that be? After some thinking I figured out that all I needed was to get an 8-bit 2 KB FIFO buffer chip and use it to sample the signals when the console starts up after a reset sequence. By doing this, I could look at the signals and try to decode their relationship with some of the other well-known pins on the CPU bus. As I was very familiar with how the MC68K CPU bus works, I was up to the challenge.

Basically, what I wanted to do was:

But how could I get hold of a FIFO-buffer chip?

At the time I was staying in Paris with a friend, where we were finalizing a music sound tracker called Audio Sculpture for the Atari ST that we had sold to a French publisher.

So, back to getting hold of the chip. I somehow found out about an electronics trade show in Paris, so I decided to go there with the goal of asking for a FIFO-buffer engineering sample. I eventually found a helpful company that would give me an engineering sample chip for free. Awesome!

Here are some links about the Audio Sculpture sound tracker we published:

Audio Sculpture Demo Disk by SYNC and Expose Software on Atari ST
Audio Sculpture at Atari mania.

But how would I get the data out of the FIFO-buffer?

My Atari ST had an expansion port that directly exposed the CPU bus inside the computer, so with some logic, I tied the FIFO-buffer to this port. I wrote some software to extract the data from the buffer and display it to the screen. Using this technique I was eventually able to figure out the purpose of the mysterious pins.

Now I had solved the layout of the cartridge port in the console. On to the next challenge!

Getting my code into the Mega Drive

With the hardware all figured out, I now needed to figure out how I would be able to write software for the console.

My idea was to have a small boot firmware that, at startup, would wait for a binary data dump from my Atari ST. I would connect the kit to my Atari using a home-built transfer protocol that would send it over an 8-bit parallel cable, similar to the parallel printer post most PCs had back in the day.

At startup the Mega Drive boots from the game cartridge, so all I had to do was to add a small boot-firmware that would, at startup, accept the binary data dump and, after receiving the dump, it should start to execute the code. I used two 8-bit EPROM chips to hold the actual firmware.

I did manage to locate some of the source code for the firmware and I have published the code as a GitHub GIST (Not sure if it is the final one) and in this GIST.

The development kit memory board

My design consisted of two circuit boards, one memory board that just held the static ram memory and one logic board for all the rest.

To store the game I created a memory board that consisted of ten 128 KB static ram memory chips (KM681000LP-8) with a total capacity of 1280 KB. At that time most games on the Mega Drive required 256–512 KB of storage while some needed more.

Besides the memory chips, I added the following buffers to the memory board, just to be sure that I would not overload the system bus on the Mega Drive:

Two 74HC245 – 8-bit bi-directional transceiver for the data bus
Three HC541 – 8-bit driver for the address bus

For the memory board, I eventually designed some proper circuit boards and also created a few different revisions of the board – here are a few of them:

I was able to extract the PCB layout files from the old DOS-based circuit board designer software that I used, using the DOSBox-X DOS emulator, and here is the result:

The development kit logic board

The second circuit board that this kit consisted of contained the following parts:

Two EPROM chips that held the startup firmware
Glue logic
Connector to the memory board
Connector to the host computer

The board went through several iterations, where the one in the middle is the latest and working prototype:

For rapid prototyping I wire-wrapped these boards as you can see below:

I started to design a real circuit board as you can see from the screenshots below, but unfortunately I never got around to actually building one using this board.

[gallery link=“file” columns=“2” size=“full” ids=“1069,1070”]

Glue logic

To tie up all the necessary logic, I added a small PAL (Programmable Array Logic) chip that contained some of the glue logic needed to tie it all up.

I managed to dig up some source code for this chip and I posted it as a GIST here for you to explore.

Schematics

The schematics for the setup can be found here. However, as version control was not a thing back then, I am not sure if this is the final schematics or not.

Did it work?

Yes, eventually I got it all to work and I was, for example, able to write simple applications and download them directly to the Mega Drive and run it. Eventually I got hold of enough detailed information to be able to control some sprites on the screen and control it using the joystick.

To do the actual programming on my Atari ST, I used a tool called Turbo Assembler. Turbo Assembler was a very unique assembly language IDE as it would pre-generate the binary data as you typed. The second advantage with Turbo Assembler was that it allowed me to develop my own custom drivers/targets. This allowed me to send the final assembly directly down to my hardware kit! Awesome!

Did I write any games? Unfortunately no. As I started my university studies, I didn’t have the time to pursue my game career any further. But it sure was a very fun project and I learned a lot on the way.

The final thing

So, what did the final project look like? Here are some photos:

[gallery size=“full” link=“file” ids=“1073,1074,1075,1076,1077”]

Advanced firmware

As a side project I started to write a bit more advanced firmware with some more advanced debugging features and I’ve posted a copy of the source code here for you to explore.

It included features like debugging, setting breakpoints, downloading binary data, and other handy tools. I have no idea if it works or not.

I was interviewed

As a follow-up to this blog post, I did an interview with RetroRGB that you can watch here.

TNValidate is now open source

Tore Nestenius — Tue, 01 Aug 2017 00:00:00 GMT

Our internal validation library TNValidate is now available as a project on GitHub. We released this as open source because we wanted to let others take part in our internal libraries. The library is written in C# and uses a “Fluent Interface” to define the validation rules.

By using TNValidate, we have achieved a uniform way to write our validation logic, which in turn has reduced the number of bugs and made our code more readable.

Using TNValidate is very simple:

// Instantiate validator. var Validate = new Validator(ValidationLanguageEnum.English);

// Basic validation. Validate.That(Email, "Email address").IsEmail();

// Chaining a couple of rules. Validate.That(Name, "Name").IsLongerThan(3).IsShorterThan(100);

// Supply a custom error message. Validate.That(Age, "Age").IsGreaterThanOrEqual(13, "You must be older than 13 to sign up");

// Check if validation succeeded. if (Validate.HasErrors()) { // Show errors (Validate.ValidatorResults can be data-bound). foreach (var Error in Validate.ValidatorResults) Console.WriteLine(Error.ValidationMessage); } else { // Was fine, continue... // ... }

Head over to GitHub and give it a try!

Tore Nestenius

Visualizing Claude Code MCP Requests with Coding Agent Explorer

What Is Model Context Protocol (MCP)?

HTTP vs. STDIO MCP Servers

What Is the MCP Observer?

Why HTTP Only on Port 9999?

How to Set Up the MCP Observer

Step 1: Start the Coding Agent Explorer

Step 2: Create a working directory

Step 3: Register the proxy with Claude Code

Step 4: Verify the MCP configuration

Step 5: Open the MCP Observer dashboard

Step 6: Set the destination URL

Step 7: Try your first prompt

What You Can See

Two Ways to View the Response

Pretty

Raw

Sample MCP Services to Try

Microsoft Learn

Context7

A Practical Example: Watching a tools/call in Action

MCP Requests and Hooks

Why This Matters

What’s Next

I Want Your Feedback!

Want to Learn Agentic Development?

Frequently Asked Questions

Does the MCP Observer affect Claude Code or the MCP server in any way?

Can I use the MCP Observer with any MCP server?

Can I watch multiple MCP servers at the same time?

Why does changing the destination clear the request history?

Do I need to restart Claude Code after registering the proxy?

Can I observe STDIO-based MCP servers?

Related Posts

Exploring Claude Code Hooks with the Coding Agent Explorer (.NET)

What Are Claude Code Hooks?

What can hooks be used for?

Example: Block access to secret files

How can a hook control Claude Code?

Which events can we hook into?

Why Hooks Matter for Every Project

How to Observe Claude Code Hooks in Real Time

Introducing HookAgent

FACT: stdin and exit codes

Getting Started with HookAgent

Prerequisites

Step 1: Build HookAgent

Windows:

macOS / Linux:

Step 2: Create a working directory

Step 3: Configure Claude Code hooks

Step 4: Verify the hooks are registered

Step 5: Start the Coding Agent Explorer

Step 6: Test HookAgent

Step 7: Run Claude

Seeing Claude Code Hooks and Tool Calls in Real Time

Why This Is Useful in Workshops

Claude Code Hook Events Reference

What’s Next: Inspecting Claude Code with MCP Observer

I Want Your Feedback

Want to Learn Agentic Development?

Claude Code Hooks FAQ

Does HookAgent slow down Claude Code?

Do I need to change my project or code to use hooks?

Can I use only some of the hook events?

Does this work on macOS and Linux?

Is this tool suitable for production use?

Can I block all sensitive file access using PreToolUse?

What does it take to truly secure file access?

Links to other blog posts

Introducing the Coding Agent Explorer (.NET)

Coding Agent Explorer Series

Here’s what you’ll learn:

What Is Agentic Development?

Why I Built This Tool

What Is the Coding Agent Explorer?

Three Ways to Explore With Coding Agent

The HTTP Inspector

The Conversation View