DEV Community: Julio Casal

Build a Reusable .NET Aspire API Template in Minutes

Julio Casal — Sat, 09 Aug 2025 07:00:00 +0000

A few months ago, I was trying to find a way to come up with some sort of template for future .NET API projects based on .NET Aspire.

The standard Aspire templates give you a great start, but I had already finished another Aspire application with tons of essential building blocks that I did not want to manually bring to the new project.

There had to be a better way than cloning and tweaking everything by hand.

Well, this is exactly what .NET project templates are designed for, and when taking full advantage of their features, they can really streamline the way you start new Aspire-based projects.

Today, I’ll show you how I created my new .NET Aspire API Starter template, step-by-step.

Let’s start.

The starting point

The Aspire-enabled .NET API I had just finished already had most of the things I could reuse in future projects, including:

Vertical slice architecture
Classic (and not-so-classic) CRUD endpoints
EF Core integration with PostgreSQL
Global error handling
Authorization policies
JWT authentication with support for Entra ID
Azure Storage integration
An Aspire AppHost project with:
- A complete application model
- Support for Azure services, ready to deploy
An Aspire Service Defaults project with:
- Custom health checks
- Custom health checks
An integration tests project, with several working tests
An Azure DevOps CI/CD pipeline
A lot of other reusable stuff.

At a high level, it looked like this:

To turn this into a template, I started by generalizing things a bit.

Step 1: Generalize project items

You don’t have to do this, but it didn’t feel right to have GameStore spread all over the soon-to-be template.

Plus, that term will be used as a placeholder to be replaced with the actual name given to the project by the user.

So I replaced all instances of GameStore with TemplateApp, a more generic term:

Notice this applies not only to folders and project files, but also to every namespace and class influenced by the name of the project:

Even to the CI/CD pipeline yml contents:

It’s not the most fun part of this process, but with the help of the Copilot Agent, it didn’t take long.

Next: time to add the template configuration.

Step 2: Add the template configuration

To turn the templatized application into an actual template, all you need to do is add a template.json file in a new .template.config folder at the root of the repo.

Here’s my template.json file:

Let’s go over the not-so-obvious key elements:

classifications: These will show in the Tags column when your template appears in the dotnet new list command results.
shortName: The name you will use with dotnet new to create a project using your template.
sourceName: The name to be replaced across all template dirs and files with the value specified by the user via the –name argument.
preferNameDirectory: Makes it so a directory is created for your project if –name was specified.

There are tons more things you could configure in that file, but I found these to be a great start.

Now, let’s install the template.

Step 3: Install the template

To use the template, you first have to install it. But, before doing that, make sure you delete any extra folders you don’t want to get included with it, like your bin or obj dirs.

Then, open a terminal at the root of your template, and use the dotnet new install command:

You should now be able to list your template with the familiar dotnet new list command:

Great, now let’s put it to the test.

Using the template

Let’s say I want to create a new Aspire-enabled API for my new inventory management application.

Easy to get started with the new template:

Let’s open the new project in VS Code and confirm all projects and files look good:

What about classes?

But can I build and run this? Will it work?

Yep. Let’s also open the Aspire Dashboard:

Great!

Finally, what about the integration tests?

Mission Accomplished!

Wrapping Up

.NET project templates aren’t just about saving time—they’re about building consistency across your projects.

Instead of manually recreating the same Aspire setup, authentication flows, and project structure every time, you get a battle-tested foundation that just works.

One template. Infinite projects. Zero repetitive setup.

And that’s all for today.

See you next Saturday.

P.S. If you need it, the complete .NET Aspire API Starter template is now available here.

Whenever you’re ready, there are 4 ways I can help you:

Stripe for .NET Developers (Waitlist): Add real payments to your .NET apps with Stripe—fast, secure, production-ready.
.NET Cloud Developer Bootcamp: A complete blueprint for C# developers who need to build production-ready .NET applications for the Azure cloud.
Get the full source code: Download the working project from this newsletter, grab exclusive course discounts, and join a private .NET community.
Promote your business to 25,000+ developers by sponsoring this newsletter.

Keycloak Tutorial for .NET Developers

Julio Casal — Sat, 01 Feb 2025 08:00:00 +0000

In one of my recent newsletters, I claimed OpenID Connect (OIDC) is the right way to configure authentication and authorization for your ASP.NET Core apps. No need to reinvent the wheel.

However, ASP.NET Core does not include a built-in OIDC server, so you are on your own trying to figure out what to use out of dozens of possible free, paid, local, or hosted options.

If you deploy your apps to Azure, a great option is Microsoft Entra ID, which I covered here. But, for local development, I find that to be overkill.

You should be able to run one command in your box and have everything needed to test your app with all the OIDC goodness without ever having to leave your box or pay for cloud services.

So today I’ll show you how to secure your ASP.NET Core Apps with OIDC and Keycloak, from scratch.

Let’s dive in.

What is Keycloak?

Keycloak is an open-source identity and access management (IAM) tool that helps secure applications and services.

I love to use it primarily for local development because:

It’s easy to run it locally using nothing more than Docker.
It has no cloud dependencies , making it fast and free from cloud-related costs.
It has a simple web admin UI for managing users, roles, clients, scopes, and many other things.
It is free and open-source , so you can go straight to the source if needed.
It is OpenID Connect certified , so it must support all the OIDC goodness.

Now let’s see how to configure it for local development.

Step 1: Run Keycloak via Docker

Make sure you have already installed and started Docker Desktop in your box, and then create a docker-compose.yml file somewhere in your repo with these contents:

That configures the container to run Keycloak version 26.1 , exposing its admin portal on port 8080 , using admin for user and password, and with a volume to not lose our settings when stopping the container.

We also configure it to run in dev mode (start-dev), which avoids a few restrictions that should be enforced in Production only.

Open a terminal wherever you saved this file and run this:

Now open your browser and navigate to this page:

http://localhost:8080

Now let’s configure the realm.

Step 2: Create the realm

A Keycloak Realm is a logical space for managing users, roles, groups, and authentication configurations within a Keycloak instance.

You can create one by clicking on Create realm in the realm drop-down:

In the next screen enter a realm name that matches what your app is about and hit Create:

The realm for our Game Store app is ready. Next, let’s add a user.

Step 3: Add a user

User management is very straightforward in Keycloak. Just head to the Users section and click Create new user :

In the next screen, enter your user details, turn on Emal verified (to keep things simple), and hit Create :

Here you also want to set a password for your user, so next click on the Credentials tab and click on Set password :

Any password will do, since this is for local dev. Also, no need to make it temporary.

Next, let’s register our first client.

Step 4: Register the back-end

The access tokens generated by Keycloak to authorize requests to our back-end API must include the correct audience. That’s how our back-end can confirm the token is intended for it.

And, for that, we’ll need to register our back-end as a client in Keycloak, which you can do by going to the Client tab and then clicking on Create client :

On the General settings wizard step, enter a meaningful ID for this client. I’ll use gamestore-api:

Step 2 of the wizard is meant for clients that start an OIDC authorization flow, like our front-end, but it does nothing for our backend, so you can keep everything OFF:

There’s nothing to enter in the last wizard step, so just hit Save and your client is created.

Step 5: Configure the audience

We need to create the client scope that, if granted, will attach the correct audience to the access tokens.

So, go to Client scopes and then click on Create client scope :

For the client scope name you should enter a value that reflects the kind of permissions that clients will be granted if they are allowed to request that scope.

I used gamestore_api.all since this scope grants access to the entire back-end API. This can be further enforced in your back-end authorization policies.

Turn on Include in token scope so that the scope is included in the generated access token (if you need it) and hit Save.

Now, we have to configure this scope so that it will produce the right audience in the token when requested. For that, while in this same client scope details screen, click on Mappers and Configure a new mapper :

From the list select Audience :

You can enter any name for this audience, it’s not very relevant, but the key detail is to ensure you select your API client for Included Client Audience:

That will ensure any time the gamestore_api.all scope is requested and granted, the gamestore-api audience will be added to the access token.

There’s nothing else to do on this screen, so just hit Save.

Now let’s register our second client.

Step 6: Register the front-end

Since we’ll be using the OIDC authorization code flow, which starts from the front-end, we need to register our front-end as a client in Keycloak.

For this, go back to the Clients section and click on Create client :

In the General settings screen use a meaningful ID for your front-end, which you’ll use later in your app code:

In the Capability config step, the Client authentication check goes On or Off depending on your type of client:

Public client -> On: This is for SPA-style clients like React, Angular, Blazor WASM, or for mobile apps, since they can’t safely store secrets (anything that runs in the user’s device can be hacked).
Private client -> Off: This is for server-side apps, like Blazor server or old-style ASP.NET MVC or Razor apps. Those can safely store secrets on the server.

In my case, my front-end is a Blazor app with Static Server Side Rendering, no client interactivity, so I’ll turn Client authentication On.

For Authentication flow, the Standard flow is all you need.

Moving on to the Login settings , you want to enter both the Valid redirect URIs and Valid post logout redirect URIs :

The host:port to use there depends on the host and port where you run your front-end locally, http://localhost:5002 in my case.

Then, to keep it simple, I used the default paths used by ASP.NET Core’s OIDC middleware (signin-oidc, signout-callback-oidc).

You can use any other paths there, but you have to make sure they exist in your front-end and that the OIDC middleware is aware of them.

Hit Save and your front-end is mostly good to go.

The missing piece is allowing our front-end to request the client scope we created earlier. That’s how it can get access tokens with the correct audience.

So from your front-end screen go to Client scopes and click on Add client scope :

Select the scope you had created (gamestore_api.all in my case), click Add, and choose Default or Optional.

Optional means the client must request the scope, while Default means the scope is always requested for this client, even if it doesn’t ask for it.

I like to pick Optional here to let the client be very explicit on what it requests.

That’s all the required Keycloak configuration. Now let’s see what to do to wire things up on the code side.

Step 7: ASP.NET Core back-end configuration

We need to tell our back-end 2 key things:

Who will be issuing the access tokens (Authority)
Who are those tokens meant for (Audience)

We can achieve those by first installing the Microsoft.AspNetCore.Authentication.JwtBearer NuGet package and then registering a JWT Bearer scheme with the right values on our application startup code:

Notice that Authority is the host:port where Keycloak is running plus /realms/your-realm-name, and Audience must match exactly the audience we configured earlier on Keycloak.

RequireHttpsMetadata needs to be false so that the middleware can talk to our Keycloak server locally, which is not using HTTPS.

Also, add this line to turn on the Authorization middleware:

And then update your endpoints to require authorization:

The back-end should be ready. Now, let’s see what to do on the front-end.

Step 8: Front-end configuration

How you configure the front-end for OIDC will vary wildly depending on your tech stack, but here’s what you can do for a Blazor Static SSR app.

First install the Microsoft.AspNetCore.Authentication.OpenIdConnect NuGet package, which gives you access to the OIDC middleware.

Then, configure your Keycloak scheme during your application startup:

You can get your ClientId and ClientSecret from your front-end client configuration on Keycloak:

Just don’t hard code the secret there, and instead load it from .NET’s Secret Manager. Also, keep in mind that a client secret is not required for public clients since they can’t hold secrets.

Regarding the other values:

Authority: The path to your realm in your Keycloak server.
Scope: The exact scope we defined earlier and that grants the correct audience.
ResponseType: The flow to use to authenticate the user. Code corresponds to the Authorization Code Flow.
SaveTokens: True so that received tokens can be saved in the authentication cookie to be used later when we send requests to the backend.
SignInScheme: The scheme used to sign in the user. We use cookies here so the user can remain authenticated between requests.
SignOutScheme: The scheme used to sign out the user. We use Keycloak here so that the user is signed out of both Keycloak and the front-end.
RequireHttpsMetadata: Needs to be false, same reason as the back-end.
TokenValidationParameters.NameClaimType: Setting this to JwtRegisteredClaimNames.Name will make sure the user’s name is populated in the claims principal after the user authenticates.
MapInboundClaims: Prevents ASP.NET Core from changing the name of a few key claims. We want the exact claims coming from Keycloak.

You will also need to add the Cookies auth scheme, so that it can be used alongside the OIDC middleware:

How will Blazor components know if the user is authenticated or not?

By using the authorization middleware, an authentication state provider, and the cascading authentication state, which you can register like this:

That’s how we can do stuff like this elsewhere:

We should also add an endpoint in the front-end to kick off the OIDC sign-in flow:

That endpoint will be invoked by your Login button or link. Something like this:

This should be enough for your front-end to authenticate users via Keycloak.

But, there’s one more thing needed to let the front-end make authenticated requests to the backend.

Step 9: Add an authorization handler

Just because the user is authenticated in the front-end doesn’t mean the back-end will automatically trust the front-end to make requests on behalf of the user.

We need to make sure we attach the access token as a header on every request we make to the back-end API endpoints that require authorization.

We could do this manually in every request, but it’s easier via a delegating handler like this:

As you can see, all we do there is get the access token from the current HTTP context and attach it as a Bearer token in the Authorization header of the request.

Finally, to enable our authorization hander, we need to register it and add it to our typed HTTP client in the front-end:

Step 10: ASP.NET Core + Keycloak in action

Now run your backend and frontend applications and navigate to the frontend in your browser:

Now click on the Login button and you’ll land on Keycloak’s login page:

And, after login, you’ll get redirected to the home page, but with a few differences:

You can now see UI elements only meant for authorized users, like the Catalog link there, plus you can see details about the authenticated user, like the name and a small gravatar generated out of the user email.

You can also have the front-end make use of protected back-end APIs that require the presence of an access token.

For instance, here’s the shopping cart page, where the back-end must know who the current user is and what kind of access has been granted to return the correct cart:

So there you go, ASP.NET Core + Keycloak working end to end, all secured with the industry standard OIDC protocol.

Mission accomplished!

Wrapping up

You now have a complete ASP.NET Core application secured with industry-standard OIDC authentication, all running locally without any cloud dependencies.

Your backend API validates JWT tokens properly. Your frontend handles the authorization code flow seamlessly. And Keycloak provides enterprise-grade identity management that just works.

This setup gives you everything you need for local development: a real identity provider, proper token validation, and the confidence that your authentication flow will work the same way in production.

Want to take this even further?

In Part 2 of this series, I’ll show you how to make this entire setup even more developer-friendly using .NET Aspire. We’ll eliminate the manual Keycloak configuration and make everything start automatically when you hit F5.

Just clone, run, and authenticate. Every single time.

Until next time!

P.S. For a step-by-step video guide to everything I showed you above plus advanced topics like role, claims and resource based authorization, and complete frontend integration with both Blazor and React applications, check out my ASP.NET Core Security Course.

Whenever you’re ready, there are 4 ways I can help you:

Stripe for .NET Developers (Waitlist): Add real payments to your .NET apps with Stripe—fast, secure, production-ready.
Containers & .NET Aspire: Build production-ready apps from day 1 and leave ‘but it works on my machine’ behind.
Get the full source code: Download the working project from this newsletter, grab exclusive course discounts, and join a private .NET community.
Promote your business to 25,000+ developers by sponsoring this newsletter.

Understanding JSON Web Tokens

Julio Casal — Sat, 04 Jan 2025 08:00:00 +0000

Well, 2024 is gone, and wow it was such an amazing year in many aspects, but especially for software developers and AI enthusiasts.

As I look back, here are a few 2024 breakthroughs that I think set the stage for how we will be doing things moving forward:

GPT-4o and Claude 3.5 Sonnet enabled more natural and versatile human-AI interactions, significantly changing the way we solve our everyday human problems.
AI coding assistants like GitHub Copilot and Cursor are now integrated deeply into our developer workflows, reducing mundane tasks and allowing more focus on creative problem-solving.
NVIDIA’s market value went beyond $3 trillion, reflecting how tech giants like Microsoft, Google, and Amazon can no longer live without their powerful AI chips.
Microsoft’s 365 Copilot, their Azure cloud, and all their developer tools are now heavily powered by a myriad of OpenAI services, reshaping human productivity and innovation at all levels.
.NET Aspire achieved not 1 but 2 major releases, reflecting the increasing demand for better tooling for cloud-native development with a strong focus on Azure.

2025 is only going to get better, but boy, things are moving so fast!

Today I want to dive into JWTs (JSON Web Tokens), and the key role they play in today’s web app security infrastructure.

Let’s dive in.

What is a JSON Web Token (JWT)?

Think of a JWT (pronounced “jot”) like a digital VIP pass at a concert. Just as a VIP pass contains information about who you are and what areas you can access, a JWT contains claims about a user and their permissions.

The key difference is that a JWT is cryptographically signed, making it tamper-proof.

To be more specific:

JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties.

Now, before looking at real JWTs, I think it’s good to understand the concept of a claim.

What is a claim?

In our VIP pass, we have several pieces of information about the pass holder:

Each of these pieces of information is like a “claim” in JWT terms.

A claim is a statement about an entity (typically, the user) and additional data.

Think about it this way: When Thomas shows his VIP pass to a security guard, that pass is making several claims on his behalf:

The name claim : “I am Thomas A. Anderson”
The access level claims : “I have permission to enter the backstage area,” “I can enter the green room,” “I can attend the soundcheck”
The time validity claim : “My privileges are valid until December 31, 2025”

In a JWT, claims work the same way. When your application presents a JWT to a server, it’s like Thomas showing his VIP pass, which makes specific claims about Thomas and his granted access.

But what do these JWTs look like?

What’s in a JWT?

JWTs follow a 3 part structure:

So there we got:

The Header , which contains information about the type of token and how it was signed
The Payload , which contains all the transmitted claims
The Signature , _**_which is calculated from the encoded header and payload, an added secret, and the hashing algorithm specified in the header.

Now if you decode the payload of a JWT, as your Web app will do, you will get something like this:

So it’s just a list of claims related to Mr. Anderson and the access given to him in the system.

To explain a few important ones:

sub: The unique ID of Thomas in the system
iss: The URL of the authorization server that issued the token
scope: The type of access granted to the app, on behalf of Thomas, to use our backend API
role: The business role assigned to Thomas
email: Thomas’s registered email

But how are these JWTs used in real life and who creates them?

Token-based Authentication

Let’s say you have a backend API that gates access to everything related to the concert venues and that Thomas wants to securely check all that info from his phone.

Here is where we would use what is known as token-based authentication:

Token-based authentication is a security mechanism in which a client authenticates itself to a server by presenting a unique token, which serves as a temporary credential to access protected resources.

It works like this:

Thomas Requests Authorization: Thomas logs in through the mobile app to request access to concert details.
Authorization: The authorization server checks Thomas’s credentials and approves his login.
JWT Issued: The authorization server issues a JWT with all the claims that confirm the kind of access Thomas has been granted.
API Request: The mobile app sends a request to the Concert Gate API attaching the issued JWT as a header.
API Validates JWT: The API verifies the JWT for validity, expiration, and permissions.
API Responds: The API returns the requested concert details to the mobile app.

Now, how do you deal with these JWTs in your ASP.NET Core APIs? Let’s tackle that in next week’s newsletter.

And, if you need to learn how to configure Keycloak, a popular open-source authorization server, to authenticate your users and generate JWTs, I go over all those details (and lots more) in the bootcamp.

New ASP.NET Core Security course: recording complete!

Earlier this week I finished recording course 3 of the bootcamp: ASP.NET Core Security and, as expected, it ended up being the largest course in the bootcamp yet.

This course is a bit longer to make sure you are ready to answer questions like:

How does ASP.NET Core validate and extract info from the JWTs attached to your requests?
How do OAuth 2.0 and OpenID Connect (OIDC) work?
How to read and transform claims?
What are and how to use different authentication schemes?
How to implement different types of authorization policies based on JWT claims?
How can a full-stack application integrate with Keycloak to offload user login and registration and enable OIDC?

And tons of other stuff, including a mini-course on Docker for students new to that popular tech.

I’m now going through all the post-production work, which ended up being a bit more than anticipated, but if all goes well this course should be ready for all bootcamp students by January 14.

Now, back to work.

Until next time!

Julio

Whenever you’re ready, there are 4 ways I can help you:

Stripe for .NET Developers (Waitlist): Add real payments to your .NET apps with Stripe—fast, secure, production-ready.
Containers & .NET Aspire: Build production-ready apps from day 1 and leave ‘but it works on my machine’ behind.
Get the full source code: Download the working project from this newsletter, grab exclusive course discounts, and join a private .NET community.
Promote your business to 25,000+ developers by sponsoring this newsletter.

Securing ASP.NET Core Apps With OIDC and Microsoft Entra ID

Julio Casal — Sat, 25 May 2024 07:00:00 +0000

Today I’ll show you how to secure your ASP.NET Core applications using OpenID Connect (OIDC) and Microsoft Entra ID.

OIDC is the industry-standard protocol for authentication and is pretty much the go-to choice for securing full-stack applications these days.

But the sad thing is that there are few things more frustrating than trying to understand and implement OIDC for the first time.

However, it’s not rocket science and once you get the hang of it, you’ll be able to secure your applications with confidence.

Let’s dive in.

What is OpenID Connect?

Any OpenID Connect (OIDC) definition involves OAuth 2.0, so you should first know that OAuth 2.0 is the industry-standard protocol for authorization, allowing a website or application to access resources hosted by other web apps on behalf of a user.

OIDC is nothing more than an authentication protocol built on top of OAuth 2.0 that allows clients to verify the identity of the end-user based on the authentication performed by an authorization server.

OIDC supports several flows to authenticate users depending on your scenario, but one of the most modern and secure flows you can use is the Authorization Code Flow with PKCE.

Here’s how the OIDC Authorization Code Flow with PKCE works:

The end-user initiates an authorization request to perform some action in the resource server (say, query resources from an ASP.NET Core API) via a client, also known as the relying party.
The client generates a code verifier , which is a hard-to-guess value that will be used later in the flow.
The client then generates a code challenge , which is an encoded hash value derived from the code verifier.
The client sends the code challenge, along with the openid scope, to the authorization server , also known as the OpenID provider. The openid scope indicates that the client wants to authenticate the user.
The OpenID provider presents the sign-in page where the end-user can authenticate.
After authentication, the OpenID provider might optionally also present an additional page where the end-user can provide explicit consent to which actions can be performed on the resources he owns.
After this, the OpenID provider generates an authorization code which it sends back to the client. It also stores the code challenge for future verification
Now, the client can request an authorization token by using the received authorization code plus the code verifier it had created at the start of the flow.
The OpenID provider verifies the authorization token request by generating the code challenge itself out of the received code verifier and comparing it with the code challenge it had already stored.
If all looks good, the OpenID provider generates two tokens: an access token and an ID token.
The client can verify the identity of the end-user via the ID token.
The client can send requests to the resource server to query for the resources it needs using the access token.
The resource server validates the received access token and if all looks good it executes the requested action and returns the corresponding response.

I love this flow because of 3 key reasons:

Enhanced Security: Prevents authorization code interception attacks by binding the authorization code to a code verifier.
Defense in Depth: Adds an additional layer of security beyond the client secret, making the overall authentication process more robust.
Compliance with Best Practices: Aligns with modern security standards and recommendations for OAuth 2.0 and OpenID Connect, ensuring a more secure implementation.

Choosing an OpenID Provider

There are several OpenID providers you can use to enable OIDC in your ASP.NET Core applications.

A few of the popular ones I have used in the past are:

There are many others, but the key thing is that they all implement OIDC, which means that they can all enable the OIDC flow I described above.

Plus, once you understand OIDC via one of them, you can easily switch between providers if needed.

The choice of provider will depend on your specific requirements and constraints, like:

How much you are willing to pay
How much control you want over the authentication process
How much you want to rely on third-party services.

For this post, I’ll focus on Microsoft Entra ID because it’s part of the Microsoft ecosystem, and it’s a great starting point to understand how OIDC works.

Prefer to watch instead? Here’s a full walkthrough:

Let’s see how to secure an ASP.NET Core full-stack application via Microsoft Entra ID in a few simple steps.

Step 1: Register your application in Microsoft Entra ID

Our full-stack application is made of an ASP.NET Core API backend and a Blazor frontend.

In this step we need to register the Blazor frontend in Microsoft Entra ID, which you can do by going to the App registrations section of Microsoft Entra ID on your Azure Portal.

Here I’ll go for a single-tenant application to keep things simple, will select Web as the platform (since it’s a server-side web application) and add the redirect URI for my Blazor frontend.

The platform you choose determines what kind of information Entra ID will demand from your app when configuring it for OIDC. For instance, it will not require a client secret for an SPA, but it is required for a Web app.

The redirect URI is the location where Entra ID will send the authorization code after the user authenticates. In this case, it’s just the local URL of my Blazor frontend plus /signin-oidc , the default path where the ASP.NET Core OIDC middleware will listen for the authorization code.

After registering the app, you should go to Expose an API and add the scope(s) that your API backend supports (if any).

Scopes are a way to define what actions the client can perform on the resources it requests. In this case, the scope api://8814267c-25fc-459e-b0a6-f6d7ed056f12/games:all allows the client to perform any operation on the games managed by the API backend.

The actual scope is games:all , but Entra ID will automatically prepend it with the Client ID assigned to your application.

Lastly, you’ll need to head to Certificates & secrets and create a new client secret that you’ll use in your Blazor frontend as part of the OIDC flow.

You’ll need more configuration there if you need to do things like support application roles, but this is good to get started.

Step 2: (Optional) Understand your access tokens

You don’t have to do this, but I find it helpful to understand the access tokens that Entra ID will generate, so I can tell which claims to expect to find in them.

To manually get an access token, you will first need to know your Authorization Endpoint and your Token Endpoint. Get those from the Overview blade of your Entra ID app registration in the Portal:

Then open up Postman, create a new request, and head to the Authorization tab:

On the right side, under Configure New Token , select Authorization Code (With PKCE) as the grant type, and fill in the boxes I highlighted below with your Redirect URI , Authorization Endpoint , Token Endpoint , Client ID , Client Secret , and Scope (all from your Entra ID app registration in the Portal):

Notice that for Scope I also added openid and profile , so that I can get not just the access token , but also the ID token with some interesting user info on it.

And, make sure you select Send client credentials in body for the Client Authentication setting, or it won’t work.

Click Get New Access Token , which should take you to the Entra ID sign-in page. After signing in, you’ll be back in Postman with your new tokens:

Now, grab your Access Token from Postman and decode it in a page like jwt.ms. Here’s my token decoded:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "L1KfKFI_jnXbwWc22xZxw1sUHH0",
  "kid": "L1KfKFI_jnXbwWc22xZxw1sUHH0"
}.{
  "aud": "api://8814267c-25fc-459e-b0a6-f6d7ed056f12",
  "iss": "https://sts.windows.net/e6244037-0452-4a93-bcb4-864751f62fcf/",
  "iat": 1716569236,
  "nbf": 1716569236,
  "exp": 1716574166,
  "acr": "1",
  "aio": "AVQAq/8WAAAAk9VaoKrqC7/gpqMXx9XMbpIhpZ9oVzSheQZQr1jCbfJiSkkYd9JgF8ziMf+rrxjonWeQPIAzTpqPtw6DLqjMTIDVsxbtfos6J6ksaoO3BfA=",
  "amr": [
    "pwd",
    "mfa"
  ],
  "appid": "8814267c-25fc-459e-b0a6-f6d7ed056f12",
  "appidacr": "1",
  "family_name": "Casal",
  "given_name": "Julio",
  "ipaddr": "50.35.76.187",
  "name": "Julio Casal",
  "oid": "3f7e659c-1aaf-43ec-8ffd-fb6dc91d1045",
  "rh": "0.AXYAN0Ak5lIEk0q8tIZHUfYvz3wmFIj8JZ5FsKb21-0FbxJ2AO4.",
  "scp": "games:all",
  "sub": "ofM-v1Euz4cuFXSEzmQ1DVtz5W5V27vVR4E5iVHgvFk",
  "tid": "e6244037-0452-4a93-bcb4-864751f62fcf",
  "unique_name": "julioc@dotnetacademy.io",
  "upn": "julioc@dotnetacademy.io",
  "uti": "l6MNUJEh9UmpJOCnIG-nAA",
  "ver": "1.0"
}.[Signature]

Now you can tell exactly which Audience (aud), Authority (iss), and Scopes (scp) your backend API will receive in the access tokens, besides a bunch of other interesting claims.

From that same Postman dialog, scroll down a bit, grab your id_token and decode it. Should be something like this:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "L1KfKFI_jnXbwWc22xZxw1sUHH0"
}.{
  "aud": "8814267c-25fc-459e-b0a6-f6d7ed056f12",
  "iss": "https://login.microsoftonline.com/e6244037-0452-4a93-bcb4-864751f62fcf/v2.0",
  "iat": 1716570599,
  "nbf": 1716570599,
  "exp": 1716574499,
  "name": "Julio Casal",
  "oid": "3f7e659c-1aaf-43ec-8ffd-fb6dc91d1045",
  "preferred_username": "julioc@dotnetacademy.io",
  "rh": "0.AXYAN0Ak5lIEk0q8tIZHUfYvz3wmFIj8JZ5FsKb21-0FbxJ2AO4.",
  "sub": "ofM-v1Euz4cuFXSEzmQ1DVtz5W5V27vVR4E5iVHgvFk",
  "tid": "e6244037-0452-4a93-bcb4-864751f62fcf",
  "uti": "5vHcMCJMnkG87UQUAZAbAA",
  "ver": "2.0"
}.[Signature]

The ID Token is the one that your Blazor frontend can use to identify the user via interesting claims like name , preferred_username , and sub.

Knowing about all these claims will save you a lot of trouble down the road, trust me.

Let’s now start writing some code.

Step 3: Secure the backend API endpoints

First things first. We have to make sure our endpoints are protected and only accessible to authorized users.

For this, I first defined a couple of authorization policies in the API backend:

builder.Services
       .AddAuthorizationBuilder()
       .AddPolicy("read_access", builder =>
       {
           builder.RequireClaim("scp", "games:read", "games:all");
       })
       .AddPolicy("write_access", builder =>
       {
           builder.RequireClaim("scp", "games:write", "games:all");
       });

The read_access policy is meant for my GET endpoints, while the write_access policy is meant for all endpoints that can modify my games in any way.

In each policy, we require the scp claim to be present in the user’s token. From the access token we inspected earlier, we know that is the claim where Entra ID will place the scope(s) the client was granted.

So, GET endpoints will require either the games:read or games:all scope, while all other endpoints will require either the games:write or games:all scope.

Here’s one of my GET endpoints, which uses the read_access policy:

group.MapGet("/{id}", async (int id, GameStoreContext dbContext) =>
{
    Game? game = await dbContext.Games.FindAsync(id);

    return game is null ? Results.NotFound() : Results.Ok(game.ToGameDetailsDto());
})
.RequireAuthorization("read_access");

You can use the RequireAuthorization method to set the policy for each of your endpoints similarly.

Step 4: Configure the backend API for Entra ID

First, we’ll need one NuGet package to be able to use JWT-bearer authentication:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Then, we’ll need to configure our Entra ID details like this:

builder.Services
       .AddAuthentication()
       .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
       {
           options.Authority = "https://sts.windows.net/e6244037-0452-4a93-bcb4-864751f62fcf/";
           options.Audience = "api://8814267c-25fc-459e-b0a6-f6d7ed056f12";
           options.MapInboundClaims = false;
       });

There we are configuring JWT-bearer authentication with the following details:

Authority: The Entra ID authorization server, which is the one that will verify any tokens received by the API. Just replace the GUID there with the Directory (tenant) ID you’ll find in the overview blade of your Entra ID app registration in the Portal.
Audience: The Client ID of the Entra ID application for whom the token was issued. With this, the API backend can verify that the token was indeed issued for it. Also found in the overview blade of your Entra ID app registration in the Portal.
MapInboundClaims: Setting this one to false is important because it will prevent ASP.NET Core from mapping the claims in the token to claim types that we are not interested in. We want to access the scopes directly from the scp claim, and this will allow us to do so.

There’s a lot more you may want to configure there depending on your scenario, but this will do for now.

Step 5: Configure the Blazor frontend for Entra ID

For this, we’ll need to add one new NuGet package to the Blazor frontend project:

dotnet add package Microsoft.AspNetCore.Authentication.OpenIdConnect

Then, here’s how you can configure the OIDC flow in the frontend:

var authority = "https://login.microsoftonline.com/e6244037-0452-4a93-bcb4-864751f62fcf/v2.0/";

builder.Services
        .AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)        
        .AddOpenIdConnect(options =>
        {
            options.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
            options.SignOutScheme = OpenIdConnectDefaults.AuthenticationScheme;
            options.Authority = authority;
            options.ClientId = "8814267c-25fc-459e-b0a6-f6d7ed056f12";
            options.ClientSecret = "[Read from a configuration source]";
            options.ResponseType = OpenIdConnectResponseType.Code;
            options.SaveTokens = true;
            options.MapInboundClaims = false;
            options.Scope.Add("api://8814267c-25fc-459e-b0a6-f6d7ed056f12/games:all");
            options.TokenValidationParameters.NameClaimType = JwtRegisteredClaimNames.Name;
            options.TokenValidationParameters.RoleClaimType = "roles";
        })
        .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme);

Let’s break down that:

SignInScheme: The scheme used to sign in the user. We use cookies here so the user can remain authenticated between requests.
SignOutScheme: The scheme used to sign out the user. We use the OIDC scheme so that the user is signed out of both the OIDC provider and the frontend.
Authority: The Entra ID authorization server, which is the one that will authenticate the user. Use the same GUID you used for Authority in the backend. It’s just that the format of the URL is different.
ClientId: The Client ID of the Entra ID application for whom the token will be issued. It’s the same GUID you used for Audience in the backend configuration.
ClientSecret: The client secret you created in the Entra ID app registration. Make sure you read this from some configuration source, not hardcode it in the code.
ResponseType: The flow to use to authenticate the user. OpenIdConnectResponseType.Code corresponds to the Authorization Code Flow , which will also use PKCE by default.
SaveTokens: Whether to save the tokens received from the authorization server. We need to save them so we can use them when we send requests to the backend.
MapInboundClaims: Same idea as what we did in the backend.
Scope: The scope(s) the client wants to request from the authorization server. This is the exact scope we defined when registering the app in the Entra ID portal.
TokenValidationParameters.NameClaimType: Setting this to JwtRegisteredClaimNames.Name will make sure the user’s name is populated in the claims principal after the user authenticates, so we can easily display it in the frontend.

You also need to add these other two lines to your Program.cs in the frontend:

builder.Services.AddAuthorizationBuilder();
builder.Services.AddCascadingAuthenticationState();

The first line adds the authorization services to the frontend, while the second one adds the services needed to propagate the authentication state to all components in the Blazor app.

We should also add an endpoint in the frontend to kick off the OIDC sign-in flow:

app.MapGet("/authentication/login", () 
    => TypedResults.Challenge(
        new AuthenticationProperties { RedirectUri = "/" }))
    .AllowAnonymous();

That endpoint will be invoked by an anchor tag in the Blazor Login component. Something like this:

<a href="authentication/login" class="btn btn-warning">Login</a>

Now, that configuration should be enough for your frontend to authenticate users via Entra ID.

But, there’s one more thing needed to let the frontend make authenticated requests to the backend.

Step 6: Add an authorization handler

Just because the user is authenticated in the frontend doesn’t mean the backend will automatically trust the frontend to make requests on behalf of the user.

We need to make sure we attach the access token as a header on every request we make to the backend API endpoints that require authorization.

We could do this manually in every request, but it’s easier via a delegating handler like this:

public class AuthorizationHandler(IHttpContextAccessor httpContextAccessor) : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, 
        CancellationToken cancellationToken)
    {
        var httpContext = httpContextAccessor.HttpContext ??
            throw new InvalidOperationException(
                "No HttpContext available from the IHttpContextAccessor!");

        var accessToken = await httpContext.GetTokenAsync("access_token");

        if (!string.IsNullOrEmpty(accessToken))
        {
            request.Headers.Authorization = new AuthenticationHeaderValue(
                "Bearer", 
                accessToken);
        }            

        return await base.SendAsync(request, cancellationToken);
    }
}

As you can see, all we do there is get the access token from the current HTTP context and attach it as a Bearer token in the Authorization header of the request.

Finally, to enable our authorization hander, we need to register it and add it to the HTTP client in the frontend:

builder.Services.AddHttpContextAccessor();
builder.Services.AddTransient<AuthorizationHandler>();     

builder.Services.AddHttpClient<GamesClient>(
    client => client.BaseAddress = new Uri("http://localhost:5274"))
    .AddHttpMessageHandler<AuthorizationHandler>();

Step 7: ASP.NET Core + Entra ID in action

Now run your backend and frontend applications and navigate to the frontend in your browser:

How is the home page able to query games without signing in? That’s because I didn’t want users to have to sign in just to be able to list the games, so I didn’t add any authorization policy to the GET endpoint that retrieves all games from the backend.

Clicking the Login button should take you to a sign-in page like this:

And, after authenticating, you should be redirected back to the frontend:

Thanks to the claims available in the ID token provided by Entra ID, I was able to display the user’s name and generate a Gravatar image where the login button was before.

I was also able to show New Game , Edit and Delete buttons for each game, which are only visible if the user is authenticated.

And if I click on the Edit button, I can see the game details and update them:

Both the GET and PUT backend endpoints used by this page require authorization, so if you can load the page and save the updates, the access token was correctly attached to the requests by the authorization handler.

Mission accomplished!

Whenever you’re ready, there are 4 ways I can help you:

Stripe for .NET Developers (Waitlist): Add real payments to your .NET apps with Stripe—fast, secure, production-ready.
Containers & .NET Aspire: Build production-ready apps from day 1 and leave ‘but it works on my machine’ behind.
Get the full source code: Download the working project from this newsletter, grab exclusive course discounts, and join a private .NET community.
Promote your business to 25,000+ developers by sponsoring this newsletter.

How To Monitor Your ASP.NET Core Application In Azure

Julio Casal — Sat, 01 Jul 2023 07:00:00 +0000

Today I’m going to show you how to quickly start monitoring your ASP.NET Core application in Azure.

Having good monitoring in place is a huge life saver since it can quickly give you a good insight into the health of your application and works as the pillar upon which you can later setup alerts to make sure you know about application problems before your customers ever notice.

Many folks leave monitoring for the very end, which is not surprising since it’s not critical to get the app up and running and the traditional series of concepts to learn, libraries to install and services to configure, can be overwhelming.

You need to start monitoring to your .NET application today.

I’ll show you how to start collecting metrics using OpenTelemetry, a super popular observability framework to collect, process and export telemetry data and the Azure Monitor OpenTelemetry Distro, a new library to make it really easy to publish collected metrics to Azure Monitor Application Insights.

With these two sets of frameworks in place you’ll be able to:

Add basic monitoring to your ASP.NET Core app in no time
Quickly see your app’s basic health indicators in your Azure Portal
Start tracking your custom metrics with a few lines of code

Here’s how to get started, step by step:

Prerequisites

An Azure subscription. You can sign up for a free trial here.
Your existing ASP.NET Core application. I’m not sure how much you’ll be able to do with other types of .NET apps.

1. Create an Application Insights resource

In your Azure Portal, look for the Application Insights service and create a new one:

Once creation is completed (20-30 seconds in my case), go to your new App Insights resource and copy the connection string that you’ll find in the Overview blade. You’ll need that later.

2. Install the client library

Open a Terminal, switch to your ASP.NET Core app dir and install the Azure Monitor OpenTelemetry Distro client library:

dotnet add package --prerelease Azure.Monitor.OpenTelemetry.AspNetCore

3. Register the Azure Monitor OpenTelemetry services

Add the following line to your Program.cs file:

builder.Services.AddOpenTelemetry().UseAzureMonitor();

That will both register the OpenTelemetry services and configure Azure Monitor exporters for logging, distributed tracing and metrics. The simplest Program.cs file would look like this now:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

4. Provide the App Insights connection string to your app

For your app to start talking to Azure App Insights, it needs the connection string you copied earlier. There are a few ways to configure the connection string in your app, but for local development purposes my preferred approach is to use the .NET Secret Manager.

To do that, first go back to your Terminal and initialize user secrets for your app:

dotnet user-secrets init

Then, set your secret, where the key must be AzureMonitor:ConnectionString and the value the actual connection string:

dotnet user-secrets set "AzureMonitor:ConnectionString" "YOUR CONN STRING HERE"

5. Confirm your app is sending data to Azure App Insights

Surprisingly, there’s nothing else to do to start getting data in App Insights. So, start your app and start hitting a few of your endpoints to start collecting monitoring data.

Give it a few minutes (data will not show up in real time in Azure) and eventually you should see a few essential metrics popping up in your App Insights Overview blade:

I even tried out a few requests that resulted in a 404 to confirm they would show up as failed requests in the first chart.

6. Track custom metrics

Let’s say that now you want to start tracking your own metrics. For instance, in my little Match Making app I’d like to start counting each time a new match is created and report that as a new metric.

That’s actually quite easy with the built in APIs provided in .NET. So here’s what you do:

Define a counter:
Create an instance of the meter for your API and use it to create your counter:
Count! For instance, here’s where my app creates a new match, so just after the match is created in my repository, I use the counter to count one more match created:
Define your new meter in your Program.cs via the ConfigureOpenTelemetryMeterProvider method:
Run your app and execute the endpoint(s) that use the above logic. Then go to your Metrics blade in the Azure portal and add your new metric. In my case, the created matches look like this:

Done!

Well, that’s it for today.

I hope you enjoyed it.

Whenever you’re ready, there are 4 ways I can help you:

Stripe for .NET Developers (Waitlist): Add real payments to your .NET apps with Stripe—fast, secure, production-ready.
Containers & .NET Aspire: Build production-ready apps from day 1 and leave ‘but it works on my machine’ behind.
Get the full source code: Download the working project from this newsletter, grab exclusive course discounts, and join a private .NET community.
Promote your business to 25,000+ developers by sponsoring this newsletter.