DEV Community: Tran Manh Hung

Wolverine + Marten: My story and subjective take

Tran Manh Hung — Wed, 17 Sep 2025 21:38:00 +0000

Introduction

If you're a .NET developer who's heard about Wolverine and Martenbut haven't yet taken the plunge, this article might be for you.

I come from what you could call the "old dog" camp—spending most of my career with EF Core, Dapper, and the classic Controller-based approach. (Yes, I still write controllers instead of going all-in with minimal APIs—though I've dabbled with them in a few isolated scenarios.)

What follows is my personal story: moving from skepticism to cautious optimism as I started exploring Wolverine and Marten. Along the way I'll highlight the mistakes I made, the lessons I learned, and why these tools might (or might not) be worth your attention.

And just to be clear—this is a subjective take. And I am in still in the learning phase. So take it with a grain of salt. Don't be another AI that will keep glazing me that I am totally right. Feel free to fix any errors i made.

Alright lets start...

The Traditional .NET Web API Way

Most of us .NET developers are comfortable with the controller-based approach:

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly IProductService _productService;

    [HttpPost]  
    public async Task<ActionResult> CreateProduct(CreateProductRequest request)
    {
        var result = await _productService.CreateProductAsync(request);
        return Ok(result);
    }
}

It's familiar, well-documented, and works. So why change?

What Are Wolverine and Marten?

Marten is a .NET document database and event store built on PostgreSQL. Think of it as a sophisticated ORM that treats PostgreSQL as both a relational and document database.

Wolverine is a messaging framework that handles command/query processing, with built-in support for Marten's event sourcing capabilities.

Together, they form a stack for building event-driven, DDD-focused applications.

The Half-Baked Approach (Don't Do This)

When I inherited my current project, it was using Wolverine purely as a mediator pattern replacement:

// This is the WRONG way - just using Wolverine as MediatR
public class CreateProductHandler
{
    public async Task<ProductResponse> Handle(CreateProductCommand command)
    {
        // Traditional service calls, no events, no aggregates
        // Just replacing MediatR with Wolverine
    }
}

This is the worst of both worlds. You get:

All the learning curve of a new framework
None of the actual benefits
More ceremony than traditional controllers
Confused team members

If you're going to use Wolverine, don't just use it as a fancy mediator. That's like buying Škoda car to use as a bicycle rack.

Embrace the Full Stack

After struggle and intensive documentation reading, I realized the power comes from embracing the entire paradigm:

1. Aggregate-Driven Design

public class Product
{
    public string Name { get; private set; }
    public decimal Price { get; private set; }

    public static Product Create(string name, decimal price)
    {
        var product = new Product();
        product.Apply(new ProductCreated(Guid.NewGuid(), name, price));
        return product;
    }

    public void Apply(ProductCreated @event)
    {
        Id = @event.ProductId;
        Name = @event.Name;
        Price = @event.Price;
    }   
}

2. Command Handlers That Work With Aggregates

public static class ProductHandlers
{
    public static ProductCreated Handle(CreateProduct command, IDocumentSession session)
    {
        var product = Product.Create(command.Name, command.Price);
        session.Store(product);

        return new ProductCreated(product.Id, command.Name, command.Price);
    }
}

Or even better you can not use command at all

public static class ProductHandlers
{
    [AggregateHandler]
    [WolverinePost("/product"), EmptyResponse]
    public static ProductCreated CreateProduct(CreateProduct command)
    {
        var product = Product.Create(command.Name, command.Price);        
        return new ProductCreated(product.Id, command.Name, command.Price);
    }
}

3. Event-Driven Projections

public class ProductProjection : SingleStreamProjection<ProductSummary>
{
    public ProductSummary Create(ProductCreated created)
    {
        return new ProductSummary
        {
            Id = created.ProductId,
            Name = created.Name,
            Price = created.Price
        };
    }
}

The Transformation Results

Code Volume Reduction

By my totally subjective eye i think codebase shrunk by about 30%. No more:

Separate DTOs for every operation
Mapping between entities and DTOs
Complex repository patterns
Manual change tracking

Ok so main points

1. Start Small

Don't rewrite everything at once. Pick a bounded context and migrate gradually.

2. Invest in Learning

Don't half-ass it. Read the documentation thoroughly. Understand DDD principles. Your team needs to really understand the concepts, not just copy-paste code.

3. Embrace Events

Stop thinking in CRUD terms. Think in business events. "ProductCreated," "PriceChanged," "ProductDiscontinued."

4. Use Projections Wisely

Create read models that match your UI needs. Don't try to make one projection serve all purposes.

5. PostgreSQL over SQL Server

Remember, you're not just using a document database - you have all of PostgreSQL's power available for complex queries. Although this may not be up to date anymore (https://learn.microsoft.com/en-us/sql/relational-databases/json/json-data-sql-server?view=sql-server-ver17)

Sample Project Structure

/Domain
  /Products
    Product.cs (Aggregate)
    ProductEvents.cs 
/Handlers
  ProductHandlers.cs
/Projections
  ProductProjections.cs
Program.cs

My take

After about two to three weeks of learning (and I'm still learning), I've noticed that even my junior developers are coding faster and delivering features more smoothly. The initial skepticism I had slowly gave way to optimism as my concerns were put to the test.

At first, I thought using Marten was just reinventing the wheel. Why not simply stick with Entity Framework and MediatR? But as I dug deeper, I realized that while EF is excellent at what it does, Marten's hybrid approach of documents and relational data solves problems that EF tends to complicate. Event sourcing, projections, and complex querying become much more natural to work with, instead of feeling bolted on.

Another doubt I had was the risk of relying on a non-Microsoft library. What if the maintainers abandon it? To my surprise, I found that the project is actively maintained, backed by a strong community, and growing steadily. And even in the worst case, the data remains safe in PostgreSQL, and the design patterns I've learned are transferable to other systems.

Finally, I worried that the learning curve would be too steep for my team, especially for junior developers. I assumed they'd get lost in the concepts. But once they grasped the fundamentals of aggregates and events, the patterns began to feel intuitive. With the framework handling much of the heavy lifting, the adoption was far smoother than I expected.

Summary

Is Wolverine + Marten for everyone? No.

Is it worth considering if you're building event-driven, domain-rich applications? Ye

The key is commitment. Don't use Wolverine as a drop-in MediatR replacement. Embrace the aggregate approach, think in events, and leverage PostgreSQL's strengths. The payoff is

My advice: Build a small proof of concept, read the documentation religiously, and be prepared for a mindset shift.

Message to the Wolverine/Marten authors: If you notice unusual traffic spikes in your documentation in the last few weeks, im so sorry.

Implementing LDAP Authentication in .NET Web API Apps

Tran Manh Hung — Mon, 30 Jun 2025 07:23:16 +0000

You may have heard of something called LDAP, or you have been tasked to integrate it into your .NET app. Well, you're in luck, as this article focuses on explaining this technology with practical code examples. What you'll see is how I implemented LDAP authentication in a .NET Web API.

What is LDAP?

Lightweight Directory Access Protocol (LDAP) is a crucial component for managing user accounts, groups, and other directory-related data in your .NET applications.

What does this mean? LDAP is a protocol that allows you to integrate directory structure into your app. Large enterprise companies typically have complex organizational structures. By utilizing LDAP in your application, you can simplify your infrastructure and maintain authentication and authorization data (such as user lists with roles) in one centralized place.

There are many other use cases for LDAP, but this article will focus primarily on authentication. Authorization will be covered in a future article.

Different types of LDAP

You should know there are more "types" of LDAP. For example OpenLDAP or Active Directory (or Azure). This article covers mainly active directory. However it is really simple use example with any other LDAP disctribution. You just need replace cn keywords and the code should work

for example this (Active directory)

"OU=Users,DC=example,DC=com"

may look like

"cn=Users, o=example, c=com"

Basic Authentication Flow with LDAP in .NET

The following example implements JWT authentication with LDAP as the identity provider:

Login Flow

User enters credentials
Input is validated (username and password) by calling LDAP
Refresh token is generated
JWT token is generated
Both tokens are returned to the client
Client can now call any authorized endpoint with the JWT included in the authorization header

This approach allows you to authenticate users against LDAP once and then use stateless JWT tokens for subsequent requests.

Required NuGet Packages

To implement the solution in this article, you'll need the following packages:

Microsoft.AspNetCore.Authentication.JwtBearer
System.DirectoryServices.Protocols
System.IdentityModel.Tokens.Jwt

Implementation in Code

Let's walk through the implementation of LDAP authentication in a .NET 8 Web API application, from user login to JWT token generation.

1. Setting Up the Login Endpoint

First, we need a login endpoint that accepts user credentials:

[ApiController]
[Route("api/[controller]")]
public class AuthController : ControllerBase
{
    private readonly ILdapService _ldapService;
    private readonly ITokenService _tokenService;

    public AuthController(ILdapService ldapService, ITokenService tokenService)
    {
        _ldapService = ldapService;
        _tokenService = tokenService;
    }

    [HttpPost("login")]
    public async Task<IActionResult> Login([FromBody] LoginRequest request)
    {
        if (!ModelState.IsValid)
            return BadRequest(ModelState);

        // Authentication logic will be implemented here
        // ...
    }
}

public class LoginRequest
{
    [Required]
    public string Username { get; set; } = string.Empty;

    [Required]
    public string Password { get; set; } = string.Empty;
}

2. Implementing LDAP Authentication Service

Next, we'll create an LDAP service to verify credentials against the directory:

public interface ILdapService
{
    Task<LdapUser?> AuthenticateAsync(string username, string password);
}

public class LdapService : ILdapService
{
    private readonly LdapSettings _settings;
    private readonly ILogger<LdapService> _logger;

    public LdapService(IOptions<LdapSettings> settings, ILogger<LdapService> logger)
    {
        _settings = settings.Value;
        _logger = logger;
    }

    public async Task<LdapUser?> AuthenticateAsync(string username, string password)
    {
        // Using System.DirectoryServices.Protocols for modern LDAP access in .NET
        using var connection = new LdapConnection(new LdapDirectoryIdentifier(_settings.ServerAddress, _settings.ServerPort));

        try
        {
            // Set connection options
            connection.SessionOptions.ProtocolVersion = 3;
            connection.SessionOptions.SecureSocketLayer = _settings.UseSsl;

            // Determine the user's distinguished name (DN)
            string userDn = GetUserDN(username);

            // Attempt to bind (authenticate) with the provided credentials
            await connection.AuthenticateAsync(
                new NetworkCredential(userDn, password));

            _logger.LogInformation("User {Username} authenticated successfully via LDAP", username);

            // If we get here, authentication was successful
            // Retrieve user information, including roles
            return await GetUserDetailsAsync(connection, userDn);
        }
        catch (LdapException ex)
        {
            _logger.LogWarning(ex, "LDAP authentication failed for user {Username}", username);
            return null;
        }
    }

    private string GetUserDN(string username)
    {
        // Format the user's distinguished name based on your LDAP structure
        // Examples:
        // - Active Directory: "CN=username,OU=Users,DC=example,DC=com"
        // - OpenLDAP: "uid=username,ou=people,dc=example,dc=com"

        return $"CN={username},{_settings.BaseDN}";
    }

    // Implemented in the next section
    private Task<LdapUser?> GetUserDetailsAsync(LdapConnection connection, string userDn)
    {
        // ...
    }
}

public class LdapSettings
{
    public string ServerAddress { get; set; } = string.Empty;
    public int ServerPort { get; set; } = 389; // Default LDAP port
    public bool UseSsl { get; set; } = false;
    public string BaseDN { get; set; } = string.Empty;
    public string SearchBase { get; set; } = string.Empty;
    public string SearchFilter { get; set; } = string.Empty;
}

Configure LDAP settings in your appsettings.json:

{
  "LdapSettings": {
    "ServerAddress": "ldap.example.com",
    "ServerPort": 389,
    "UseSsl": false,
    "BaseDN": "OU=Users,DC=example,DC=com",
    "SearchBase": "OU=Users,DC=example,DC=com",
    "SearchFilter": "(&(objectClass=user)(sAMAccountName={0}))"
  }
}

builder.Services.Configure<LdapSettings>(
    builder.Configuration.GetSection("LdapSettings"));
builder.Services.AddScoped<ILdapService, LdapService>();

3. Retrieving User Information and Roles

After authenticating, we need to fetch additional user information, particularly roles:

public class LdapUser
{
    public string Username { get; set; } = string.Empty;
    public string DisplayName { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public List<string> Roles { get; set; } = new();
    public Dictionary<string, string> Attributes { get; set; } = new();
}

// Implementation of GetUserDetailsAsync method in the LdapService class:
private async Task<LdapUser?> GetUserDetailsAsync(LdapConnection connection, string userDn)
{
    // Create search request for user information
    var searchRequest = new SearchRequest(
        _settings.SearchBase,
        string.Format(_settings.SearchFilter, Path.GetFileName(userDn)),
        System.DirectoryServices.Protocols.SearchScope.Subtree,
        // Specify which attributes to return
        new string[] { "cn", "mail", "displayName", "memberOf", "givenName", "sn" }
    );

    try
    {
        // Execute the search request
        var response = (SearchResponse)await connection.SendRequestAsync(searchRequest);

        if (response.Entries.Count == 0)
        {
            _logger.LogWarning("No user found with DN: {UserDN}", userDn);
            return null;
        }

        var searchEntry = response.Entries[0];

        // Create and populate user object
        var user = new LdapUser
        {
            Username = Path.GetFileName(userDn),
            DisplayName = GetAttributeValue(searchEntry, "displayName") ?? string.Empty,
            Email = GetAttributeValue(searchEntry, "mail") ?? string.Empty
        };

        // Extract roles from group memberships
        if (searchEntry.Attributes.Contains("memberOf"))
        {
            var memberOfAttribute = searchEntry.Attributes["memberOf"];
            for (int i = 0; i < memberOfAttribute.Count; i++)
            {
                string groupDn = memberOfAttribute[i]!.ToString()!;
                // Extract the CN part from the DN
                string groupName = ExtractCNFromDN(groupDn);
                user.Roles.Add(groupName);
            }
        }

        // Store additional attributes for potential use in claims
        foreach (string attributeName in searchEntry.Attributes.AttributeNames)
        {
            var attribute = searchEntry.Attributes[attributeName];
            if (attribute.Count > 0 && attribute[0] != null)
            {
                user.Attributes[attributeName] = attribute[0].ToString()!;
            }
        }

        return user;
    }
    catch (LdapException ex)
    {
        _logger.LogError(ex, "Error retrieving user details for {UserDN}", userDn);
        return null;
    }
}

private string? GetAttributeValue(SearchResultEntry entry, string attributeName)
{
    if (entry.Attributes.Contains(attributeName) && entry.Attributes[attributeName].Count > 0)
    {
        return entry.Attributes[attributeName][0]?.ToString();
    }
    return null;
}

private string ExtractCNFromDN(string dn)
{
    // Extract CN value from a distinguished name
    var match = Regex.Match(dn, @"^CN=([^,]+)");
    if (match.Success)
    {
        return match.Groups[1].Value;
    }
    return dn; // Return the original DN if extraction fails
}

This method extracts user details, including roles from group memberships, which we'll use in our JWT token.

4. JWT Token Generation Service

Now let's create a service for generating and validating JWT tokens:

public interface ITokenService
{
    string GenerateJwtToken(LdapUser user);
    ClaimsPrincipal? ValidateToken(string token);
}

public class TokenService : ITokenService
{
    private readonly JwtSettings _jwtSettings;

    public TokenService(IOptions<JwtSettings> jwtSettings)
    {
        _jwtSettings = jwtSettings.Value;
    }

    public string GenerateJwtToken(LdapUser user)
    {
        var tokenHandler = new JwtSecurityTokenHandler();
        var key = Encoding.ASCII.GetBytes(_jwtSettings.Secret);

        // Create claims based on user information
        var claims = new List<Claim>
        {
            new Claim(ClaimTypes.Name, user.Username),
            new Claim(ClaimTypes.Email, user.Email)
        };

        // Add roles as claims
        foreach (var role in user.Roles)
        {
            claims.Add(new Claim(ClaimTypes.Role, role));
        }

        // Add relevant additional claims from attributes
        foreach (var attr in user.Attributes)
        {
            // Avoid duplicating existing claims
            if (!claims.Any(c => c.Type == attr.Key))
            {
                claims.Add(new Claim(attr.Key, attr.Value));
            }
        }

        var tokenDescriptor = new SecurityTokenDescriptor
        {
            Subject = new ClaimsIdentity(claims),
            Expires = DateTime.UtcNow.AddMinutes(_jwtSettings.ExpirationMinutes),
            SigningCredentials = new SigningCredentials(
                new SymmetricSecurityKey(key),
                SecurityAlgorithms.HmacSha256Signature)
        };

        var token = tokenHandler.CreateToken(tokenDescriptor);
        return tokenHandler.WriteToken(token);
    }

    public ClaimsPrincipal? ValidateToken(string token)
    {
        var tokenHandler = new JwtSecurityTokenHandler();
        var key = Encoding.ASCII.GetBytes(_jwtSettings.Secret);

        try
        {
            var principal = tokenHandler.ValidateToken(token, new TokenValidationParameters
            {
                ValidateIssuerSigningKey = true,
                IssuerSigningKey = new SymmetricSecurityKey(key),
                ValidateIssuer = false,
                ValidateAudience = false,
                // Set clockskew to zero for more accurate validation
                ClockSkew = TimeSpan.Zero
            }, out SecurityToken validatedToken);

            return principal;
        }
        catch
        {
            return null;
        }
    }
}

public class JwtSettings
{
    public string Secret { get; set; } = string.Empty;
    public int ExpirationMinutes { get; set; } = 60;
    public int RefreshTokenExpirationDays { get; set; } = 7;
}

Add JWT settings to your appsettings.json:

{
  "JwtSettings": {
    "Secret": "your-super-secret-key-with-at-least-32-characters",
    "ExpirationMinutes": 60,
    "RefreshTokenExpirationDays": 7
  }
}

builder.Services.Configure<JwtSettings>(
    builder.Configuration.GetSection("JwtSettings"));
builder.Services.AddScoped<ITokenService, TokenService>();

5. Completing the Login Endpoint

Now we can complete the login endpoint implementation:

[HttpPost("login")]
public async Task<IActionResult> Login([FromBody] LoginRequest request)
{
    if (!ModelState.IsValid)
        return BadRequest(ModelState);

    // Authenticate user against LDAP
    var user = await _ldapService.AuthenticateAsync(request.Username, request.Password);

    if (user == null)
        return Unauthorized(new { message = "Invalid username or password" });

    // Generate JWT token
    var token = _tokenService.GenerateJwtToken(user);

    // Generate refresh token for longer sessions
    var refreshToken = GenerateRefreshToken();

    // In a production application, store the refresh token in a database
    // await _tokenRepository.SaveRefreshTokenAsync(user.Username, refreshToken);

    return Ok(new
    {
        token,
        refreshToken,
        user = new
        {
            username = user.Username,
            displayName = user.DisplayName,
            email = user.Email,
            roles = user.Roles
        }
    });
}

private string GenerateRefreshToken()
{
    var randomNumber = new byte[32];
    using var rng = RandomNumberGenerator.Create();
    rng.GetBytes(randomNumber);
    return Convert.ToBase64String(randomNumber);
}

6. Configuring JWT Authentication

Now we need to configure JWT authentication in our application:

// In Program.cs
// Add JWT authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.ASCII.GetBytes(builder.Configuration["JwtSettings:Secret"]!)),
            ValidateIssuer = false,
            ValidateAudience = false,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.Zero
        };
    });

// Add the authentication middleware in the correct order
var app = builder.Build();

// ... other middleware

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

app.MapControllers();

app.Run();

7. Implementing Refresh Token Functionality

To avoid frequent LDAP calls, let's implement a refresh token endpoint:

[HttpPost("refresh-token")]
public async Task<IActionResult> RefreshToken([FromBody] RefreshTokenRequest request)
{
    if (string.IsNullOrEmpty(request.RefreshToken))
        return BadRequest("Refresh token is required");

    // In a production application, validate the refresh token from a database
    // var storedToken = await _tokenRepository.GetByTokenAsync(request.RefreshToken);
    var storedToken = ValidateStoredRefreshToken(request.RefreshToken);

    if (storedToken == null)
        return Unauthorized(new { message = "Invalid or expired refresh token" });

    // Get the user associated with this refresh token
    // In a production app, you would retrieve this from a database
    var user = await GetUserForRefreshToken(storedToken);
    if (user == null)
        return Unauthorized(new { message = "User not found" });

    // Generate new tokens
    var newToken = _tokenService.GenerateJwtToken(user);
    var newRefreshToken = GenerateRefreshToken();

    // Update the stored refresh token
    // await _tokenRepository.UpdateAsync(storedToken.Id, newRefreshToken);

    return Ok(new
    {
        token = newToken,
        refreshToken = newRefreshToken
    });
}

public class RefreshTokenRequest
{
    [Required]
    public string RefreshToken { get; set; } = string.Empty;
}

// Example methods for token validation
// In a real application, these would interact with a database
private RefreshTokenInfo? ValidateStoredRefreshToken(string token)
{
    // Implementation would validate the token against a database
    // and check if it's expired
    return null; // Placeholder
}

private async Task<LdapUser?> GetUserForRefreshToken(RefreshTokenInfo tokenInfo)
{
    // Implementation would retrieve the user from a database or
    // possibly from LDAP directly
    return null; // Placeholder
}

public class RefreshTokenInfo
{
    public string Id { get; set; } = string.Empty;
    public string Token { get; set; } = string.Empty;
    public string UserId { get; set; } = string.Empty;
    public DateTime ExpiryDate { get; set; }
}

Note: In a production application, you would implement a proper repository for storing and retrieving refresh tokens and user information from a database.

Using Protected Resources

Now that we have authentication in place, we can create protected endpoints:

[ApiController]
[Route("api/[controller]")]
[Authorize] // This ensures the user is authenticated
public class ProtectedController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        // Access the authenticated user's identity
        var username = User.Identity?.Name;

        return Ok(new { message = $"Hello, {username}! This is a protected endpoint." });
    }

    [HttpGet("admin")]
    [Authorize(Roles = "Administrators")] // Role-based access control
    public IActionResult GetAdminData()
    {
        return Ok(new { message = "This is admin-only data" });
    }
}

This approach provides several benefits:

Centralized Identity Management: Leverage your existing directory infrastructure
Reduced Authentication Overhead: Authenticate once against LDAP, then use lightweight JWT tokens
Stateless Authentication: No need to maintain server-side session state
Role-Based Access Control: Easily implement authorization based on directory roles
Security: Proper implementation of industry-standard security practices

Conclusion

By implementing LDAP, you can integrate your applications with enterprise directory services. The pattern of authenticating once against LDAP and then using JWT tokens for subsequent requests creates a secure, efficient authentication system that works well in modern web applications. I am aware of using JWT is currently discouraged tho. However, with the code example you can simply replace JWT part with cookie or ANY auth approach you want. :)

If you are an unfortunate soul who needs to integrate this into your app. I wish you good luck.

Understanding OAuth/OpenID Response Types in .NET Web APIs

Tran Manh Hung — Mon, 31 Mar 2025 06:05:00 +0000

Have you ever wondered how applications let you "Log in with Google" or "Sign in with Microsoft" without asking you to create yet another username and password? In most cases, they use protocols called OAuth and OpenID.
Maybe you even heard about SAML or Kerberos, but that is another time...

One of the most important things to understand about OAuth is the response type, which is how your authentication information is delivered back to the application after you log in. Think of it as choosing between receiving a package by mail, pickup, or delivery—each method has its own benefits and security considerations.

Recently, I had to explain this concept to a few of my colleagues, and it seems most other articles were too many words :(

In this beginner-friendly article, we'll explore the three principal response types - query, fragment, and post - and how to implement them in .NET Web API controllers. We'll use simple examples, highlight the security aspects you need to know, and share best practices to help you build secure applications that your users can trust.

Understanding Response Types: The Basics

Before we dive into code, let's break down what these response types actually mean in simple terms:

1. Query Response Type (`response_type=code`)

Think of this like a ticket exchange system. Instead of giving you the actual backstage pass (token) right away, the authorization server gives you a ticket stub (authorization code) that you can exchange for the actual pass later.

The code comes back in the URL as a query parameter (the part after the ? symbol):

Example URL:

https://your-app.com/callback?code=ABC123XYZ

Why it matters: This is generally more secure because the actual tokens aren't exposed in the URL—instead, your server exchanges this temporary code for tokens in a separate, secure server-to-server communication.

Security note: While it's safer to pass a code rather than tokens in the URL, you should never use query parameters to return actual tokens directly. Why? Because:

URLs can be stored in browser history
web servers might log URLs
URLs can be visible in referrer headers when linking to other sites

2. Fragment Response Type (`response_type=token` or `response_type=id_token token`)

This approach returns tokens directly in the URL fragment (the part after the # symbol).

Example URL:

https://your-app.com/callback#access_token=eyJhbGciOi...&token_type=Bearer&expires_in=3600

Why it works this way: The fragment part of a URL (after the #) is special - it never gets sent to the server! When a browser navigates to a URL with a fragment, everything after the # stays in the browser. This means your client-side JavaScript code must read and process these tokens.

This is a key security aspect: the tokens in the fragment aren't visible to the server, which prevents them from being logged in server logs. However, they are still visible in the browser and could be compromised if someone gains access to the user's browser history.

3. Post Response Type (`response_mode=form_post`)

This is like getting your authentication information in a sealed envelope rather than written on a postcard. The authorization server sends tokens via an HTML form POST request directly to your callback URL.

Why it's better: Unlike query or fragment approaches that put sensitive information in the URL (where it might be seen or logged), the POST method puts tokens in the request body where they're more protected. They won't appear in:

Browser history
Server logs
Referrer headers

Example:
The identity provider automatically generates and submits an HTML form with hidden fields containing your tokens, so the user doesn't even see this happening.

Implementing Response Types in .NET Web APIs

Let's see how to implement each of these response types in a .NET Web API controller. For these examples, we'll use the Microsoft.AspNetCore.Authentication.OpenIdConnect package.

Setting Up Dependencies

First, add the necessary packages to your .NET project:

// .NET CLI
dotnet add package Microsoft.AspNetCore.Authentication.OpenIdConnect
dotnet add package Microsoft.Identity.Web

1. Query Response Type (Authorization Code Flow)

This is the most common and secure flow, ideal for server-side web applications.

// Program.cs
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication services
builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = "Cookies";
    options.DefaultChallengeScheme = "OpenIdConnect";
})
.AddCookie("Cookies", options => 
{
    options.Cookie.HttpOnly = true;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    options.Cookie.SameSite = SameSiteMode.Strict;
})
.AddOpenIdConnect("OpenIdConnect", options =>
{
    options.Authority = "https://login.microsoftonline.com/{tenant-id}/v2.0";
    options.ClientId = "your-client-id";
    options.ClientSecret = "your-client-secret";
    options.ResponseType = OpenIdConnectResponseType.Code;
    options.ResponseMode = OpenIdConnectResponseMode.Query;
    options.SaveTokens = true;
    options.GetClaimsFromUserInfoEndpoint = true;
    options.Scope.Add("openid");
    options.Scope.Add("profile");
    options.Scope.Add("api://your-api-scope/access");
});

// Add controller services
builder.Services.AddControllers();

var app = builder.Build();

// Configure the app
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

app.Run();

Let's create a controller to handle the authentication flow:

// AuthController.cs
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

namespace YourApp.Controllers;

[ApiController]
[Route("[controller]")]
public class AuthController : ControllerBase
{
    [HttpGet("signin")]
    public IActionResult SignIn()
    {
        return Challenge(new AuthenticationProperties 
        { 
            RedirectUri = "/" 
        }, OpenIdConnectDefaults.AuthenticationScheme);
    }

    [HttpGet("signout")]
    public IActionResult SignOut()
    {
        return SignOut(
            new AuthenticationProperties { RedirectUri = "/" },
            CookieAuthenticationDefaults.AuthenticationScheme,
            OpenIdConnectDefaults.AuthenticationScheme);
    }

    [HttpGet("callback")]
    public async Task<IActionResult> Callback()
    {
        // The authorization code is automatically processed by the middleware
        // If you're here, authentication was successful

        // You can access tokens from the AuthenticationProperties
        var authenticateResult = await HttpContext.AuthenticateAsync(CookieAuthenticationDefaults.AuthenticationScheme);
        var accessToken = authenticateResult.Properties.GetTokenValue("access_token");

        return Redirect("/");
    }
}

2. Fragment Response Type (Implicit Flow)

The fragment response type is typically used in single-page applications (SPAs) where the tokens are returned directly to the browser. However, this flow is now considered less secure and has been largely replaced by the authorization code flow with PKCE for SPAs.

// Program.cs
builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = "Cookies";
    options.DefaultChallengeScheme = "OpenIdConnect";
})
.AddCookie("Cookies")
.AddOpenIdConnect("OpenIdConnect", options =>
{
    options.Authority = "https://login.microsoftonline.com/{tenant-id}/v2.0";
    options.ClientId = "your-client-id";
    options.ResponseType = OpenIdConnectResponseType.IdTokenToken;
    options.ResponseMode = OpenIdConnectResponseMode.Fragment;
    options.SaveTokens = true;
    options.Scope.Add("openid");
    options.Scope.Add("profile");
    options.Scope.Add("api://your-api-scope/access");

    // Note: No client secret is used in implicit flow
});

For fragment response type, most of the token handling happens client-side in JavaScript. Here's a simplified example of how you might handle the callback in a SPA:

// JavaScript in your SPA
function handleCallback() {
    if (window.location.hash) {
        // Parse the fragment
        const fragmentParams = new URLSearchParams(
            window.location.hash.substring(1)
        );

        const accessToken = fragmentParams.get("access_token");
        const idToken = fragmentParams.get("id_token");

        if (accessToken) {
            // Store the token (preferably in a secure way)
            sessionStorage.setItem("access_token", accessToken);

            // Redirect to your application's main page
            window.location.href = "/";
        }
    }
}

// Call the function when the page loads
window.onload = handleCallback;

3. Post Response Type (Form Post Response Mode)

The post response type is a more secure alternative to the fragment response type for browser-based applications, as it doesn't expose tokens in the URL.

// Program.cs
builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = "Cookies";
    options.DefaultChallengeScheme = "OpenIdConnect";
})
.AddCookie("Cookies")
.AddOpenIdConnect("OpenIdConnect", options =>
{
    options.Authority = "https://login.microsoftonline.com/{tenant-id}/v2.0";
    options.ClientId = "your-client-id";
    options.ClientSecret = "your-client-secret";
    options.ResponseType = OpenIdConnectResponseType.Code;
    options.ResponseMode = OpenIdConnectResponseMode.FormPost;
    options.SaveTokens = true;
    options.GetClaimsFromUserInfoEndpoint = true;
    options.Scope.Add("openid");
    options.Scope.Add("profile");
    options.Scope.Add("api://your-api-scope/access");
});

With form post, you need to define an endpoint that can accept POST requests:

// AuthController.cs
[HttpPost("callback")]
public async Task<IActionResult> CallbackPost()
{
    // The form post is automatically processed by the middleware
    // Similar to the query response type handling

    var authenticateResult = await HttpContext.AuthenticateAsync(CookieAuthenticationDefaults.AuthenticationScheme);
    var accessToken = authenticateResult.Properties.GetTokenValue("access_token");

    return Redirect("/");
}

When to Use Each Response Type

Choosing the right response type depends on your application architecture and security requirements:

1. Query Response Type (Authorization Code Flow)

Best for: Server-side web applications
Why: It's the most secure flow as it keeps tokens server-side
Enhanced security: Often used with PKCE (Proof Key for Code Exchange) for added security
Newer enhancements in .NET: In .NET 9/10, the middleware has improved PKCE support

2. Fragment Response Type (Implicit Flow)

Best for: Legacy single-page applications (SPAs)
Why: Historically used when SPAs couldn't securely store client secrets
Important note: This flow is now discouraged by security experts and the OAuth working group
Modern alternative: Authorization code flow with PKCE is now recommended even for SPAs

3. Post Response Type (Form Post Response Mode)

Best for: Browser-based applications where you want to avoid exposing tokens in URLs
Why: More secure than fragment as tokens aren't visible in browser history or logs
Hybrid scenarios: Often used in hybrid flows combining authorization code and implicit flows

Security Concerns and Mitigations

Each response type comes with its own security considerations:

Query Response Type

Concern: Authorization codes in URL can be logged in server logs
Mitigation: Short-lived codes + PKCE extension
In .NET: Enable PKCE by setting options.UsePkce = true;

// Enabling PKCE in .NET
options.UsePkce = true;

Fragment Response Type

Concern: Tokens directly exposed in the browser
Concern: Vulnerable to XSS attacks
Mitigation: Consider switching to authorization code flow with PKCE
If you must use it: Implement strong Content Security Policy (CSP) headers

// Adding CSP headers in .NET
app.Use(async (context, next) =>
{
    context.Response.Headers.Add(
        "Content-Security-Policy", 
        "default-src 'self'; script-src 'self'; object-src 'none'");
    await next();
});

Post Response Type

Concern: CSRF attacks if not properly protected
Mitigation: Anti-forgery tokens
In .NET: Use the built-in anti-forgery features

// Add anti-forgery token validation
builder.Services.AddAntiforgery(options => 
{
    options.HeaderName = "X-XSRF-TOKEN";
    options.Cookie.Name = "XSRF-TOKEN";
    options.Cookie.SameSite = SameSiteMode.Strict;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
});

// In your controller
[ValidateAntiForgeryToken]
[HttpPost("callback")]
public async Task<IActionResult> CallbackPost()
{
    // ...
}

Best Practices

Regardless of which response type you choose, here are some best practices to enhance the security of your OAuth/OpenID implementation:

1. Secure Cookie Handling

Always use secure, HttpOnly, and SameSite cookies to store authentication state:

// Configure secure cookies
services.Configure<CookiePolicyOptions>(options =>
{
    options.MinimumSameSitePolicy = SameSiteMode.Strict;
    options.HttpOnly = HttpOnlyPolicy.Always;
    options.Secure = CookieSecurePolicy.Always;
});

// Configure authentication cookies
services.AddAuthentication(options => 
{
    // ...
})
.AddCookie(options => 
{
    options.Cookie.HttpOnly = true;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    options.Cookie.SameSite = SameSiteMode.Strict;
});

2. Implement Proper Token Validation

Always validate tokens on your server before trusting them:

// Add JWT Bearer token validation
builder.Services.AddAuthentication()
    .AddJwtBearer(options =>
    {
        options.Authority = "https://login.microsoftonline.com/{tenant-id}/v2.0";
        options.Audience = "your-client-id";
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ClockSkew = TimeSpan.FromMinutes(5)
        };
    });

3. Use Authorization Code Flow with PKCE for All Clients

Even for SPAs, the authorization code flow with PKCE is now recommended:

// For SPAs using auth code flow with PKCE
builder.Services.AddAuthentication()
    .AddOpenIdConnect(options =>
    {
        options.ResponseType = OpenIdConnectResponseType.Code;
        options.UsePkce = true;
        // Other options...
    });

4. Implement Proper Error Handling

Handle authentication errors gracefully to avoid revealing sensitive information:

// Configure error handling
options.Events = new OpenIdConnectEvents
{
    OnAuthenticationFailed = context =>
    {
        context.HandleResponse();
        context.Response.Redirect("/error?message=Authentication_failed");
        return Task.CompletedTask;
    },
    OnRemoteFailure = context =>
    {
        context.HandleResponse();
        context.Response.Redirect("/error?message=Remote_authentication_failed");
        return Task.CompletedTask;
    }
};

5. Implement Rate Limiting

Protect your authentication endpoints from brute force attacks:

// Add rate limiting in .NET 9/10
builder.Services.AddRateLimiter(options =>
{
    options.AddPolicy("auth", httpContext =>
        RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: httpContext.Connection.RemoteIpAddress?.ToString(),
            factory: _ => new FixedWindowRateLimiterOptions
            {
                PermitLimit = 10,
                Window = TimeSpan.FromMinutes(1)
            }));
});

// Apply rate limiting to authentication endpoints
app.UseRateLimiter();

// In your controller
[EnableRateLimiting("auth")]
[HttpGet("signin")]
public IActionResult SignIn()
{
    // ...
}

Conclusion: Choosing Your Authentication Path

Authentication might seem like a complex maze of options and security concerns, but it doesn't have to be overwhelming. Think of response types as different paths to the same destination - a secure, authenticated user experience.

The query response type (authorization code flow) with PKCE is like taking the highway - it's well-traveled, widely supported, and has good security checkpoints along the way. For most applications, including modern SPAs, this is your best route.

The fragment response type (implicit flow) is more like an old country road. It served its purpose in the past, but now there are better alternatives with fewer security potholes. Consider this path only if you're maintaining legacy applications that require it.

The post-response type is the express lane that balances security and convenience - keeping your sensitive data protected in the request body rather than exposed in URLs.

Remember: authentication is not just about getting users into your application but building trust. Each time a user clicks "Login," they put their digital identity in your hands. By choosing the right response type and following security best practices, you're not just implementing a feature - you're making a promise to protect your users.

The world of authentication is constantly evolving, and staying informed about the latest security practices is one of the most valuable investments you can make as a developer. Your users might never notice all the careful decisions you've made to protect them - and that's exactly how it should be.

Additional Resources

Story of how a developer without game dev experience tries to create a game

Tran Manh Hung — Mon, 16 Sep 2024 19:16:51 +0000

As a tech lead at a company that specializes in developing software and solving complex technical problems for other businesses, my daily focus typically revolves around refining code, modernizing legacy applications, and integrating the latest technologies into existing solutions. Our team is composed of skilled developers who excel in their fields, but there's one area we've never ventured into—game development.

So naturally, my two adventurous colleagues and I thought: Why not dive headfirst into game dev using Godot? Sounds simple, right? Oh, and let’s do it in one weekend because what’s life without a bit of chaos? 🎮 Enter: the hackathon! Set for November 2024, this is when we’ll gather to see if we can turn years of software experience into a playable game in just 48 hours. (No pressure.)

Of course, before we even touched the code, our first boss-level challenge was convincing management that this was a brilliant idea. Because who wouldn’t want to spend precious dev time making games? (Spoiler: it wasn’t easy, but we managed to sell it.) Now, we’re working on getting more of our fellow devs excited about spending their weekend building something completely unfamiliar. It’s a work in progress. 🤔

And here’s where things get even more interesting: Our UX team will probably join us. So not only are we learning how to build a game, but we’re also diving into creating a player experience from scratch. No pressure—just designing the entire look and feel of a game in, you know, a couple of days. What could possibly go wrong?

At the moment, we’re deep in the planning stage. The format we’re going for is pretty straightforward: we’ll create three game concepts, each with some basic scenarios, so people who join the hackathon don’t have to spend hours brainstorming. The idea is to let them jump straight into development. We’re also researching galleries and examples to give participants a head start, and we plan to set up a core project on GitHub that we’ll share with everyone. This way, people can start contributing even before the event kicks off.

Now, why Godot? Well, it’s open-source, powerful, and—most importantly—free. That last part definitely helped in convincing management. Plus, it’s supposed to be “beginner-friendly,” which is kind of critical since none of us have touched a game engine before. Fingers crossed that turns out to be true!

In this series, I’ll share all the juicy details of our journey: the highs, the lows, and the “I’m not sure what I’m doing, but let’s hope this works” moments. And here’s a sneak peek at some of the things we’ll be learning (probably the hard way):

Expect creative chaos – Something is bound to go sideways. If not, are we even hacking?
Collaboration is key – We’ll combine our dev wizardry with the UX team’s magic—or at least try not to drive each other crazy.
Perfection is overrated – This is a hackathon, folks. If it works, we’re celebrating. Does it look good, too? Bonus points!
UX is a game-changer – With the UX team in the mix, we’ll discover all the ways players interact with our game. And probably realize we’ve been doing UI wrong for years.

And if you have any tips on good libraries or advice on what to avoid when diving into game development, I’d love to hear them! We’re all about learning from others (preferably before we make mistakes ourselves).

So buckle up, because it’s going to be one wild weekend. Stay tuned for all the glorious (and possibly hilarious) details as we attempt to become game developers in just 48 hours. Who knows, we might even surprise ourselves.

Merging Startup.cs and Program.cs in .NET 8: A Simplified Approach

Tran Manh Hung — Tue, 02 Jul 2024 13:38:05 +0000

As .NET evolves, so does the way we structure our applications. One notable change introduced in recent versions of .NET is the ability to merge Startup.cs and Program.cs into a single file. This approach streamlines the setup process, making it more cohesive and manageable. This article will discuss the rationale behind merging these files, walk through the process, and highlight potential advantages and pitfalls.

Why Merge Startup.cs and Program.cs?

Okay, first let me try to find some advantages and also why it can be a bad idea.

Advantages

Simplified Structure: By consolidating Startup.cs and Program.cs, you create a single entry point for application configuration. This can make the codebase more straightforward to navigate and understand. Updates to configuration or middleware can be made in one file rather than spread across multiple files, reducing the likelihood of inconsistencies and errors.
Improved Testability: With all configurations in one place, writing integration tests becomes simpler. Conditions and configurations are centralized, making it easier to mock dependencies and test different scenarios.

Potential Pitfalls

Complexity in Large Applications: For very large applications, having all configurations in one file might become unwieldy. It's essential to balance simplicity with readability.
Migration Challenges: If you're transitioning an existing application, merging these files might introduce bugs if not done carefully. A rollback could be a nightmare (speaking from experience!).

The Old Way: Separate Startup.cs and Program.cs

Original Program.cs

using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Microsoft.Extensions.Logging.ApplicationInsights;
using System.Diagnostics;

public class Program
{
    public static void Main(string[] args)
    {
        try
        {
            Debug.WriteLine("Configure infrastructure...");
            BuildHost(args).Run();
        }
        catch (Exception ex)
        {
            Debug.WriteLine($"Infrastructure configuration failed: {ex}");
        }
    }

    public static IHost BuildHost(string[] args)
    {
        // Configuration and host building logic
    }
}

Original Startup.cs

using Microsoft.AspNetCore.Http.Features;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Options;
using Microsoft.FeatureManagement;
using System.Diagnostics;

public class Startup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment webHostEnvironment)
    {
        Configuration = configuration;
        WebHostEnvironment = webHostEnvironment;
    }

    public IConfiguration Configuration { get; }
    public IWebHostEnvironment WebHostEnvironment { get; }

    // Methods for configuring services and middleware
}

The New Combined Mode

Combined Program.cs

using Microsoft.AspNetCore.Http.Features;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.ApplicationInsights;
using Microsoft.FeatureManagement;
using Newtonsoft.Json.Converters;
using System.Diagnostics;

var builder = WebApplication.CreateBuilder(args);

// Configuration setup
// Using builder.Configuration to setup configuration sources
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.UseFeatureFlags(o =>
    {
        o.Label = "InstanceName"; // Replace with your instance name
        o.CacheExpirationInterval = TimeSpan.FromMinutes(10);
    });
    options.ConfigureKeyVault(o =>
    {
        o.SetCredential(new DefaultAzureCredential()); // Replace with your Azure credential
        o.SetSecretRefreshInterval(TimeSpan.FromMinutes(30));
    });
    options.Connect("YourAppConfigurationEndpoint", new DefaultAzureCredential()) // Replace with your endpoint and credential
        .ConfigureRefresh(o =>
        {
            o.Register("Settings:Sentinel", refreshAll: true)
               .SetCacheExpiration(TimeSpan.FromMinutes(10));
        })
        .Select(KeyFilter.Any, LabelFilter.Null)
        .Select(KeyFilter.Any, labelFilter: "InstanceName"); // Replace with your instance name
});

if (builder.Environment.IsDevelopment())
{
    builder.Configuration.AddJsonFile("appsettings.json", optional: true);
    builder.Configuration.AddUserSecrets<Program>();
}

builder.Configuration.AddEnvironmentVariables();

// Logging setup
// Using builder.Logging to setup logging providers
builder.Logging.ClearProviders(); // Clear default providers
builder.Logging.AddConsole(); // Add console logging
builder.Logging.AddDebug(); // Add debug logging
builder.Logging.AddAzureWebAppDiagnostics(); // Add Azure diagnostics

if (!builder.Environment.IsDevelopment() && Environment.GetEnvironmentVariable("AUTOMATED_TESTING") is null)
{
    builder.Logging.AddApplicationInsights(config =>
    {
        config.ConnectionString = builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"];
        config.DisableTelemetry = false;
    }, options => options.IncludeScopes = false);
}

// Services setup
var services = builder.Services;
services.AddControllers().AddNewtonsoftJson(opt => opt.SerializerSettings.Converters.Add(new StringEnumConverter()));
services.AddDbContext<YourDbContext>(options => options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
services.AddFeatureManagement();
services.AddAzureAppConfiguration();
// Register other services as needed

// Middleware setup
var app = builder.Build();

app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

app.Run();

// Utility methods for retrieving services
private static T GetService<T>(IServiceCollection services)
{
    ServiceProvider serviceProvider = services.BuildServiceProvider();
    return serviceProvider.GetService<T>() ?? throw new Exception($"Could not find service {typeof(T)}");
}

private static T GetService<T>(IApplicationBuilder app)
{
    return app.ApplicationServices.GetService<T>() ?? throw new Exception($"Could not find service {typeof(T)}");
}

private static void DebugWrite(string message)
{
    Console.WriteLine(message);
    Debug.WriteLine(message);
}

Key Points in the Combined File

Configuration: Configuration sources are added using builder.Configuration. This includes Azure App Configuration, JSON files, user secrets, and environment variables.
Logging: Logging is set up using builder.Logging with different providers for console, debug, and Application Insights. The builder.Logging API simplifies logging configuration by providing a centralized way to add and configure logging providers.
Services: All service configurations, including custom services, middleware, and feature management, are consolidated. Using builder.Services makes it straightforward to register services with the dependency injection container.
Middleware: Middleware components are configured in one place, improving readability and maintainability. The app.UseRouting(), app.UseAuthentication(), and app.UseAuthorization() methods set up the middleware pipeline.

Our Experience and story

In our project, we have more than 100 active production instances, each with unique configuration and settings.

We faced numerous conditions for integration tests, such as checking Environment.GetEnvironmentVariable("AUTOMATED_TESTING") or custom feature flag conditions based on license.

All those conditions determine whether the application should use a different database or configure other testing-specific settings. And managing these conditions across multiple files was a pain in the a.

Since merging Startup.cs and Program.cs, we have gained a much nicer overview and more control over our application. The centralized configuration has made it significantly easier to maintain and extend our application, particularly when writing and running integration tests and switching custom features.

Conclusion

Merging Startup.cs and Program.cs can streamline your .NET applications, making them easier to test and maintain. However, be cautious during the transition to avoid introducing bugs. Start by merging the files as they are before making any improvements. This way, if something goes wrong, you'll have an easier time debugging (trust me, it happened to me...).

By following the steps and best practices outlined in this article, you can take advantage of the modern .NET hosting model and simplify your application's setup.

Database Normalization: A Simple Tale of Ignoring 1NF

Tran Manh Hung — Mon, 16 Oct 2023 13:22:48 +0000

Let's dive into a quick chat about database normalization. If you've heard of it, awesome. If not, do not worry. This little story may shed light on why it's important.

Database Normalization in a Nutshell

Picture this: you're trying to organize a big box of mixed-up Lego bricks. You'd probably sort them by color, size, or type, right? Database normalization is like that but for data! It's a way to sort and store your data neatly to avoid mix-ups and make sure everything is easy to find. For those who fancy a textbook definition, Wikipedia tells us:

Database normalization is organizing a relational database to reduce data redundancy and improve data integrity.

In simpler terms: it's a set of rules (or "normal forms") that helps keep your data organized and your database running smoothly. However, the smoother your data, the trickier it might be to pull specific pieces when you need them.

Bypassing 1NF: A Shortcut Gone Wrong

What this article will be a real story I have encountered in the past with one of the projects, where we tried to be clever and decided to ignore the first normal form (1NF) to "simplify" our database.

Just to clarify, 1NF says:

Every field should contain a single value, no sets of values or nested records allowed.

In other words: "Don't put tables inside of tables." But, of course, we did just that—tucked a table into another and found ourselves in a mess of complications and headaches.

The story

Our journey commenced with the seemingly straightforward task of crafting a mechanism to store varied types of content – encompassing charts, custom HTML content, and checklists. The initial thought process nudged us toward the creation of a single table, structured as follows:

create table [dbo].[ContentSelection]
(
    [ContentPartSelectionID] int identity (1, 1) not null,
    [ConfigurationJSON] nvarchar(max) null,
    [ProfileTabID] int not null,
    [ContentType] int not null,
);

A singular majestic table, ContentSelection, was meant to graciously host various content types - charts, HTML blobs, or checklists, all neatly serialized and tucked into the ConfigurationJSON column. Oh, and a polite ContentType column to nudge us about what was packed inside each JSON, making deserialization ez thanks to .NET wizards like System.Text.Json and Newtonsoft.

Problem 1: Navigating the Puzzle of Configuration Updates

Oh, the joys of updating configurations! Especially when dealing with JSON, it turned out to be a notable quest in our database management journey. Even seemingly simple tasks, like tweaking a chart's Title attribute, uncovered some pretty significant hurdles embedded in this method.

Simple Title Update in code: A Walk in the Park

In the world of coding, this task seemed like a walk in the park. The steps of deserialization, executing the update, and saving the JSON again could be done in a few simple steps:

var data = JsonConvert.DeserializeObject<ChartConfiguration>(chart.ConfigurationJSON);
data.Title = "New Title";
chart.ConfigurationJSON = JsonConvert.SerializeObject(data);
// And the chart is saved!

This snippet of C# code allows developers to change the Title without diving deep into the entire JSON string. However, as the application goes, the code was all over the place, and this deserialization and serialization were done in many places. This is a code smell; we should have done it in one place. Sometimes, we just took the whole string and saved it as it is. I just trusted(hoped) that the client is sending the configuration in the correct state. Yeah, but that's a different story.

Simple but Not So Simple: The Database Update

Trying to update the configuration JSON directly within the database manually gave us a few options, each with its own set of complex puzzles:

Whole JSON String Update:

UPDATE [dbo].[ContentSelection] 
SET [ConfigurationJSON] = '{"Title": "New Title", "Type": "Chart", ...}'
WHERE [ContentPartSelectionID] = 1

Surprisingly, updating the entire JSON string, while seemingly straightforward, demands a meticulous understanding of the existing data structure to prevent any accidental data adventures (or misadventures).

Making Friends with SQL Server’s JSON_MODIFY Function:

UPDATE [dbo].[ContentSelection]
SET [ConfigurationJSON] = JSON_MODIFY([ConfigurationJSON], '$.Title', 'New Title')
WHERE [ContentPartSelectionID] = 1

The JSON_MODIFY function seemed like a neat and tidy update approach. Yet, it introduced a new set of complexities, particularly for those developers who might not be best buddies with SQL JSON manipulation functions.

HTML Property Challenges: An Additional Twist

And then, things got particularly interesting when dealing with properties that encapsulate entire HTML strings. Direct updates weren't quite in the cards due to the necessity of escaping quotes to keep our JSON string in good shape. Thus, what seems like a straightforward update morphs into a careful dance of ensuring every character is correctly escaped and validated, amplifying the possibilities for error and inefficiency in database management.

Problem 2: Leaping Over Initial Data Insertion Hurdles

Inaugurating a new production instance entailed inserting a wide variety of content—charts, checklists, and the like—into the ContentSelection table. What seemed like a straightforward task was, in reality, a hidden obstacle course.

The balance between Quantity vs. Quality

Inserting many rows into the ContentSelection table meant wrestling with large strings of JSON configurations. Each piece of content, whether a chart or checklist, demanded a unique, error-free JSON string to guarantee smooth sailing in functionality and display.

Example JSON:

{
  "Title": "Sample Chart",
  "Type": "Chart",
  "Configuration": {
    "Type": "Bar",
    "Data": {
      "Labels": ["January", "February", "March"],
      "Datasets": [{"Label": "Monthly Sales", "Data": [30, 25, 45]}]
    }
  }
}

Even the tiniest misstep, like a missing comma or mislabeled key, could introduce:

Data Integrity: A chance of mischievous JSON disrupting data retrieval or manipulation.
User Experience: The risk of misconfigurations causing a little chaos in content display or UI interactions.
Developer Efficiency: The potential time-drain of debugging and correcting JSON strings.

The Sneaky "What-If" of Mistakes

While seemingly trivial, an error in the JSON string can secretly trigger a chain reaction of operational disruptions, impacting developers and end-users alike. Though subtle, this issue beautifully underscores the crucial nature of precise data management and hints at the complex challenges that emerge when diverting from tried-and-true database normalization practices.

Problem 3: Data Retrieval

While seemingly simple, extracting data from the ContentSelection table unveiled its complexity in deserializing JSON strings. This complexity, particularly when handling larger objects like comprehensive dashboards requiring multiple content elements, swells even more in cloud environments like Azure, where every computational second counts—both in performance and pennies.

Problem 3.5 Search Operations: Not So Light on Serialized Columns

Embarking on search operations within serialized columns is not just a stroll in the tech park. Here we are, navigating through JSON strings, demanding not just a splash, but a veritable ocean of additional computational prowess—especially when side-eyed with the columnar searches in our ever-so-organized normalized database setup. And as those JSON objects swell in size and complexity, our search operations mutate, becoming an increasingly obstinate beast, voraciously consuming resources and casually nudging our end-users’ response times into the slow lane.

And nvarchar(max), oh what a whimsical challenge for standard SQL server full search – a perfect storm of complexity all bundled up with a neat little bow. Thus, the serialized columns sashay through, daring us to keep pace without tripping over the nuances of adept database management. May the odds be ever in our favor!

Problem 4: The Need for a Schema Update

We had multiple model classes within the source code with this comment.

// Careful with renaming any of the properties here!!! - will break existing content parts

That's it. That explains it all.

The Solution: A Nod to 1NF

To alleviate the problems mentioned above, we pivoted towards adhering to the First Normal Form (1NF). It entailed restructuring our database, primarily by creating distinct tables for each content type, thus eliminating the need for JSON serialization within the database.

-- Original table, omitting the JSON column
create table [dbo].[ContentSelection]
(
    [ContentPartSelectionID] int identity (1, 1) not null,
    [ProfileTabID] int not null,
    [ContentType] int not null,
);

-- Additional tables
create table [dbo].[ChartConfiguration]
(
    [ContentPartSelectionID] int not null,
    [Title] nvarchar(max) null,
    [ChartType] int not null, -- e.g., 1 = Bar, 2 = Line, 3 = Pie
    [Values] nvarchar(max) not null,
    [XName]  nvarchar(100) not null,
    [YName]  nvarchar(100) not null
);

create table [dbo].[CustomContentConfiguration]
(
    [ChecklistConfigurationID] int identity (1, 1) not null,
    [ContentPartSelectionID] int not null,
    [Title] nvarchar(max) null,
    [Html] nvarchar(max) null,
);
... -- you get the idea

While effectively eliminating the need for extensive JSON operations within SQL, this solution required a meticulous migration process, ensuring existing customer data was transferred accurately and securely to the new structure.

Navigating Through Data Migration

The transition demanded the crafting of migration scripts for each existing customer instance.

insert into ChartConfiguration(ContentPartSelectionID, Title, Values, Type, XName, YName)
select
    ContentPartSelectionID,
    Json_Value(ConfigurationJSON, '$.title'),      
    Json_Value(ConfigurationJSON, '$.values'),
    Json_Value(ConfigurationJSON, '$.ChartType'),
    Json_Value(ConfigurationJSON, '$.xName'),
    Json_Value(ConfigurationJSON, '$.yName')
from ContentSelection 
where ContentType = 1

Interestingly, this migration was multi-faceted and far from straightforward. For each content type, specific scripts were required. Moreover, each migration script must include checks to ensure data integrity, particularly validating JSON strings and managing instances where the Json_Value function misbehaved without apparent reason.

To safeguard against potential mishaps during the migration, the process was executed in two strategic phases:

Data Migration: Transfer data without altering the original structure.
Schema Update: Only after verifying the migrated data did we modify the schema, like deleting the JSON column.

This dual-phase approach provided a safety net, ensuring that if complications arose at any point, a revert to the previous database state was always within reach. While resource-intensive, this strategy underscored the importance of meticulous planning and safeguarding data during migration, especially when restructuring to adhere to normalization principles like 1NF.

Conclusion

This story concludes with a happy ending. We successfully migrated all our customers to the new structure and can now update the configuration of each content type without any problems. However, this story is not about the happy ending. It's about the issues we faced and how we solved them.

Take this story as a way to remind you to follow the best practices as much as possible. Even if you think you can do it better.

One last note

Yes, I called them problems, not "challenges" or "opportunities". Because they were problems.

From Converters to Dependency Injection: Navigating Model Migrations

Tran Manh Hung — Fri, 29 Sep 2023 14:47:50 +0000

Do you know the three-layer software design? Think of it as tech's equivalent of a sandwich with neatly stacked presentation, logic, and data layers. Now, why choose multiple models over one mammoth model? It's akin to organizing playlists by mood. Nifty, isn't it? In the coding realm, it's about being spick and span. Tiny model tweaks feel more like a brisk walk than a marathon.

But the real query is: how do we flit between models within these layers, especially when models diverge or beckon another repo or service?

Well, Examples Speak Louder

Keep It Simple

Suppose a Dog is set to evolve into a DogDto.

public class Dog
{
    public string Name { get; set; }
}

public class DogDto
{
    public string Name { get; set; }
}

Seems direct, right? Either use AutoMapper:

Dog dog = new Dog{ Name = "doge"};
DogDto dogDto = _mapper.Map<DogDto>(dog);

Or, take the traditional route:

Dog dog = new Dog{ Name = "doge"};
DogDto dogDto = new DogDto { Name = dog.Name };

Navigating Naming Nuisances

What if DogDto opts for a different nomenclature?

public class Dog
{
    public string Name { get; set; }
}

public class DogDto
{
    public string Naming { get; set; }
}

You've got two aces up your sleeve: use a FromXX/ToXX method or integrate a mapper profile. Here's option one:

public class DogDto
{
    public string Naming { get; set; }

    public static DogDto FromDog(Dog dog)
    {
        return new DogDto
        {
            Naming = dog.Name
        };
    }
}

And here you have how would mapper profile look like:

using AutoMapper;

public class UserProfile : Profile
{
    public UserProfile()
    {
        CreateMap<Dog, DogDto>()
            .ForMember(dest => dest.Naming, opt => opt.MapFrom(src => src.Name));
    }
}

var configuration = new MapperConfiguration(cfg =>
{
     cfg.AddProfile<UserProfile>();
});

When Models are Like Apples and Oranges

public class Dog
{
    public string Name { get; set; }
}

public class DogDto
{
    public int NumberOfLegs { get; set; }

    public Superpower SuperPower  { get; set; }
}

Time to roll up the sleeves! Converters are the knights in shining armor here:

public interface IConverter<In, Out>
{
    Out Convert(In input);
}

public class DogConverter : IConverter<Dog, DogDto>
{
    // Your conversion magic here!
}

Elevate Your Game: Services Within Converters

Ever bumped into a situation where your models are as different as, well, apples and oranges? And, to spice things up, you need to juggle an AnimalRepository or a FoodService within your converter. Tough spot, right?

Remember this code?

var converter = new DogConverter(_animalRepository, _foodService, _anotherService, _pleaseStopThisIsTooMuch, userId);

It might remind you of the infamous spaghetti mess. But fear not, there's a cleaner approach. Let me share a neat trick I've brewed up!

Step into the World of ConverterFactory

A ConverterFactory is like a genie granting your converter wishes.

public class ConverterFactory
{
    private readonly IServiceProvider _serviceProvider;

    public ConverterFactory(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }

    public IConverter<InType, OutType> GetConverter<InType, OutType>()
    {
        var converter = _serviceProvider.GetService(typeof(IConverter<InType, OutType>));
        if (converter == null)
        {
            throw new Exception("Missing converter alert!");
        }

        return (IConverter<InType, OutType>)converter;
    }
}

Boot Things Up in Startup.cs

Here's where we align our forces. Add your services to the service collection:

services.AddTransient<ConverterFactory>();
services.AddTransient<IConverter<Dog, DogDto>, DogConverter>();
services.AddTransient<IAnimalRepository, AnimalRepository>();
services.AddTransient<IFoodService, FoodService>();

Smooth Operations with DogHelper

With everything set, it's showtime:

public class DogHelper
{
    private readonly ConverterFactory _converterFactory;
    public DogHelper(ConverterFactory converterFactory)
    {
        _converterFactory = converterFactory;
    }

///...
    public DogDto TransformDog(Dog input)
    {
        var converter = _converterFactory.GetConverter<Dog, DogDto>();
        return converter.Convert(input);
    }
}

What's the magic? No more manually creating converter instances and wrestling with services. Dependency injection sweeps in, handling all the heavy lifting ensuring cleaner and more efficient code.

Wrapping Up: A Fresh Look at Tools and Tactics

Is Automapper Outdated? Let's Debate

Let me drop a bombshell: Could Automapper be sliding into obsolescence? I recently found myself locked in a spirited dialogue with a colleague about its continuing relevance. The crux of the debate? Automapper's Achilles' heel is its runtime error reporting. Get a property name or type conversion wrong, and you're signing up for bug city.

Sure, Automapper shone when replicating models that were virtually identical, especially those property-heavy behemoths we often see in enterprise settings. But let’s be real: Visual Studio's ultra-efficient auto-code completion has redefined the game, making that argument a little wobbly.

ConverterFactory: A Quick Fix, But Not a Cure-All

Time to tackle the not-so-hidden issue: If you find yourself leaning heavily on something like a ConverterFactory, coupled with dependency injection, it might be time to sniff out potential architectural odors. Could it be a red flag suggesting you revisit your system’s blueprints?

The Final Takeaway

So, there we are! Whether you're nodding along or vigorously shaking your head, my hope is that this exploration has sparked some intellectual kindling. Got a different approach? Differing opinions? Lay it on me. Let's remember that achieving perfection is less a destination and more an ever-evolving journey. There's always room for development and refinement in the ever-changing tech landscape. So go ahead, share your insights—I'm more than ready for a good round to disscuss!

The Hidden Costs of Misusing Scheduled Jobs and Messaging Systems

Tran Manh Hung — Mon, 28 Aug 2023 10:21:15 +0000

It's a common scenario we've all faced: you've got a table and a scheduled job designed to process this table.

Below is a simplified example of what such a script might look like:

-- Declare a variable to store the ID of the row to be processed
DECLARE @rowID INT

-- Get the first row from the table to process
SELECT TOP 1 @rowID = ID
FROM TableToProcess
ORDER BY ID ASC

-- Check if a row was found
IF @rowID IS NOT NULL
BEGIN
    -- Perform processing on the selected row (You can put your processing logic here)
    -- For now, we'll add a comment to indicate where the processing happens

    -- Delete the processed row from the table
    DELETE FROM TableToProcess WHERE ID = @rowID
END

But what happens when there's no new data to process? Without any contingency, the script will repeatedly hammer your database with fruitless calls, generating redundant traffic and potentially impacting the performance of your entire system.

Now, don't get me wrong. Scheduled jobs are not the enemy. They have a critical role in certain situations, such as scheduling regular email alerts. However, as developers, we sometimes fall into the trap of over-reliance on this tool, leading to unnecessary overhead within our systems.

So, is there a better, more efficient alternative to deal with these situations? Welcome to the realm of messaging systems.

So, What's a Messaging System?

In essence, a messaging system provides a reliable way to exchange information (in the form of messages) between applications, systems, or services. The main idea here is to enable communication between different components without them necessarily knowing about each other.

In a messaging system, producers create messages and put them onto the system. Consumers get those messages and do something with them. These systems are crucial for enabling asynchronous processing, meaning that your components don't have to wait around for other tasks to finish. This can significantly enhance performance, scalability, and reliability.

Message Flow vs Scheduled Task

Advantages

Real-time Processing: Messages are processed as they arrive, leading to faster responses.
Decoupling of Processes: Allows systems to be developed, upgraded, and scaled independently.
Improved Scalability: Messaging systems can more easily scale to handle larger loads.
Reduced Database Load: By processing data as it comes in, constant database querying can be reduced.
Resilience: Messaging systems can handle failures without losing data.

Disadvantages

Complexity: Messaging systems come with their own complexities that require more advanced understanding and maintenance.
Handling Failures: Although resilient, handling failures, "poison messages," and ensuring message ordering can be challenging.
Infrastructure Requirements: Establishing and maintaining a robust messaging system might require significant resources and expertise.

Popular Messaging System Implementations

Now that you've got a taste of a messaging system let's dive into some popular implementations: Azure Service Bus, Kafka, Azure Queue System, and RabbitMQ.

Azure Service Bus

Azure Service Bus is a fully managed service from Microsoft Azure that supports queue and topic, messaging models. It's robust, provides guaranteed message delivery, and maintains the order of messages. Here's an example of sending a message with Azure Service Bus in C#:

ServiceBusClient client = new ServiceBusClient("<connection_string>");
ServiceBusSender sender = client.CreateSender("<queue_name>");

ServiceBusMessage message = new ServiceBusMessage("Hello, World!");

await sender.SendMessageAsync(message);

Console.WriteLine($"Sent a single message to the queue: {sender.EntityPath}");

And here is how would consumer look like

string connectionString = "<connection_string>";
string queueName = "<queue_name>";

await using (ServiceBusClient client = new ServiceBusClient(connectionString))
{
    ServiceBusProcessor processor = client.CreateProcessor(queueName, new ServiceBusProcessorOptions());

    processor.ProcessMessageAsync += async args =>
    {
        string body = args.Message.Body.ToString();
        Console.WriteLine($"Received message: {body}");
        await args.CompleteMessageAsync(args.Message);
    };

    processor.ProcessErrorAsync += args =>
    {
        Console.WriteLine($"Error occurred: {args.Exception}");
        return Task.CompletedTask;
    };

    await processor.StartProcessingAsync();

    Console.WriteLine("Press any key to stop receiving messages...");
    Console.ReadKey();

    await processor.StopProcessingAsync();

And if you start using Azure function the implementation if even shorter and simple!

[FunctionName("ServiceBusConsumer")]
public static async Task Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_string>")] string messageBody,
    ILogger log)
{
    log.LogInformation($"Received message: {messageBody}");

    // Process the message (you can replace this with your custom logic)

    // Note: Unlike the previous examples, the message is automatically marked as completed (removed from the queue) by the Function after successful processing.
}

Azure Queue System

Azure Queue System is another Microsoft offering specifically for storing large numbers of messages that may be accessed from anywhere via authenticated calls. It's simpler than Azure Service Bus and perfect for light workloads. An example of sending a message with Azure Queue in C# looks like this:

QueueClient queueClient = new QueueClient("<connection_string>", "<queue_name>");
string message = "Hello, World!";
await queueClient.SendMessageAsync(message);

Kafka

Apache Kafka, an open-source system, is built to handle real-time data feeds with high throughput and low-latency. Kafka operates in a distributed manner and can handle massive amounts of data. Here's a simple example of producing a message with Kafka using Java:

Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
props.put("key.serializer", "org.apache.kafka.common.serialization.StringSerializer");
props.put("value.serializer", "org.apache.kafka.common.serialization.StringSerializer");

Producer<String, String> producer = new KafkaProducer<>(props);
ProducerRecord<String, String> record = new ProducerRecord<>("test", "Hello, World!");

producer.send(record);
producer.close();

RabbitMQ

RabbitMQ is another open-source messaging system known for its robustness. It supports multiple messaging protocols, message queuing, delivery acknowledgment, flexible queue routing, and more. Here's a Python example of sending a message with RabbitMQ:

import pika

connection = pika.BlockingConnection(pika.ConnectionParameters('localhost'))
channel = connection.channel()

channel.queue_declare(queue='hello')

channel.basic_publish(exchange='', routing_key='hello', body='Hello, World!')

print(" [x] Sent 'Hello, World!'")
connection.close()

Conclusion

There you have it. Keep your system from getting bogged down by an overload of scheduled tasks. Give messaging systems a try and watch your application's performance and scalability reach new heights. Whether you go for a fully managed service like Azure Service Bus or Azure Queue System or an open-source option like Kafka or RabbitMQ, you'll reap the benefits of reliable, scalable, and high-performance messaging.

A Breezy Guide to Implementing SAML2 Authentication with JWT in .NET WebAPI using Sustainsys

Tran Manh Hung — Tue, 15 Aug 2023 20:06:07 +0000

Did you pull a new assignment to sprinkle SAML2 magic on your .NET WebAPI using JWT with a free library? Well, your search ends here, fellow coder! By the end of this guide, you'll be equipped with a production-ready solution and glean insights into how to extend it and construct a truly enterprise-grade authentication system.

My inspiration for this guide draws heavily from this stackoverflow thread that offers a great example.

Gearing Up:

Prerequisites

Before we delve into the thick of things, it would be beneficial to have:

A basic understanding of .NET Core and C# programming. (This article by Jason Watmore is a gem!)
Some degree of familiarity with SAML2.

But fret not. Armed with the examples provided here, you'll manage to put together a working solution.

Visualizing the Flow

Before we embark, let's visualize how our app's authentication flow transforms with and without SAML.

Here is really simplified sequence diagram of how basic authentication looks like:

And now with SAML2:

Step 1: Loading Up the Necessary Packages

First off, we need to install the necessary NuGet packages for Sustainsys, JWT, and other supporting libraries. Head to the Package Manager Console and run these commands:

Install-Package Sustainsys.Saml2.AspNetCore2
Install-Package Microsoft.AspNetCore.Authentication.JwtBearer
Install-Package System.IdentityModel.Tokens.Jwt

Step 1.1: Certificates 101

SAML authentication protocol mandates certificate management, primarily used for signing and encrypting SAML assertions. Here's a brief rundown on how to handle these certificates.

For our demo, we'll use the certificate from https://stubidp.sustainsys.com/Certificate

Here's how you'd use a .pfx file:

public static X509Certificate2 GetCertificate()
{
    X509Certificate2 certificate = new X509Certificate2(@"path/to/your/certificate.pfx", certificatePassword);
}

Step 2: Configuring SAML2 & JWT Authentication

Fantastic! Now, we'll couple SAML2 authentication with Sustainsys and set up JWT authentication in our .NET WebAPI application. Open your Startup.cs file (or Program.cs, based on your configs) and add these configurations:

JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
services
    .AddAuthentication(options =>
    {
        options.DefaultScheme = "AppScheme";
        options.DefaultSignInScheme = "AppExternalScheme"; // If you didn't have add default scheme
        options.DefaultSignOutScheme = "AppExternalScheme"; // If you didn't have add default scheme
    })
    .AddCookie("AppExternalScheme") // If you didn't have add this
    .AddJwtBearer("AppScheme", options => ...);

services
    .AddAuthentication()
    // AddSaml2 must always be after AddAuthentication
    .AddSaml2(sharedOptions =>
    {
        string siteAddress = "https://your.application.example.com/" // take note!
        sharedOptions.SPOptions.EntityId = new EntityId(siteAddress); 
        sharedOptions.SPOptions.ServiceCertificates.Add(serviceCertificate);
        sharedOptions.SPOptions.AuthenticateRequestSigningBehavior = SigningBehavior.Always;
        sharedOptions.SPOptions.WantAssertionsSigned = true;

        RegisterIdentityProvider(sharedOptions, siteAddress, selectedIdentityProvider);
    });

    // Register a single identity provider
    void RegisterIdentityProvider(Saml2Options sharedOptions, string siteAddress, IdentityProviderCustomClass identityProvider)
    {
        var ip = new IdentityProvider(
            new EntityId(identityProvider.MetadataId), sharedOptions.SPOptions)
        {
            MetadataLocation = identityProvider.MetadataLocation, // example: https://stubidp.sustainsys.com/metadata
            LoadMetadata = true,
            DisableOutboundLogoutRequests = false,
            AllowUnsolicitedAuthnResponse = identityProvider.AllowUnsolicitedAuthResponse,
        };


        X509Certificate2 customerSsoCertificate = GetCertificate();
        ip.SigningKeys.AddConfiguredKey(customerSsoCertificate);

        //Finally, add identity provider to the app
        sharedOptions.IdentityProviders.Add(ip);
    }

Step 3: Crafting New Controller Endpoints

/// <summary>
/// Redirects the user to the SAML authentication provider (SSO)
/// </summary>
/// <param name="returnUrl">URL to which the user should return post successful authentication.</param>
[HttpGet("saml/redirect")]
public async Task<ActionResult> SamlRedirectSaml(string returnUrl)
{
    return new ChallengeResult(
        Saml2Defaults.Scheme,
        new AuthenticationProperties
        {
            RedirectUri = Url.Action(nameof(SamlLoginCallback), new { returnUrlOrError.Value.Url }),
            IsPersistent = true
        });
}

/// <summary>
/// Logs the user in (SSO).
/// </summary>
/// <param name="url">URL to which the user should return post successful authentication.</param>
[HttpGet("saml/login")]
public async Task<ActionResult> SamlLoginCallback(string url)
{
    // Use .AuthenticateAsync to verify if user authentication was successful
    AuthenticateResult authenticateResult = await HttpContext.AuthenticateAsync("AppExternalScheme");
    if (!authenticateResult.Succeeded)
    {
        return await Problem(statusCode: StatusCodes.Status401Unauthorized);
    }

    // Use claims to identify authenticated user 
    Collection<Claim> claimCollection = authenticateResult?.Principal?.Claims;
    if (claimCollection.Count == 0) // No claims specified
    {
        return await Problem(statusCode: StatusCodes.Status400BadRequest);
    }

    // You can use ClaimTypes instead of long string like 
    // Always refer to the identity provider documentation of your choice to match the correct claims with your app
    string? userName = claimCollection.FirstOrDefault(c => c.Name.Equals(ClaimTypes.NameIdentifier, StringComparison.OrdinalIgnoreCase)).Value;    
    Maybe<UserSecurityData> existingUser = await _userService.GetUser(userName);
    if (existingUser.HasNoValue) // User doesn't exist 
    {
        // Optional: Auto-create a user account if none exists
        Result<User> autoCreatedUser = await _userService.AutoCreateAccount(userNameOrError.Value, claimCollection);
        if (autoCreatedUser.IsFailure)
        { 
            return await Problem(statusCode: StatusCodes.Status401Unauthorized);
        }

        // Log in user as you normally would
        await LogInSsoUser(autoCreatedUser.Value.Id);
    }
    else
    {
        // Log in user as you normally would
        await LogInSsoUser(existingUser.Value.Id);
    }

    // Redirect user to the original address
    return Redirect(url);
}

Unveiling the Hidden Treasures

This section'll explore a few more tips to enhance your solution.

Tap into Azure Key Vault

Did you know there's a savvy way to manage your certificates? Azure Key Vault is your secret weapon among Microsoft Azure's cloud-based services. Think of it as a secure digital chest where you can safely stash your cryptographic keys, certificates, secrets, and connection strings used by your cloud apps and services. Rather than spreading them throughout your application code or configuration files, Azure Key Vault offers centralized, safe, and scalable storage.

To give you an idea, here's a snapshot of how you can utilize Azure Key Vault:

public static X509Certificate2 GetCertificate()
{
    DefaultAzureCredential azureCredentials = new DefaultAzureCredential();
    CertificateClient client = new CertificateClient(new Uri($"https://{VaultName}.vault.azure.net/"), azureCredentials);

    Azure.Response<X509Certificate2> certificate = client.DownloadCertificate("CertificateName");

    return certificate.Value;
}

Juggling Multiple Identity Providers

Imagine handling multiple identity providers, such as Azure AD and OKTA. No problem at all! A few modifications to our existing solution, and you're all set.

Firstly, let's revisit our existing code and integrate some additional lines. We'll begin with the registration:

services
    .AddAuthentication()
    // AddSaml2 must always follow AddAuthentication
    .AddSaml2(sharedOptions =>
    {
        string siteAddress = "https://your.application.example.com/" // be careful here
        sharedOptions.SPOptions.EntityId = new EntityId(siteAddress); 
        sharedOptions.SPOptions.ServiceCertificates.Add(serviceCertificate);
        sharedOptions.SPOptions.AuthenticateRequestSigningBehavior = SigningBehavior.Always;
        sharedOptions.SPOptions.WantAssertionsSigned = true;

        // NEW - Here's where we register multiple identity providers
        foreach(IdentityProviderCustomClass selectedIdentityProvider in multipleIdentityProviders)
        {
            RegisterIdentityProvider(sharedOptions, siteAddress, selectedIdentityProvider);
        }

    });

Then, let's add some flavors to the saml/redirect endpoint by incorporating identity provider selection logic.

[HttpGet("saml/redirect")]
public async Task<ActionResult> SamlRedirect(string returnUrl, string entity)
{
    var properties = new AuthenticationProperties
    {
        RedirectUri = Url.Action(nameof(SamlLoginCallback), new { returnUrlOrError.Value.Url }),
        IsPersistent = true
    };

    properties.Items.Add("idp", new EntityId(entity).Id) // NEW - This line is crucial. It explicitly defines the identity provider to use.

    return new ChallengeResult(Saml2Defaults.Scheme, properties);
}

A User-Friendly Approach to Error Handling

When directing users to multiple websites, the traditional error messaging approach between the Front-End (FE) and the API can fall short. However, you can handle this user-friendly by designing a cshtml view on the API end to display error messages.

Let's look at an example. Start by creating Error.cshtml and ErrorModel.cs files:

@page
@model ErrorModel
@{
    Layout = null;
}

<!DOCTYPE html>
<html>
<head>
    <title>Oops, Something Went Wrong!</title>
</head>
<body>
    <h1>Error</h1>
    <p>@Model.ErrorMessage</p>
</body>
</html>

using Microsoft.AspNetCore.Mvc.RazorPages;

public class ErrorModel : PageModel
{
    public string ErrorMessage { get; set; }

    public void OnGet(string message)
    {
        ErrorMessage = message;
    }
}

Next, integrate this into your controller. Here's how it would look with some pre-existing code:


[HttpGet("saml/login")]
public async Task<ActionResult> SamlLoginCallback(string url)
{
    AuthenticateResult authenticateResult = await HttpContext.AuthenticateAsync("AppExternalScheme");
    if (!authenticateResult.Succeeded)
    {
        ViewResult view = View("Error", new ErrorModel{ ErrorMessage = "Authentication failure!"});
        view.StatusCode = StatusCodes.Status401Unauthorized;

        return view;
    }
...

Simplifying Claims Processing With a Helper Class

Claims are generally used to identify an authenticated user. You might want to consider creating a helper class to make your code easier to understand and maintain.

 public class ClaimCollection : Collection<Claim>
{
    // Constructors...
    // ...

    public Result<UserName> GetUserName() => this.FirstOrDefault(c => c.Type.Equals(ClaimTypes.NameIdentifier, StringComparison.OrdinalIgnoreCase)));

    public Result<Email> GetEmail() => this.FirstOrDefault(c => c.Type.Equals(ClaimTypes.Email, StringComparison.OrdinalIgnoreCase));

// Add other claims as needed...

The Importance of Logging

If you've ever been caught up in a SAML2 flow issue, you'd know how challenging it can be to identify the problem. Was it an error in the Identity Provider (IdP) configuration? Or was there a bug within your code? For this reason, it's crucial to incorporate a logging system into your application's communication with the identity provider.

The sustainsys library handles this aspect and allows for the injection of a logger. In the following example, we've used the pre-defined AspNetCoreLoggerAdapter, which employs the standard Microsoft.Extensions.Logging class.

services
    .AddAuthentication()
    .AddSaml2(sharedOptions =>
    {
        string siteAddress = "https://your.application.example.com/" // remember this!
        sharedOptions.SPOptions.EntityId = new EntityId(siteAddress); 
        sharedOptions.SPOptions.ServiceCertificates.Add(serviceCertificate);
        sharedOptions.SPOptions.AuthenticateRequestSigningBehavior = SigningBehavior.Always;
        sharedOptions.SPOptions.WantAssertionsSigned = true;
        sharedOptions.SPOptions.Logger = new AspNetCoreLoggerAdapter(logger)  // Here's where you add the logger

...

The Charm of User-Password Authentication with SAML2

What's so special about SAML2 in .NET? With SAML2, you no longer need to implement user-password authentication separately. SAML2 seamlessly integrates into your authentication processes, allowing you to maintain your existing authentication endpoints. It handles the Single Sign-On (SSO) flow, so users can log in once and access multiple applications without having to repeatedly enter their credentials.

Final Thoughts

Voila! You've now become part of the elite club capable of integrating SAML2 into their .NET applications. Recognizing the potential for research headaches, I decided to put together this comprehensive guide. But don't rest on your laurels. This is just the starting point, and there's a whole universe to explore beyond. However, with this demo, you've already hit the ground running.

If you've discovered an even better solution, please share! We're all in this learning journey together. Also, a hearty shoutout to the talented team behind the Sustainsys library. Keep the coding spirit alive. Happy coding!

DEV Community: Tran Manh Hung

Wolverine + Marten: My story and subjective take

Introduction

The Traditional .NET Web API Way

What Are Wolverine and Marten?

The Half-Baked Approach (Don't Do This)

Embrace the Full Stack

1. Aggregate-Driven Design

2. Command Handlers That Work With Aggregates

3. Event-Driven Projections

The Transformation Results

Code Volume Reduction

Ok so main points

1. Start Small

2. Invest in Learning

3. Embrace Events

4. Use Projections Wisely

5. PostgreSQL over SQL Server

Sample Project Structure

My take

Summary

Implementing LDAP Authentication in .NET Web API Apps

What is LDAP?

Different types of LDAP

Basic Authentication Flow with LDAP in .NET

Login Flow

Required NuGet Packages

Implementation in Code

1. Setting Up the Login Endpoint

2. Implementing LDAP Authentication Service

3. Retrieving User Information and Roles

4. JWT Token Generation Service

5. Completing the Login Endpoint

6. Configuring JWT Authentication

7. Implementing Refresh Token Functionality

Using Protected Resources

Conclusion

Understanding OAuth/OpenID Response Types in .NET Web APIs

Understanding Response Types: The Basics

1. Query Response Type (response_type=code)

2. Fragment Response Type (response_type=token or response_type=id_token token)

3. Post Response Type (response_mode=form_post)

Implementing Response Types in .NET Web APIs

Setting Up Dependencies

1. Query Response Type (Authorization Code Flow)

2. Fragment Response Type (Implicit Flow)

3. Post Response Type (Form Post Response Mode)

When to Use Each Response Type

1. Query Response Type (Authorization Code Flow)

2. Fragment Response Type (Implicit Flow)

3. Post Response Type (Form Post Response Mode)

Security Concerns and Mitigations

Query Response Type

Fragment Response Type

Post Response Type

Best Practices

1. Secure Cookie Handling

2. Implement Proper Token Validation

3. Use Authorization Code Flow with PKCE for All Clients

4. Implement Proper Error Handling

5. Implement Rate Limiting

Conclusion: Choosing Your Authentication Path

Additional Resources

Story of how a developer without game dev experience tries to create a game

Merging Startup.cs and Program.cs in .NET 8: A Simplified Approach

Why Merge Startup.cs and Program.cs?

Advantages

Potential Pitfalls

The Old Way: Separate Startup.cs and Program.cs

Original Program.cs

Original Startup.cs

The New Combined Mode

Combined Program.cs

Key Points in the Combined File

Our Experience and story

Conclusion

Database Normalization: A Simple Tale of Ignoring 1NF

Database Normalization in a Nutshell

Bypassing 1NF: A Shortcut Gone Wrong

The story

1. Query Response Type (`response_type=code`)

2. Fragment Response Type (`response_type=token` or `response_type=id_token token`)

3. Post Response Type (`response_mode=form_post`)