How Auth was done earlier?

• Manual Token Generation: Developers manually created JWT tokens using libraries like System.IdentityModel.Tokens.Jwt and hardcoded key management.
• No Built-in User Management: Handling user registration, login, password hashing, and role management required custom code.
• Manual Claims Management: Claims (roles, permissions) were added to JWT tokens manually, increasing the risk of errors.
• Token Validation: Developers manually validated JWT tokens in each request, including signature, expiration, and claims validation.
• No Built-in Features for Role Management: Handling user roles and claims for authorization were complex

It’s not uncommon to see code like this even today (there continue to be valid use cases, of course).

var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("YourSecretKey"));
var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

var claims = new[]
{
    new Claim(JwtRegisteredClaimNames.Sub, "username"),
    new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
};

var token = new JwtSecurityToken(
    issuer: "yourdomain.com",
    audience: "yourdomain.com",
    claims: claims,
    expires: DateTime.Now.AddMinutes(30),
    signingCredentials: creds);

// create token
var tokenString = new JwtSecurityTokenHandler().WriteToken(token);


// time passes..
//
// time now to validate in another part of the code..
// validate token

services.AddAuthentication(options =>
    {
        options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    })
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = "yourdomain.com",
            ValidAudience = "yourdomain.com",
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("YourSecretKey"))
        };
    });

Roll-in Identity

• Built-in User and Role Management
  • Identity provides a complete user management system with built-in support for user registration, login, password hashing, and role management.
  • No need to manually store user credentials or roles in the database; Identity handles it through its own entity models (e.g., IdentityUser, IdentityRole).
• Automatic Token Generation and Validation
  • Identity integrates easily with JWT authentication, automatically handling token generation, validation, and expiration management.
  • Developers no longer need to manually create or validate tokens using JwtSecurityTokenHandler.
• Claims and Role Management: Manage claims and roles through simple, high-level APIs (UserManager, RoleManager), which abstract away the complexity of managing claims in the token payload manually.
• Out-of-the-Box (“OOB”) Security
  • OOB industry-standard security practices such as password hashing (with customizable password policies) and token expiration management - reduce security risks.
  • Built-in support for multi-factor authentication (MFA), account lockout, and password recovery without custom implementations.
• Simplified Middleware Integration
  • Easily integrated into the ASP.NET middleware pipeline - no need to manually configure authentication schemes or token validation parameters.
  • Built-in Identity middleware automatically manages authentication cookies and tokens.
• Flexible Data Store: Work with multiple data stores (SQL Server, MySQL, etc.) by default
• Support for External Authentication Providers: Integrating OAuth providers like Google, Facebook, and Microsoft is simplified

Identity in Action: A Simple Demo

Create a new project..

dotnet new webapi -n dotnet-api-auth-demo

Add the below packages..

• Microsoft.EntityFrameworkCore.Sqlite
• Microsoft.EntityFrameworkCore.Design
• Microsoft.EntityFrameworkCore.Tools
• Microsoft.AspNetCore.Identity.EntityFrameworkCore

The first three are for Entity Framework Core and for using a SQLite database. The last one is for Identity.

Create the ApplicationDbContext class like as God intended. However, inherit from IdentityDbContext this time.

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
  public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : base(options)
  {
  }
}

IdentityDbContext will add magic that we are about to experience.

Add three lines of code in Program.cs.

builder.Services.AddAuthorization();
builder.Services.AddIdentityApiEndpoints<IdentityUser>().AddEntityFrameworkStores<ApplicationDbContext>();
// add the above lines before initializing `app`

var app = builder.Build();

// add the below line after `app` is initialized
app.MapIdentityApi<IdentityUser>();

• AddEntityFrameworkStores shows which database to use. In this case, we are using SQLite and using the main ApplicationDbContext itself. We could have used a different auth database as easily.
• MapIdentityApi automatically adds the necessary routes for Identity.

Since we have no other endpoints, add auth to the default weatherforecast endpoint using RequireAuthorization().

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi().RequireAuthorization();

Do a build to ensure there are no errors.

dotnet build

Migrate the database.

dotnet ef migrations add InitAuth -o Data/Migrations
dotnet ef database update

Run the application.

dotnet run

Navigate to http://localhost:5001/swagger/index.html to see the Identity endpoints.

You can test the auth endpoints using Swagger, or as I prefer - Insomnia/Postman REST clients.

First, do a GET to http://localhost:5001/weatherforecast to see a 401 Unauthorized response.

Now, call the register to create a user, and subsequently, the login endpoint to get a token.

POST http://localhost:5001/register

{
  "email": "a1@a.com",
  "password": "Pass@123"
}

POST http://localhost:5001/login

{
  "email": "a1@a.com",
  "password": "Pass@123"
}

You should get the token response.

{
  "tokenType": "Bearer",
  "accessToken": "CfDJ8AcfSlDrZbhNlphsDvuO8gDgQty5M...",
  "expiresIn": 3600,
  "refreshToken": "CfDJ8AcfSlDrZbhNlphsDvuO8gD60O..."
}

Use the access token to call the weatherforecast endpoint and see the glorious response.

We have just scratched the surface of Identity in .NET. There is a lot more to explore, including:

• Account lockout/ recovery
• Password policies
• Claims and roles management
• Customizing Identity
• Using external providers
• Role-based authorization
• Multi-factor authentication

Conclusion

Check out the full code on GitHub.

Take a straight-forward example. A new .NET Web API project would look like this -

1. A startup.cs file with generated code
2. A Program.cs file with more lines of code
3. A lot of other files

The two file dependencies induced that warm fuzzy feeling in ASP.NET developers for sometime now.

In addition, you have code that uses a wierd using syntax everywhere with brackets. Sure, it creates better compartmentalized & namespaced code, but did not help calm my nerves when I was evaluating ten different back end technologies to make a quick start (a while ago).

C# 10 and the new ASP.NET 6 will do wonders in the “make code look deceptively simple” area.

There is no startup.cs. The Program.cs file now looks cool with the new features -

• top-level statements
• global using directives
• file scope namespace declarations (bear with me here)

A minimal API structure now looks like this (Program.cs file) -

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

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

app.Run();

A full-blown MVC web API application from the new template in .NET 6 looks like this..

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

“Whoa..!” is right.

I am not proud of the fact that the additional statements & brackets were putting me off a long time. While I love C# for what it can do, I seldom choose C# for personal projects for all the silly reasons - I did not need the complexity, did not like to do lot of typing or “auto filling”, and did not have a lot of patience for code scrolling tens of pages.

NodeJS simply offered a better alternative, was way simpler to start (especially in Fastify or Express), and came at a cost that did not quite matter to me. And, I am a happy Javascript user - no one will take that away from me.

I am a fan of the new ASP.NET structure - for probably all the wrong reasons for a “real” developer. I will probably delve more into how a further “simplified” folder structure can make the ASP.NET world more exciting to work on. The “traditional” structure has been full of folders and a lot of files. See the eShopOnWeb example on Github. The minimal API structure at a glance by Martin Fowler is a good start for a new approach to build Web APIs on .NET 6, but what is even more interesting to me is the module-based architecture outlined in this post by Tim Deschryver.

WebApplication
│   appsettings.json
│   Program.cs
│   GlobalImports.cs
│   WebApplication.csproj
│
├───Modules
│   ├───Cart
│   │      CartModule.cs
│   └───Orders
│       │   OrdersModule.cs
│       ├───Endpoints
│       │       GetOrders.cs
│       │       PostOrder.cs
│       ├───Core
│       │       Order.cs
│       │───Ports
│       │       IOrdersRepository.cs
│       │       IPaymentService.cs
│       └───Adapters
│               OrdersRepository.cs
│               PaymentService.cs

Awesome time this.

So.. ASP.net?

Yes, indeed. I have had a love-hate relationship with ASP.NET through years. I am way less productive using ASP.net but cannot ignore the speed that a dotnet web server provides. Take into account the super debugging capabilities/tooling and the sizeable market that keeps providing projects on the platform, we surely have more than a winner in ASP.NET.

And oh, it immensely helps that innovations like Blazor are exciting options to make web development arguably more productive and easier.

Why yet another introduction?

There are a million other introductions to ASP.NET platform. Microsoft’s own documentation and guides are immensely helpful for beginners at all stages. But, what I love to see is a quick way to create an app (or two) and make new developers comfortable with the ecosystem. At least that’s how I learn stuff and I found some of the tutorials I glanced through to be either too detailed, or at a superficially high level.

This introduction is more for developers who use a different language for web development. It is not quite intended for absolute beginners, but anyone should be able to follow along.

Firing off with ASP.net

There are two main ways to get started on development using ASP.net platform.

1. Use Visual Studio: proven way that has been forever
2. Use Visual Studio Code or your favourite editor and dotnet core CLI

Both ways deserve all the love they can get. I prefer VSCode, but will use Visual Studio in this tutorial because - why not. Going forward I will be basing discussions primarily on Visual Studio 2019 and dotnet Core 3.1.

Installation is somewhat boring and works on expected lines.

1. Download Visual Studio from https://visualstudio.microsoft.com/
2. Click, click, click to install

Visual Studio comes with dotnet SDK, and you should be all set by now. If you decide to use VSCode, just install the dotnet SDK separately. You should then be able to use all the command line goodness on the best code editor ever(tm).

See the install docs if you are stuck. (Stuck during install, really?)

Once everything’s ready, just create a new project.

Select “ASP.NET Core Web Application”. Hit next and name your project. You will get another screen where you can select an “Web Application” template. This option will instruct Visual Studio to scaffold a few things when the project is created.

The Structure

As any modern web development stack, the files generated can be overwhelming at the beginning. We can break the structure down to basics.

A typical ASP.net project consists of one solution (which is a container for projects), and one or more projects. It will have at least one project (of course), anything else is optional and enables you to build stuff incrementally.

Beginning of everything: Startup.cs and Program.cs

These are the two files that bootstrap our app and give it ASP powers. When our app starts, the runtime calls Main method defined in Program.cs, which configures itself and starts running as an ASP app.

If you were so far wondering how our humble app came to acquire ASP powers, IHostBuilder is to blame. That interface provides our function CreateHostBuilder abilities to assume the powers of ASP.net, configure itself and start running - all in a simple one-line statement..

CreateHostBuilder(args).Build().Run();

More code in Program.cs uses C# lambdas and Dependency Injection (“DI”) to apply configuration parameters and methods defined in Startup.cs to our application.

public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });

Further, ConfigureServices in Startup.cs has a specific block that enables Razor pages in your app.

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();
}

The Configure method in Startup.cs enables a pipeline to include middleware, which in-turn enables various features for your app - all without needing you to code them in.

For e.g. -

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...
    app.UseHttpsRedirection();
    // ...
}

… tells runtime to redirect HTTP requests to HTTPS.

We will deal with lambda functions, DI etc. in more detail some other time. For now, we will move on and find out how we can quickly create our app on ASP.net.

Before we dig-in: settings and launchSettings.json

We have created a web application that runs as a command line app. The server is just serving content defined in web stuff like HTML/JS/CSS etc and in Razor pages, but does not render UI on its own.

Configuration parameters for our app is defined in launchSettings.json.

You can see the values defined in settings file in a nice user interface - right-click on the project (not the solution) in the right-hand-side bar, and select properties. Any change in one place is reflected in the other - just sayin'.

You may also notice the word “development” in the configuration file. We can provide parameters for any number of environments including development, and the start-up logic figures out the settings to apply. Further, secrets can be managed quite efficiently and made accessible to those who “need to know”. This is super helpful as you might imagine.

By default, the app uses IISExpress but there are options to use Kestrel, which is a light-weight (& a more modern) server by Microsoft. You will see these configuration options selected in the Toolbar as well. Typically, I prefer Kestrel since it is fast, and I end up hosting dotnet on Linux (where IIS is not available).

The ‘client-facing’ wwwroot

All the client-facing assets are stored in the www folder. This includes CSS, JS (custom and any libraries), static HTML, and anything else that finds its way to the browser.

Right off the bat, you see a sample CSS and JS, bootstrap and JQuery in the scaffolded files. Any and all of this can be changed or replaced. For e.g. you can replace Bootstrap with Bulma and chug along a different path.

Pages folder

Most of the action takes place here. Pages is where you place razor pages created using C#. The pages in C# get converted to something that the browser can understand by ASP.NET – we will see way more of pages in a few moments. Razor pages have the extension ‘cshtml’ files

You also see a Shared folder and a bunch of files starting with _. Shared folder is used to contain assets shared across the project, and the _ is a convention to create something called a ‘partial’. A partial is not a ‘complete’ page in itself, but comes together with other partials or pages to form complete pages.

Layout.cshtml is an example of a partial. In this file we have the header (which forms the header in the pages using this layout), a container (which will contain data), and the footer. The file also has references to script and HTML.

Of course, you can use different layouts, or decide not to use layouts at all – but building pages like this will make the entire process easy to build and to maintain.

In other notes, take a look at -

• _ViewImports.cshtml: enables tag helpers globally
• _ViewStart.cshtml: base/master page

Error, Index and Privacy pages are the actual Razor pages. You will create something on these lines to for adding more pages to your app.

Expand Index.cshtml page to find a file called Index.cshtml.cs. This file has the C# code to go along with the mark-up page. You can refer to the variables, methods, etc. from this c# page in the mark-up cshtml page. This arrangement is akin to mark-up + code arrangement in any Vue/React/Svelte application. In Blazor, you can have mark-up + code in same or different files - but that is for a different day.

This structure is different from a typical MVC model that touts a distinct controller, model and view layer. These functions are present in the Razor page app, but not fashioned in MVC style.

More about the internals and workings of an ASP.net app

We are now masters of the structure of ASP.net core razor page project, and it is time to move on and see how everything comes together.

If you’re serious about your trade, you will skip this section altogether. The terms here just help you speak the same language - you will probably figure this out by yourself while building the actual app.

Routing

The Pages folder takes care of routing in our application. The files in the folder represent the URLs served by your application.

Let’s see how..

• Privacy.cshtml is a file in the Pages folder
• baseurl.com/privacy will request the page named ‘privacy.cshtml’ in the folder. ASP.net serves the HTML generated from the razor page.
• Any sub-folder will also get included in the path. For e.g. a blog/Hello.cshtml is rendered on baseurl.com/blog/Hello
• If the requested page does not exist, a ‘page cannot be found’ error is displayed by default. You can configure the application to redirect requests to any other page (e.g. index) if the page cannot be located

You can override the default routing using the @Page tag.

@page "/privacy1"

.. will enable the link to baseurl.com/privacy1 and the previously used /privacy page disappears into oblivion.

Start Tinkering

Run your app by hitting Ctrl + F5. Visual Studio opens the browser (or allows you to configure browser) and serves the application. You can see the starter page and navigate through the links provided in the scaffolded application.

You will see that any changes will require you to build/restart app. We can avoid that by executing our app in watch mode..

cd <project-folder>
dotnet run watch