Every article in this series has described building a BFF on a greenfield system — a clean slate where the architecture is decided upfront and the frontend and BFF are developed in parallel. That is not the situation most engineers face. Most engineers face an existing frontend that talks directly to an existing API, accumulated over years, with real users depending on it every day.

The Strangler Fig pattern is the answer for this situation. Named by Martin Fowler after a species of tree that grows around an existing structure and gradually replaces it, the pattern describes a migration strategy where the new system is built incrementally alongside the old one. Traffic is moved piece by piece — one endpoint at a time, one screen at a time — until the old system is no longer needed and can be removed. At no point is there a cutover where everything changes simultaneously. At no point are users exposed to an untested replacement of the entire system.

This article covers how to apply the Strangler Fig pattern specifically to BFF adoption: how to introduce the BFF as a routing layer in front of an existing API, how to migrate endpoints incrementally, how to manage the coexistence period without duplicating logic, and how to know when the migration is complete and the old API can be retired.

The starting point: what brownfield looks like

Before the migration begins, a typical brownfield architecture looks like this:

The Vue application makes direct HTTP calls to the existing API. The existing API was not designed with the frontend's needs in mind — it exposes domain entities rather than screen-oriented responses, it handles authentication in a way that predates modern security practices, and its response shapes have accumulated inconsistencies over years of development.

The problems this causes are the same ones Article 1 described: overfetching, underfetching, adapter logic in the frontend, and no clean place to add cross-cutting concerns like session management or response caching. The question is how to introduce a BFF to solve these problems without rewriting the entire system or breaking the existing users while doing so.

The Strangler Fig approach, applied

The migration proceeds in four stages. Each stage is independently deployable and leaves the system in a working state. There is no stage that must be completed before users can continue using the application.

The key architectural enabler is that the BFF starts as a pass-through proxy. In Stage 1, every request from the Vue application goes to the BFF, which forwards it to the existing API without modification. No functionality changes. No user-visible behaviour changes. The BFF is in the path but does nothing yet. This is the foundation that makes every subsequent stage safe.

Stage 1: The transparent proxy

The first deployment of the BFF does not aggregate, shape, or transform anything. It proxies every request to the existing API verbatim. The purpose of this stage is to establish the BFF in the request path, validate that it can handle the traffic without introducing latency or errors, and give the team confidence in the deployment and monitoring setup before any migration work begins.

The YARP reverse proxy

.NET has a first-class reverse proxy library — YARP (Yet Another Reverse Proxy) — that makes the transparent proxy stage straightforward to implement:

dotnet add package Yarp.ReverseProxy

// Program.cs — Stage 1: transparent proxy
var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

// Observability — even in proxy mode, every request should be traced
builder.Host.UseSerilog((ctx, cfg) => cfg
    .ReadFrom.Configuration(ctx.Configuration)
    .Enrich.FromLogContext()
    .Enrich.WithProperty("Service", "bff")
    .WriteTo.Console()
    .WriteTo.ApplicationInsights(
        ctx.Configuration["ApplicationInsights:ConnectionString"],
        TelemetryConverter.Traces));

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

app.UseMiddleware<CorrelationIdMiddleware>();
app.UseSerilogRequestLogging();

// All traffic proxied to existing API
app.MapReverseProxy();

app.Run();

The YARP configuration in appsettings.json:

{
  "ReverseProxy": {
    "Routes": {
      "catch-all": {
        "ClusterId": "existing-api",
        "Match": {
          "Path": "{**catch-all}"
        }
      }
    },
    "Clusters": {
      "existing-api": {
        "Destinations": {
          "primary": {
            "Address": "https://api.existingplatform.no"
          }
        },
        "HealthCheck": {
          "Active": {
            "Enabled": true,
            "Interval": "00:00:30",
            "Timeout": "00:00:05",
            "Path": "/health"
          }
        }
      }
    }
  }
}

The Vue application's API base URL is changed from https://api.existingplatform.no to https://bff.existingplatform.no. Everything else stays the same. The BFF forwards every request to the existing API and returns the response unchanged.

What to validate in Stage 1

Before proceeding to Stage 2, validate three things:

Latency. The BFF adds one network hop. In Application Insights, compare the p95 latency of the same endpoints before and after the BFF was introduced. The acceptable overhead is typically under 10ms for same-region deployments. More than that indicates a deployment topology or network configuration issue that must be resolved before migration work begins — latency introduced by the proxy will compound with latency introduced by aggregation logic.

Error rate. The error rate for all endpoints should be identical before and after the BFF introduction. Any increase in 4xx or 5xx rates is a bug in the proxy configuration.

Authentication passthrough. If the existing API uses authentication (bearer tokens, cookies, API keys), verify that the BFF passes the credentials through correctly. YARP preserves request headers by default, but verify this with an authenticated endpoint before proceeding.

Stage 1 can run for days or weeks before Stage 2 begins. There is no urgency to migrate — the system is working, users are unaffected, and the team is learning how the traffic actually looks before beginning to intercept it.

Stage 2: Incremental endpoint migration

With the BFF in the path and validated as transparent, the migration begins. The approach: introduce BFF-handled routes alongside the YARP catch-all, using specificity to determine which requests the BFF handles and which it forwards.

The routing strategy

YARP and Minimal API routes coexist in the same application. The critical insight is that ASP.NET Core's routing matches the most specific route first. A BFF-handled route for GET /api/dashboard takes precedence over the YARP catch-all for {**catch-all}. Routes that have not been migrated yet continue to be proxied.

// Program.cs — Stage 2: BFF routes coexist with catch-all proxy

// Register BFF services
builder.Services.AddHttpClient<ExistingApiClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["ExistingApi:BaseUrl"]!));
builder.Services.AddScoped<DashboardAggregator>();

// ... other BFF registrations ...

var app = builder.Build();

// BFF middleware
app.UseMiddleware<CorrelationIdMiddleware>();
app.UseSerilogRequestLogging();
app.UseAuthentication();
app.UseAuthorization();

// Migrated BFF endpoints — registered BEFORE the catch-all proxy
app.MapDashboardEndpoints();   // Handles GET /api/dashboard
app.MapCourseEndpoints();      // Handles GET /api/courses/{id}

// Catch-all: everything not yet migrated goes to the existing API
app.MapReverseProxy();

app.Run();

This routing structure means:

• GET /api/dashboard → handled by the BFF's DashboardAggregator

• GET /api/courses/c-1 → handled by the BFF's CourseAggregator

• GET /api/users/profile → forwarded to the existing API (not yet migrated)

• POST /api/enrollments → forwarded to the existing API (not yet migrated)

The Vue application makes the same requests to the same BFF base URL. Whether a given request is handled by the BFF or forwarded to the existing API is invisible to the client.

The migration wrapper: using the existing API as an upstream

During the migration, the BFF's aggregators call the existing API as their upstream. This is identical to how Article 4's aggregators call domain microservices — the existing API is just another upstream. An ExistingApiClient typed client replaces the individual service clients where the upstream has not yet been decomposed:

// Clients/ExistingApiClient.cs
public sealed class ExistingApiClient(
    HttpClient http,
    IHttpContextAccessor contextAccessor,
    ILogger<ExistingApiClient> logger)
{
    // Forward the caller's auth token — the existing API validates it
    private void AttachAuth(HttpRequestMessage request)
    {
        var authHeader = contextAccessor.HttpContext?
            .Request.Headers.Authorization.FirstOrDefault();
        if (authHeader is not null)
            request.Headers.TryAddWithoutValidation("Authorization", authHeader);
    }

    public async Task<JsonElement?> GetAsync(
        string path, CancellationToken ct = default)
    {
        var request = new HttpRequestMessage(HttpMethod.Get, path);
        AttachAuth(request);
        try
        {
            var response = await http.SendAsync(request, ct);
            response.EnsureSuccessStatusCode();
            return await response.Content.ReadFromJsonAsync<JsonElement>(ct);
        }
        catch (HttpRequestException ex)
        {
            logger.LogWarning(ex,
                "Existing API unavailable. Path: {Path}. Status: {Status}",
                path, ex.StatusCode);
            return null;
        }
    }
}

Using JsonElement rather than a typed DTO is intentional for migration work. The existing API's response shapes are already known by the Vue application — the initial goal of the BFF aggregator during migration is not to redesign the shape but to compose multiple calls and introduce the architectural boundary. Shape refinement comes after the boundary is established.

A migration-phase aggregator

During migration, the dashboard aggregator composes calls to the existing API, performing the aggregation the Vue application previously performed on the client:

// Aggregators/DashboardAggregator.cs — migration phase
public sealed class DashboardAggregator(
    ExistingApiClient existingApi,
    ILogger<DashboardAggregator> logger)
{
    public async Task<DashboardResponse> AggregateAsync(
        string userId, CancellationToken ct = default)
    {
        var partialFailures = new List<string>();

        // These were previously four separate fetch calls in the Vue application.
        // The BFF now makes them in parallel and returns a single response.
        var profileTask      = existingApi.GetAsync($"/users/{userId}/profile", ct);
        var notificationTask = existingApi.GetAsync($"/notifications/unread?userId={userId}", ct);

        await Task.WhenAll(profileTask, notificationTask);

        var profile = profileTask.Result;
        if (profile is null)
            throw new BffAggregationException("User profile unavailable.");

        var orgId   = profile.Value.GetProperty("organisationId").GetString();
        var courses  = await existingApi.GetAsync($"/courses?orgId={orgId}", ct);
        if (courses is null) partialFailures.Add("courses");

        JsonElement? sessions = null;
        if (courses.HasValue)
        {
            var courseIds = courses.Value
                .EnumerateArray()
                .Select(c => c.GetProperty("id").GetString())
                .Where(id => id is not null)
                .Take(10)
                .ToArray();

            sessions = await existingApi.GetAsync(
                $"/sessions?courseIds={string.Join(",", courseIds)}&limit=3", ct);
            if (sessions is null) partialFailures.Add("sessions");
        }

        // Shape the response — this is where the BFF adds value over the raw proxy
        return new DashboardResponse(
            User: ShapeProfile(profile.Value),
            Courses: ShapeCourses(courses),
            UpcomingSessions: ShapeSessions(sessions),
            Notifications: ShapeNotifications(notificationTask.Result),
            PartialFailures: partialFailures
        );
    }

    private static UserProfileResponse ShapeProfile(JsonElement profile) => new(
        DisplayName: $"{profile.GetProperty("firstName").GetString()} " +
                     $"{profile.GetProperty("lastName").GetString()}",
        Role: TranslateRole(profile.GetProperty("roleCode").GetString()),
        AvatarUrl: profile.TryGetProperty("avatarPath", out var avatar)
            ? $"/media/avatars/{avatar.GetString()}"
            : null
    );

    // ... additional shape methods ...
}

The JsonElement approach is verbose but honest about what is happening: the BFF is parsing a response designed for a different consumer and reshaping it. Once the migration is complete and the existing API is replaced by proper upstream services, these JsonElement navigations are replaced by typed DTO deserialisations. Using JsonElement during migration makes the interim state explicit rather than hiding it behind premature typed models that may need to change.

Managing the coexistence period

The coexistence period — where some endpoints are handled by the BFF and others are still proxied — is the riskiest phase of the migration. Three practices keep it manageable.

Track migration state explicitly

Maintain a migration status document as part of the repository. It should be updated with every pull request that migrates or retires an endpoint:

<!-- docs/bff-migration-status.md -->
# BFF Migration Status

Last updated: 2025-04-10

## Migrated endpoints (handled by BFF)
| Endpoint                  | Migrated  | Notes                                  |
|---------------------------|-----------|----------------------------------------|
| GET /api/dashboard        | 2025-03-01| Aggregates profile, courses, sessions  |
| GET /api/courses/{id}     | 2025-03-15| Includes enrollment status             |
| GET /api/auth/me          | 2025-03-22| Feide session replaces JWT             |

## Proxied endpoints (still forwarded to existing API)
| Endpoint                  | Owner     | Target migration date                  |
|---------------------------|-----------|----------------------------------------|
| GET /api/users/profile    | Auth team | 2025-04-20                             |
| POST /api/enrollments     | Course team| 2025-04-27 — needs idempotency keys   |
| GET /api/sessions/{id}    | Schedule  | 2025-05-05                             |

## Retired endpoints (no longer in use)
| Endpoint                  | Retired   | Replacement                            |
|---------------------------|-----------|----------------------------------------|
| GET /api/home             | 2025-03-01| GET /api/dashboard                     |

This document is the migration's source of truth. It prevents the common failure mode where the migration stalls because no one can remember which endpoints have been migrated and which are still proxied.

Dual-mode testing

During the coexistence period, integration tests must cover both proxied and BFF-handled paths. A test that only hits the BFF-handled endpoints will miss regressions introduced by YARP configuration changes that affect the proxied endpoints:

// EducationPlatform.Bff.IntegrationTests/Migration/ProxyBehaviourTests.cs
public class ProxyBehaviourTests(BffWebApplicationFactory factory)
    : IClassFixture<BffWebApplicationFactory>
{
    [Fact]
    public async Task ProxiedEndpoint_ForwardsToExistingApi_WithAuthHeader()
    {
        // Arrange — existing API stub returns a known response
        factory.ExistingApiServer.Given(
            Request.Create()
                .WithPath("/users/profile")
                .WithHeader("Authorization", "Bearer test-token")
                .UsingGet())
            .RespondWith(
                Response.Create()
                    .WithStatusCode(200)
                    .WithBodyAsJson(new { firstName = "Ingrid", lastName = "Solberg" }));

        var client = factory.CreateClient();
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "test-token");

        // Act — this endpoint is not yet migrated, should proxy
        var response = await client.GetAsync("/users/profile");

        // Assert
        response.StatusCode.Should().Be(HttpStatusCode.OK);
        factory.ExistingApiServer.LogEntries.Should().Contain(entry =>
            entry.RequestMessage.Path == "/users/profile");
    }

    [Fact]
    public async Task MigratedEndpoint_HandledByBff_DoesNotCallExistingApi()
    {
        // Arrange
        factory.UserClient
            .GetProfileAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(new UserProfileDto("Ingrid", "Solberg", "uninett", "TEACHER", null));
        factory.NotificationClient
            .GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(0);
        factory.CourseClient
            .GetCoursesByOrgAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns([]);

        var client = factory.CreateAuthenticatedClient();

        // Act — /api/dashboard is migrated; should NOT hit the existing API
        var response = await client.GetAsync("/api/dashboard");

        // Assert
        response.StatusCode.Should().Be(HttpStatusCode.OK);
        factory.ExistingApiServer.LogEntries.Should()
            .NotContain(entry => entry.RequestMessage.Path == "/api/dashboard");
    }
}

These tests use WireMock.NET (dotnet add package WireMock.Net) as a stub for the existing API during integration testing. WireMock logs every incoming request, which allows the test to assert that the existing API was or was not called for a given endpoint.

Feature flags for gradual traffic migration

For high-risk endpoints — those with complex business logic or high traffic volume — a feature flag allows routing a percentage of traffic to the BFF before full cutover:

// Middleware/MigrationRoutingMiddleware.cs
public sealed class MigrationRoutingMiddleware(
    RequestDelegate next,
    IConfiguration config)
{
    public async Task InvokeAsync(HttpContext ctx)
    {
        var path = ctx.Request.Path.Value ?? "";

        // Check if this path has a gradual migration percentage configured
        var migrationKey = $"Migration:Routes:{SanitisePath(path)}:BffPercentage";
        if (int.TryParse(config[migrationKey], out var bffPercent)
            && bffPercent < 100)
        {
            var roll = Random.Shared.Next(100);
            if (roll >= bffPercent)
            {
                // This request goes to the existing API
                // Mark it so YARP handles it instead of the BFF route
                ctx.Items["ForceProxy"] = true;
            }
        }

        await next(ctx);
    }

    private static string SanitisePath(string path) =>
        path.TrimStart('/').Replace('/', ':');
}

Configure the migration percentage in appsettings.json:

{
  "Migration": {
    "Routes": {
      "api:courses:detail": {
        "BffPercentage": 10
      }
    }
  }
}

Start at 10% of traffic to the BFF for a newly migrated endpoint. Monitor error rates and latency in Application Insights, split by the Source: bff vs Source: existing-api label set in the middleware. Increase the percentage incrementally — 10%, 25%, 50%, 100% — over days or weeks depending on confidence. If errors appear at any stage, rollback is a configuration change, not a code deployment.

Stage 3: Authentication boundary migration

Authentication is typically the most complex aspect of brownfield BFF migration. The existing system usually uses a pattern established years ago — often bearer tokens stored in localStorage, JWT validation in the frontend, and a stateless API. The BFF introduces a fundamentally different model: server-side sessions, HttpOnly cookies, and Feide OIDC.

These two authentication models cannot coexist in the same session. A user authenticated with the old model cannot seamlessly transition to the new model without a re-authentication event. The migration strategy must account for this.

The dual-auth window

During the migration, the BFF accepts both authentication models simultaneously:

// Authentication configuration during migration
builder.Services
    .AddAuthentication(options =>
    {
        // Default to cookie (new model) — falls back to JWT (old model)
        options.DefaultAuthenticateScheme = "cookie-or-jwt";
        options.DefaultChallengeScheme    = OpenIdConnectDefaults.AuthenticationScheme;
    })
    .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme, opts =>
    {
        opts.Cookie.Name     = "__bff_session";
        opts.Cookie.HttpOnly = true;
        opts.Cookie.Secure   = true;
        opts.Cookie.SameSite = SameSiteMode.Strict;
        opts.Cookie.MaxAge   = TimeSpan.FromHours(8);
    })
    .AddJwtBearer("legacy-jwt", opts =>
    {
        // Existing API's JWT configuration — same issuer, same audience
        opts.Authority = config["LegacyAuth:Authority"];
        opts.Audience  = config["LegacyAuth:Audience"];
        opts.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer   = true,
            ValidateAudience = true,
            ValidateLifetime = true
        };
    })
    .AddOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme, opts =>
    {
        // Feide configuration from Article 6
        opts.Authority    = config["Feide:Authority"];
        opts.ClientId     = config["Feide:ClientId"];
        opts.ClientSecret = config["Feide:ClientSecret"];
        // ...
    })
    .AddPolicyScheme("cookie-or-jwt", "Cookie or JWT", opts =>
    {
        opts.ForwardDefaultSelector = ctx =>
        {
            // If a session cookie is present — use cookie auth (new model)
            if (ctx.Request.Cookies.ContainsKey("__bff_session"))
                return CookieAuthenticationDefaults.AuthenticationScheme;

            // If an Authorization header is present — use JWT (legacy model)
            if (ctx.Request.Headers.ContainsKey("Authorization"))
                return "legacy-jwt";

            // Neither — challenge with Feide
            return OpenIdConnectDefaults.AuthenticationScheme;
        };
    });

With this configuration, a user with an existing JWT session continues to function. A user who re-authenticates through the BFF gets a session cookie. Both are valid during the migration window.

Forcing re-authentication

The migration window should have a defined end date. After that date, the legacy-jwt scheme is removed and only the cookie-based session is accepted. Users still holding a JWT are redirected to the Feide login page on their next request. This is a deliberate, communicated breaking change — not a silent failure.

Communicate it to users as a security improvement ("we've updated how authentication works to improve security") and choose a date that coincides with the natural expiry of existing JWTs. If JWTs expire after 24 hours, removing the legacy scheme after 25 hours ensures no currently-valid JWT is invalidated — users whose session expires naturally will authenticate through the new model on their next login.

Stage 4: Retiring the existing API connection

The migration is complete when every endpoint in the migration status document has been moved from "proxied" to "migrated." At this point, the YARP catch-all route is dead code — no requests reach it.

Verify this with a query in Application Insights before removing it:

// Check for any requests hitting the proxy catch-all in the last 7 days
requests
| where timestamp > ago(7d)
| where cloud_RoleName == "bff"
| where name contains "catch-all"    // YARP names proxied routes by their route id
| summarize count() by name, bin(timestamp, 1d)

If this query returns results, there are endpoints that were missed in the migration. Find them, migrate them, and run the query again.

Once the query returns no results for 7 days, the YARP catch-all can be removed:

// Program.cs — Stage 4: proxy removed, BFF-only
// app.MapReverseProxy(); ← removed

app.MapDashboardEndpoints();
app.MapCourseEndpoints();
app.MapAuthEndpoints();
app.MapSessionEndpoints();
app.MapEnrollmentEndpoints();

app.Run();

And the Yarp.ReverseProxy package can be removed from the project:

dotnet remove package Yarp.ReverseProxy

The removal of the proxy dependency is the signal that the Strangler Fig has completed its work. The old structure has been replaced; the BFF stands on its own.

The migration timeline in practice

The education platform BFF migration was completed over nine weeks. The timeline was driven by three factors: the number of distinct endpoint groups that needed migrating, the complexity of the authentication transition, and the team's capacity alongside their ongoing feature work.

Week 1–2:  Stage 1 — proxy deployed, validated, traffic baseline established
Week 3–4:  Stage 2 — dashboard and course list endpoints migrated
Week 5:    Stage 2 — authentication boundary migrated, dual-auth window opened
Week 6–7:  Stage 2 — remaining read endpoints migrated
Week 8:    Stage 2 — write endpoints migrated with idempotency keys
Week 9:    Stage 3 — legacy JWT support removed, dual-auth window closed
           Stage 4 — proxy removed, YARP dependency removed

The migration was done entirely without a feature freeze. Feature development continued on the existing API endpoints while the BFF migration progressed. The coexistence routing made this possible — new features added to the existing API continued to work through the proxy until those endpoints were migrated.

What goes wrong in brownfield migrations

Three failure modes appear consistently in BFF migrations that stall or regress.

The migration loses momentum after the easy endpoints. The first three or four endpoints migrated are typically the most straightforward — read endpoints with simple response shapes that the Vue application already knows how to consume. Then the migration reaches the endpoints with complex business logic, non-idempotent writes, or dependencies on authentication state that differs between the old and new model. These endpoints take longer. The team's capacity is consumed by feature work. The migration status document stops being updated. Six months later, 60% of endpoints are migrated and no one has the context to finish.

The fix is a defined migration end date, agreed at the start of the project, with engineering management visibility. "We will complete the migration by [date]" is a commitment that changes how the team prioritises the remaining work. An open-ended migration is a migration that will not be completed.

The proxy catches bugs that the existing API already had. When the BFF is introduced as a proxy, errors that were already present in the existing API become visible through the BFF's logs and Application Insights. The instinct is to fix them in the BFF. Resist this — fixing existing API bugs in the BFF creates coupling between the proxy and the API's broken behaviour, and the fixes must be re-done when the endpoint is eventually migrated to native BFF handling. Log the bugs, report them to the teams that own the existing API, and let them be fixed at the source.

The Vue application is modified during the migration. If the Vue application is updated to use the new BFF response shapes before all endpoints are migrated, the frontend code must handle two different shapes for the same data simultaneously — one from the BFF, one from the legacy proxy. This is the most common source of migration-phase bugs. The correct sequencing: migrate the BFF endpoint first, validate it in staging, then update the Vue application's composables to use the new shape. Never the reverse.

When the Strangler Fig is not the right approach

The Strangler Fig is the right migration strategy for most brownfield BFF adoptions, but not all.

If the existing API and the new BFF will share the same domain name and the same path namespace, the routing differentiation that YARP provides requires careful configuration to avoid conflicts. In this situation, it may be simpler to accept a brief maintenance window and do a cutover rather than managing the coexistence routing.

If the Vue application is being rewritten simultaneously — a common scenario in brownfield projects where technical debt has accumulated enough to justify both a frontend rewrite and a BFF introduction — the Strangler Fig adds complexity without benefit. A clean-slate Vue 3 application and a new BFF can be developed together against a shared API contract, with the existing frontend kept running until the new system is validated. This is a parallel-run strategy rather than a Strangler Fig, and it is the correct choice when the frontend is being replaced rather than migrated.

The Strangler Fig is for preserving the existing frontend while migrating the backend layer beneath it. When both are changing at once, a different approach is warranted.

☰ Series navigation

A BFF that aggregates four upstream services inherits four independent failure modes. Any one of them can be unavailable, slow, or intermittently returning errors at any time. The question is not whether an upstream service will fail — it will — but whether that failure propagates to the user as a broken screen or is absorbed by the BFF and handled gracefully.

Polly is the .NET resilience library that provides the building blocks to absorb those failures: retries for transient errors, timeouts for slow upstreams, circuit breakers for services that are systematically down, and bulkheads for isolating one upstream's failure from another's. Used correctly, these patterns make the BFF fault-tolerant. Used incorrectly — retrying too aggressively, timing out too generously, failing to isolate failure domains — they amplify the problems they were meant to solve.

This article covers the correct application of each pattern to a BFF, the specific failure modes each one addresses, and how they compose into a production-grade resilience strategy. Code examples use the education platform BFF built throughout this series and Microsoft.Extensions.Http.Resilience, the .NET 8 integration layer that wires Polly into the HttpClient pipeline.

The resilience problem, stated precisely

In Article 4, every typed HTTP client was configured with AddStandardResilienceHandler():

builder.Services.AddHttpClient<CourseServiceClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["Services:CourseService:BaseUrl"]!))
    .AddStandardResilienceHandler();

The standard handler is a reasonable starting point — it wires retry, circuit breaker, and timeout with sensible defaults. But it is a generic solution, and a BFF has specific requirements that the defaults do not address:

• Different upstream services have different acceptable latency budgets. A user profile lookup should time out faster than a course session export.

• Retrying a user profile call three times is reasonable. Retrying an enrollment mutation three times could create three enrollments.

• A circuit breaker that opens for 30 seconds on the notification service should not affect the circuit breaker state of the course service.

• The aggregator's partial failure handling (from Article 4) depends on the resilience layer returning a specific failure signal — not throwing an exception that crashes the entire aggregation.

These requirements mean the standard handler needs to be replaced with per-client custom configuration for any BFF that runs in production under real conditions.

Installing the right packages

dotnet add package Microsoft.Extensions.Http.Resilience
dotnet add package Polly
dotnet add package Polly.Extensions

Microsoft.Extensions.Http.Resilience is the preferred integration layer in .NET 8. It uses Polly 8 under the hood and integrates with IHttpClientFactory, ILogger, and IMetricsFactory from the host. The raw Polly package is used for building custom strategies; Polly.Extensions provides the ResiliencePipelineBuilder extensions.

Understanding the strategy execution order

Before configuring individual strategies, the order in which they wrap each request matters significantly. The standard pipeline executes strategies from outermost to innermost:

The total timeout is the hard wall — no matter how many retries are attempted, the entire operation cannot exceed this duration. The retry wraps the circuit breaker, which means the circuit breaker sees individual attempt outcomes. The attempt timeout is per-attempt — if a single upstream call takes longer than the attempt timeout, it is cancelled and the retry policy fires.

This ordering is not arbitrary. Inverting the circuit breaker and the retry would mean the circuit breaker sees aggregate retry counts as single outcomes, which defeats its purpose. Understanding this ordering is prerequisite to understanding why the custom configuration below is shaped the way it is.

Per-client resilience configuration

The correct approach for a BFF is to define a resilience pipeline per upstream client, tuned to that service's characteristics. A helper method keeps the configuration readable:

// Infrastructure/Resilience/ResiliencePipelineFactory.cs
public static class ResiliencePipelineFactory
{
    /// <summary>
    /// Standard read pipeline — safe to retry, moderate timeout.
    /// Use for GET requests to stable internal services.
    /// </summary>
    public static Action<ResiliencePipelineBuilder<HttpResponseMessage>>
        ReadPipeline(
            string serviceName,
            TimeSpan attemptTimeout,
            TimeSpan totalTimeout) => pipeline =>
    {
        pipeline
            // 1. Total timeout — hard limit on the whole operation including retries
            .AddTimeout(new TimeoutStrategyOptions
            {
                Timeout = totalTimeout,
                OnTimeout = args =>
                {
                    Log.TotalTimeout(args.Context.GetLogger(), serviceName, totalTimeout);
                    return ValueTask.CompletedTask;
                }
            })

            // 2. Retry — exponential backoff with jitter, read-safe
            .AddRetry(new RetryStrategyOptions<HttpResponseMessage>
            {
                MaxRetryAttempts = 2,
                Delay             = TimeSpan.FromMilliseconds(200),
                BackoffType       = DelayBackoffType.Exponential,
                UseJitter         = true,
                ShouldHandle      = args => ValueTask.FromResult(
                    ShouldRetry(args.Outcome)),
                OnRetry = args =>
                {
                    Log.Retrying(args.Context.GetLogger(), serviceName,
                        args.AttemptNumber + 1, args.RetryDelay);
                    return ValueTask.CompletedTask;
                }
            })

            // 3. Circuit breaker — opens after sustained failures
            .AddCircuitBreaker(new CircuitBreakerStrategyOptions<HttpResponseMessage>
            {
                FailureRatio            = 0.5,   // Open when 50% of requests fail
                SamplingDuration        = TimeSpan.FromSeconds(30),
                MinimumThroughput       = 5,     // Minimum requests before ratio applies
                BreakDuration           = TimeSpan.FromSeconds(20),
                ShouldHandle            = args => ValueTask.FromResult(
                    ShouldHandle(args.Outcome)),
                OnOpened = args =>
                {
                    Log.CircuitOpened(args.Context.GetLogger(), serviceName,
                        args.BreakDuration);
                    return ValueTask.CompletedTask;
                },
                OnClosed = args =>
                {
                    Log.CircuitClosed(args.Context.GetLogger(), serviceName);
                    return ValueTask.CompletedTask;
                },
                OnHalfOpened = args =>
                {
                    Log.CircuitHalfOpened(args.Context.GetLogger(), serviceName);
                    return ValueTask.CompletedTask;
                }
            })

            // 4. Per-attempt timeout — cancels a single slow call before retry fires
            .AddTimeout(new TimeoutStrategyOptions
            {
                Timeout = attemptTimeout
            });
    };

    /// <summary>
    /// Write pipeline — NOT safe to retry on most failures.
    /// Use for POST/PUT/DELETE requests where idempotency cannot be guaranteed.
    /// </summary>
    public static Action<ResiliencePipelineBuilder<HttpResponseMessage>>
        WritePipeline(string serviceName, TimeSpan attemptTimeout) => pipeline =>
    {
        pipeline
            // Total timeout only — no retry for non-idempotent operations
            .AddTimeout(new TimeoutStrategyOptions { Timeout = attemptTimeout })

            // Circuit breaker — still needed to fail-fast when service is down
            .AddCircuitBreaker(new CircuitBreakerStrategyOptions<HttpResponseMessage>
            {
                FailureRatio      = 0.5,
                SamplingDuration  = TimeSpan.FromSeconds(30),
                MinimumThroughput = 3,
                BreakDuration     = TimeSpan.FromSeconds(20),
                ShouldHandle      = args => ValueTask.FromResult(
                    ShouldHandle(args.Outcome))
            });
    };

    // Which outcomes warrant a retry
    private static bool ShouldRetry(Outcome<HttpResponseMessage> outcome)
    {
        if (outcome.Exception is HttpRequestException or TaskCanceledException)
            return true;

        if (outcome.Result is { } response)
            return response.StatusCode is
                HttpStatusCode.RequestTimeout or      // 408
                HttpStatusCode.TooManyRequests or     // 429
                HttpStatusCode.InternalServerError or // 500
                HttpStatusCode.BadGateway or          // 502
                HttpStatusCode.ServiceUnavailable or  // 503
                HttpStatusCode.GatewayTimeout;        // 504

        return false;
    }

    // Which outcomes the circuit breaker counts as failures
    private static bool ShouldHandle(Outcome<HttpResponseMessage> outcome)
    {
        if (outcome.Exception is not null) return true;
        if (outcome.Result is { } response)
            return (int)response.StatusCode >= 500;
        return false;
    }

    // Structured log messages — static for performance
    private static class Log
    {
        public static void TotalTimeout(ILogger? logger, string service, TimeSpan timeout) =>
            logger?.LogWarning(
                "Total timeout exceeded for {Service}. Timeout: {Timeout}ms",
                service, timeout.TotalMilliseconds);

        public static void Retrying(ILogger? logger, string service,
            int attempt, TimeSpan delay) =>
            logger?.LogWarning(
                "Retrying {Service}. Attempt: {Attempt}, Delay: {DelayMs}ms",
                service, attempt, delay.TotalMilliseconds);

        public static void CircuitOpened(ILogger? logger, string service,
            TimeSpan breakDuration) =>
            logger?.LogError(
                "Circuit breaker OPENED for {Service}. " +
                "Break duration: {BreakDuration}s. Upstream calls suspended.",
                service, breakDuration.TotalSeconds);

        public static void CircuitClosed(ILogger? logger, string service) =>
            logger?.LogInformation(
                "Circuit breaker CLOSED for {Service}. Upstream calls resumed.", service);

        public static void CircuitHalfOpened(ILogger? logger, string service) =>
            logger?.LogInformation(
                "Circuit breaker HALF-OPEN for {Service}. Probing upstream.", service);
    }
}

Wiring per-client pipelines in Program.cs

Each upstream client receives a pipeline tuned to its characteristics. The latency budget for each service was derived from the p95 response times observed in Application Insights during the first month of production operation:

// Program.cs
// User Service — small, fast lookups; tight timeout; retryable
builder.Services
    .AddHttpClient<UserServiceClient>(client =>
        client.BaseAddress = new Uri(config["Services:UserService:BaseUrl"]!))
    .AddResilienceHandler("user-service",
        ResiliencePipelineFactory.ReadPipeline(
            serviceName:    "UserService",
            attemptTimeout: TimeSpan.FromMilliseconds(400),
            totalTimeout:   TimeSpan.FromMilliseconds(1200)))
    .AddHttpMessageHandler<FeideTokenHandler>();

// Course Service — dataset can be larger; slightly longer timeout
builder.Services
    .AddHttpClient<CourseServiceClient>(client =>
        client.BaseAddress = new Uri(config["Services:CourseService:BaseUrl"]!))
    .AddResilienceHandler("course-service",
        ResiliencePipelineFactory.ReadPipeline(
            serviceName:    "CourseService",
            attemptTimeout: TimeSpan.FromMilliseconds(600),
            totalTimeout:   TimeSpan.FromMilliseconds(2000)))
    .AddHttpMessageHandler<FeideTokenHandler>();

// Session Service — potentially heavier queries; more generous total timeout
builder.Services
    .AddHttpClient<SessionServiceClient>(client =>
        client.BaseAddress = new Uri(config["Services:SessionService:BaseUrl"]!))
    .AddResilienceHandler("session-service",
        ResiliencePipelineFactory.ReadPipeline(
            serviceName:    "SessionService",
            attemptTimeout: TimeSpan.FromMilliseconds(800),
            totalTimeout:   TimeSpan.FromMilliseconds(2500)))
    .AddHttpMessageHandler<FeideTokenHandler>();

// Notification Service — low criticality; tight budget
builder.Services
    .AddHttpClient<NotificationServiceClient>(client =>
        client.BaseAddress = new Uri(config["Services:NotificationService:BaseUrl"]!))
    .AddResilienceHandler("notification-service",
        ResiliencePipelineFactory.ReadPipeline(
            serviceName:    "NotificationService",
            attemptTimeout: TimeSpan.FromMilliseconds(300),
            totalTimeout:   TimeSpan.FromMilliseconds(900)))
    .AddHttpMessageHandler<FeideTokenHandler>();

// Enrollment — write operation; no retry; circuit breaker only
builder.Services
    .AddHttpClient<EnrollmentServiceClient>(client =>
        client.BaseAddress = new Uri(config["Services:CourseService:BaseUrl"]!))
    .AddResilienceHandler("enrollment-write",
        ResiliencePipelineFactory.WritePipeline(
            serviceName:    "EnrollmentService",
            attemptTimeout: TimeSpan.FromSeconds(5)))
    .AddHttpMessageHandler<FeideTokenHandler>();

The notification service has the tightest budget — 300ms per attempt, 900ms total — because it is the least critical upstream in the aggregation. If notifications are slow, the partial failure path (from Article 4) handles the absence gracefully. Spending 2.5 seconds waiting for a notification count is a worse user experience than returning a count of zero with a partialFailures: ["notifications"] marker.

Handling resilience exceptions in typed clients

The resilience pipeline throws specific exceptions when it exhausts its strategies. The typed clients must catch these and return null so the aggregator's partial failure logic can handle them:

// Clients/CourseServiceClient.cs
public sealed class CourseServiceClient(
    HttpClient http,
    IHttpContextAccessor contextAccessor,
    ILogger<CourseServiceClient> logger)
{
    public async Task<IReadOnlyList<CourseDto>?> GetCoursesByOrgAsync(
        string orgId, CancellationToken ct = default)
    {
        try
        {
            var request = new HttpRequestMessage(
                HttpMethod.Get, $"courses?orgId={orgId}");
            AttachCorrelationId(request);

            var response = await http.SendAsync(request, ct);
            response.EnsureSuccessStatusCode();
            return await response.Content
                .ReadFromJsonAsync<IReadOnlyList<CourseDto>>(ct);
        }
        catch (BrokenCircuitException ex)
        {
            // Circuit is open — upstream is known-bad, skip immediately
            logger.LogWarning(
                "Circuit open for CourseService. Skipping upstream call. " +
                "OrgId: {OrgId}. Message: {Message}", orgId, ex.Message);
            return null;
        }
        catch (TimeoutRejectedException ex)
        {
            // Total timeout exhausted — upstream is too slow
            logger.LogWarning(
                "Timeout exhausted for CourseService. OrgId: {OrgId}. " +
                "Duration: {Duration}ms", orgId, ex.Telemetry.ExecutionTime.TotalMilliseconds);
            return null;
        }
        catch (HttpRequestException ex)
        {
            logger.LogWarning(ex,
                "HTTP error from CourseService. OrgId: {OrgId}. Status: {Status}",
                orgId, ex.StatusCode);
            return null;
        }
        catch (OperationCanceledException) when (!ct.IsCancellationRequested)
        {
            // Cancelled by the per-attempt timeout, not by the caller
            logger.LogWarning(
                "CourseService call cancelled by attempt timeout. OrgId: {OrgId}", orgId);
            return null;
        }
    }

    private void AttachCorrelationId(HttpRequestMessage request)
    {
        var correlationId = contextAccessor.HttpContext?
            .Response.Headers["X-Correlation-Id"].FirstOrDefault();
        if (correlationId is not null)
            request.Headers.TryAddWithoutValidation("X-Correlation-Id", correlationId);
    }
}

BrokenCircuitException is the most important case. When the circuit is open, Polly throws this exception immediately — no upstream call is made. The client catches it and returns null, which the aggregator records as a partial failure. A screen that would have waited 2.5 seconds for a timing-out upstream now fails in microseconds. This is the circuit breaker's primary value: fail fast rather than fail slow.

The aggregator: partial failure as a first-class outcome

The aggregator receives null from clients whose upstream calls failed, regardless of which resilience strategy triggered the failure. The distinction between a BrokenCircuitException and a TimeoutRejectedException is logged at the client level; the aggregator only sees the null result and decides what to do with it.

// Aggregators/DashboardAggregator.cs
public async Task<DashboardResponse> AggregateAsync(
    string userId, CancellationToken ct = default)
{
    var partialFailures = new List<string>();

    // Phase 1: parallel — both can fail independently
    var profileTask      = _userClient.GetProfileAsync(userId, ct);
    var notificationTask = _notificationClient.GetUnreadCountAsync(userId, ct);
    await Task.WhenAll(profileTask, notificationTask);

    var profile = profileTask.Result;

    // Profile is required — its absence is not a partial failure, it is a hard stop
    if (profile is null)
        throw new BffAggregationException("User profile service unavailable.");

    // Notification is optional — absence is gracefully degraded
    var notificationCount = notificationTask.Result ?? 0;
    if (notificationTask.Result is null)
        partialFailures.Add("notifications");

    // Phase 2: courses — absence degrades but does not fail the response
    var courses = await _courseClient.GetCoursesByOrgAsync(profile.OrgId, ct);
    if (courses is null)
        partialFailures.Add("courses");

    // Phase 3: sessions — only attempted if courses succeeded
    IReadOnlyList<SessionDto>? sessions = null;
    if (courses is { Count: > 0 })
    {
        sessions = await _sessionClient.GetUpcomingAsync(
            courses.Select(c => c.Id).ToArray(), 3, ct);
        if (sessions is null)
            partialFailures.Add("sessions");
    }

    return new DashboardResponse(
        User:             ShapeUserProfile(profile),
        Courses:          courses?.Select(ShapeCourse).ToList() ?? [],
        UpcomingSessions: sessions?.Select(ShapeSession).ToList() ?? [],
        Notifications:    new NotificationSummary(notificationCount),
        PartialFailures:  partialFailures
    );
}

The aggregator does not know whether courses is null because the circuit breaker opened, because a retry was exhausted, or because the service returned a 500. That distinction belongs in the client's log entry, which carries the correlation ID. The aggregator concerns itself only with the outcome: data was available or it was not.

The retry problem: when not to retry

The ShouldRetry predicate above deliberately excludes certain status codes. This is the most consequential decision in retry configuration.

Do not retry 4xx errors (except 408 and 429). A 400 Bad Request means the request itself is malformed — retrying the same request will produce the same 400. A 401 or 403 means the caller is not authorised — retrying will not change that. A 404 means the resource does not exist — retrying will not create it. The only 4xx codes worth retrying are 408 (request timeout, which may have been a transient infrastructure issue) and 429 (too many requests, which should be retried after the Retry-After header's delay).

Do not retry non-idempotent operations. The write pipeline above has no retry. A POST to /courses/{id}/enrollment that creates an enrollment and then returns a 500 due to a response serialisation error has still created the enrollment. Retrying creates a duplicate. The service must be designed to be idempotent — or the client must not retry.

In the production system, this distinction caused one production incident before the write pipeline was separated. A retry on a 500 from the enrollment service — which had successfully created the enrollment before encountering a downstream notification error — created duplicate enrollments for four students. The fix was the dedicated write pipeline with no retry and explicit idempotency keys added to the enrollment POST.

Idempotency keys for safe write retries

If retrying writes is genuinely required, idempotency keys are the mechanism. The BFF generates a key for the operation, sends it with the request, and the upstream service uses it to deduplicate:

// Clients/EnrollmentServiceClient.cs
public async Task<EnrollmentResultDto?> EnrollAsync(
    string courseId, string userId,
    string idempotencyKey, // Caller-provided — generated once per user action
    CancellationToken ct = default)
{
    var request = new HttpRequestMessage(
        HttpMethod.Post, $"courses/{courseId}/enrollments");
    request.Headers.TryAddWithoutValidation("Idempotency-Key", idempotencyKey);
    request.Content = JsonContent.Create(new { UserId = userId });

    // With idempotency key, retry is safe — upstream will deduplicate
    var response = await http.SendAsync(request, ct);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadFromJsonAsync<EnrollmentResultDto>(ct);
}

The idempotency key is generated in the BFF endpoint from the user ID and the course ID, making it stable for the same logical operation regardless of how many times it is submitted:

// Endpoints/EnrollmentEndpoints.cs
private static async Task<IResult> EnrollAsync(
    string courseId, HttpContext ctx,
    EnrollmentServiceClient enrollmentClient,
    EnrollmentCache enrollmentCache,
    CancellationToken ct)
{
    var userId = ctx.User.FindFirstValue(ClaimTypes.NameIdentifier)!;

    // Deterministic key — same user + course always produces the same key
    var idempotencyKey = Convert.ToHexString(
        SHA256.HashData(
            Encoding.UTF8.GetBytes($"{userId}:{courseId}:{DateTime.UtcNow:yyyy-MM-dd}")));

    var result = await enrollmentClient.EnrollAsync(courseId, userId, idempotencyKey, ct);

    if (result is null)
        return Results.Problem(
            detail: "Enrollment could not be processed.",
            statusCode: StatusCodes.Status502BadGateway);

    await enrollmentCache.InvalidateAsync(userId, ct);
    return Results.Ok(result);
}

The date component in the key ensures that the same enrollment attempt on different days produces different keys — which is correct, since a student might legitimately withdraw and re-enroll in the same course across days.

Bulkhead isolation: containing failure domains

A bulkhead limits the number of concurrent calls to a specific upstream service. Without bulkheads, a slow upstream service can exhaust the BFF's thread pool — every available thread is waiting on that upstream, and requests to other upstreams queue behind them.

Bulkhead support in Microsoft.Extensions.Http.Resilience is provided through the AddConcurrencyLimiter extension:

// For services that are particularly prone to slowdowns under load
builder.Services
    .AddHttpClient<SessionServiceClient>(client =>
        client.BaseAddress = new Uri(config["Services:SessionService:BaseUrl"]!))
    .AddResilienceHandler("session-service", pipeline =>
    {
        // Add bulkhead before the read pipeline strategies
        pipeline.AddConcurrencyLimiter(new ConcurrencyLimiterOptions
        {
            PermitLimit = 20,  // Max 20 concurrent calls to SessionService
            QueueLimit  = 5    // Queue up to 5 more — reject beyond that
        });

        // Then the standard read pipeline strategies
        ResiliencePipelineFactory.ReadPipeline(
            "SessionService",
            TimeSpan.FromMilliseconds(800),
            TimeSpan.FromMilliseconds(2500))(pipeline);
    })
    .AddHttpMessageHandler<FeideTokenHandler>();

When the session service is slow and 20 concurrent BFF requests are already waiting for it, the 21st through 25th requests queue. The 26th is rejected immediately with a RateLimitRejectedException, which the client catches and returns as null — a partial failure for sessions, not a hard error. The user profile and course data still load; only upcoming sessions are absent.

Without the bulkhead, the 26th request would add another waiting thread. At sufficient load, the BFF's thread pool is exhausted by session service calls, and requests to the user service — which might be perfectly healthy — cannot execute. The bulkhead contains the blast radius.

Testing resilience behaviour

Resilience strategies are only trustworthy if they are tested. The integration test factory from Article 8 provides the mechanism — configure the substitute to throw the exceptions that the resilience layer would throw, and verify the aggregator's response.

// EducationPlatform.Bff.IntegrationTests/Resilience/CircuitBreakerTests.cs
public class CircuitBreakerTests(BffWebApplicationFactory factory)
    : IClassFixture<BffWebApplicationFactory>
{
    [Fact]
    public async Task Dashboard_CourseServiceCircuitOpen_ReturnsDegradedResponse()
    {
        // Arrange — profile and notifications available; courses circuit open
        factory.UserClient
            .GetProfileAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(new UserProfileDto("Ingrid", "Solberg", "uninett", "TEACHER", null));

        factory.NotificationClient
            .GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(0);

        // Simulate the client returning null (as it would after catching BrokenCircuitException)
        factory.CourseClient
            .GetCoursesByOrgAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns((IReadOnlyList<CourseDto>?)null);

        var client = factory.CreateAuthenticatedClient();

        // Act
        var response = await client.GetAsync("/api/dashboard");

        // Assert — 200 with partial failure, not a 503
        response.StatusCode.Should().Be(HttpStatusCode.OK);
        var body = await response.Content.ReadFromJsonAsync<DashboardResponse>();
        body!.Courses.Should().BeEmpty();
        body.PartialFailures.Should().Contain("courses");
        body.User.DisplayName.Should().Be("Ingrid Solberg"); // User data unaffected
    }

    [Fact]
    public async Task Dashboard_AllNonCriticalServicesUnavailable_ReturnsMinimalResponse()
    {
        // Arrange — only profile available
        factory.UserClient
            .GetProfileAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(new UserProfileDto("Ingrid", "Solberg", "uninett", "TEACHER", null));

        factory.NotificationClient
            .GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns((int?)null);

        factory.CourseClient
            .GetCoursesByOrgAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns((IReadOnlyList<CourseDto>?)null);

        var client = factory.CreateAuthenticatedClient();

        // Act
        var response = await client.GetAsync("/api/dashboard");

        // Assert — still a valid response, just minimally populated
        response.StatusCode.Should().Be(HttpStatusCode.OK);
        var body = await response.Content.ReadFromJsonAsync<DashboardResponse>();
        body!.User.Should().NotBeNull(); // The one thing that always works
        body.Courses.Should().BeEmpty();
        body.UpcomingSessions.Should().BeEmpty();
        body.Notifications.Count.Should().Be(0);
        body.PartialFailures.Should().HaveCount(2)
            .And.Contain("courses")
            .And.Contain("notifications");
    }

    [Fact]
    public async Task Dashboard_ProfileServiceUnavailable_Returns503()
    {
        // Profile is required — its absence cannot be partially failed
        factory.UserClient
            .GetProfileAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns((UserProfileDto?)null);

        factory.NotificationClient
            .GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(0);

        var client = factory.CreateAuthenticatedClient();

        var response = await client.GetAsync("/api/dashboard");

        response.StatusCode.Should().Be(HttpStatusCode.ServiceUnavailable);
    }
}

These tests verify the aggregator's partial failure behaviour under resilience-layer outcomes. They test the outcomes — what the Vue application receives — not the Polly strategies themselves. Testing Polly's internal behaviour is Polly's job; testing that your aggregator responds correctly to the signals Polly produces is yours.

Observing resilience behaviour in production

Resilience events — retries, timeouts, circuit breaker state changes — must be visible in Application Insights. The OnRetry, OnOpened, OnClosed, and OnHalfOpened callbacks in the pipeline configuration (shown above) emit structured log entries that Serilog writes to Application Insights.

A KQL query that surfaces retry activity:

traces
| where timestamp > ago(1h)
| where message contains "Retrying"
| extend
    Service = tostring(customDimensions["Service"]),
    Attempt = toint(customDimensions["Attempt"])
| summarize RetryCount = count() by Service, bin(timestamp, 5m)
| render timechart

And circuit breaker openings:

traces
| where timestamp > ago(24h)
| where message contains "Circuit breaker OPENED"
| extend Service = tostring(customDimensions["Service"])
| project timestamp, Service, message
| order by timestamp desc

In the production system, this query was part of the daily operational review. A circuit breaker opening is always a signal worth investigating — it means an upstream service sustained a 50% failure rate for at least 30 seconds with at least 5 requests. That is not a transient blip; it is an upstream service in trouble. The circuit breaker opening is often the first observable signal of an upstream incident, arriving before alerts from the upstream team's own monitoring.

The settings that required tuning in production

The initial resilience configuration used the standard handler defaults for all services. Three settings were tuned after observing production behaviour:

Attempt timeout for the notification service was lowered from 1 second to 300ms. The notification service was consistently the slowest upstream at p95 — 280ms. With a 1-second attempt timeout and two retries, a slow notification call could hold a BFF aggregation for up to 3 seconds before returning null. At 300ms, the first slow call times out quickly, the retry fires once, and if it also times out the total operation completes in 900ms — within the acceptable budget for a non-critical service.

Circuit breaker MinimumThroughput was raised from 3 to 5 for the user service. At 3 requests, a brief burst of three 500 errors — which occurred during a weekly maintenance window on the user service — opened the circuit breaker and blocked all dashboard loads for 20 seconds. Five requests provide a more stable signal that distinguishes a sustained failure from a brief transient event.

Retry jitter was essential under load. The initial configuration used linear backoff without jitter. During a load test, all requests to the course service that encountered a 503 retried at exactly 200ms, 400ms intervals — producing a coordinated retry storm that overwhelmed the course service recovery. Adding UseJitter = true spread the retries across the delay window and eliminated the storm pattern.

Resilience as a design conversation, not a configuration detail

The configuration decisions above — which services get retries, what the timeout budgets are, where the circuit breaker thresholds sit — are not technical decisions made in isolation. They represent a negotiation between what the BFF can tolerate, what the upstream services can withstand, and what the user experience requires.

A retry that is safe from the BFF's perspective may be harmful from the upstream's perspective if it doubles the load during a partial outage. A timeout that is acceptable for a background operation is unacceptable for a user-facing request on the critical path. A circuit breaker threshold that is appropriate for a high-traffic service is too sensitive for a low-traffic service where three failures in 30 seconds is statistically insignificant.

These thresholds should be reviewed with the teams that own the upstream services, set against measured p95 latencies from production telemetry, and revisited when service characteristics change. A resilience configuration that has not been reviewed in six months is a configuration that no longer reflects the system it is protecting.

☰ Series navigation

Caching is one of the most compelling arguments for the BFF pattern — and one of the fastest ways to introduce subtle, hard-to-diagnose bugs if it is implemented without precision. A BFF that aggregates four upstream services on every request has an obvious caching opportunity: responses that are expensive to assemble and infrequently changing can be served from memory rather than recomputed. But "infrequently changing" is doing significant work in that sentence, and the failure modes that emerge when caching is applied too broadly are worse than the latency it was meant to solve.

This article covers where caching belongs in a BFF, the three caching strategies available in .NET Core and when each is appropriate, the stale-data problems that appear in each strategy, and the cache invalidation patterns that keep the system correct under real-world usage. Code examples are grounded in the education platform BFF built throughout this series.

Where caching belongs — and where it does not

Before any implementation, one architectural question determines whether your caching strategy will stay maintainable: is the data being cached user-specific, or is it shared across users?

This distinction divides the caching problem into two fundamentally different problems that require different solutions.

Shared data is the same for all users or all users within an organisation: the list of available courses for an institution, the current academic calendar, lookup tables for status codes and role descriptions. This data can be cached at the BFF level with a single cache entry serving thousands of requests.

User-specific data is different for every authenticated user: a student's enrolled courses, a teacher's upcoming sessions, a user's unread notifications. Caching this data requires a cache key that includes the user's identity. Serving one user's data to another user is a security vulnerability, not a performance optimisation.

The production system this series is based on had both types. Course catalogue data (available courses for an institution) was shared and changed at most once per day. User enrollment status was user-specific and could change within a single session if a student enrolled or withdrew. These two types required different cache strategies with different TTLs and different invalidation approaches.

A third category exists: request-level aggregation results — data that is expensive to compute for a single request but is neither shared across users nor needed beyond the current response. For this, caching is the wrong tool; parallel upstream calls (as implemented in Article 4) are the right tool. Not every performance problem is a caching problem.

The three caching strategies

.NET Core provides three caching mechanisms with distinct characteristics. A production BFF typically uses all three in different parts of the stack.

1. IMemoryCache — in-process memory cache IMemoryCache stores data in the BFF process's heap. It is the fastest cache available — no serialisation, no network hop — but its data is local to a single container instance and is lost on restart. Appropriate for: shared reference data with low invalidation requirements (course catalogues, academic year data, role lookup tables), in a single-instance deployment. Not appropriate for: user-specific data (cache keys must be per-user, which increases memory pressure significantly at scale), data that must be consistent across multiple BFF instances.

2. IDistributedCache with Redis — out-of-process distributed cache IDistributedCache backed by Redis stores serialised data outside the BFF process. Data survives container restarts, is shared across multiple BFF instances, and can be inspected and cleared independently of the BFF. Appropriate for: user-specific data at scale, shared data in multi-instance deployments, data that must survive BFF restarts. Not appropriate for: data that changes faster than the round-trip cost to Redis justifies caching (for very short TTLs, the Redis latency can approach the upstream call latency).

3. Response caching middleware — HTTP-level cache headers Response caching stores entire HTTP responses — headers and body — and serves them for subsequent requests that match the caching rules. It operates at the HTTP layer and can be combined with a CDN or reverse proxy that respects Cache-Control headers. Appropriate for: unauthenticated or publicly accessible BFF endpoints, endpoints returning shared data where HTTP cache semantics (ETags, If-None-Match) add value. Not appropriate for: authenticated endpoints — Cache-Control: private prevents proxy caching but also limits the usefulness of the middleware itself. For most BFF endpoints behind authentication, response caching at the HTTP layer adds complexity without benefit over IMemoryCache or Redis.

Implementation: IMemoryCache for shared reference data

The course catalogue for an institution — the list of available courses — changes at most once per day in the education platform. Fetching it on every dashboard request is wasteful. It is shared across all users in the same organisation, making it a natural candidate for IMemoryCache.

// Infrastructure/CourseCache.cs
public sealed class CourseCache(
    IMemoryCache cache,
    CourseServiceClient courseClient,
    ILogger<CourseCache> logger)
{
    private static string CacheKey(string orgId) => $"courses:org:{orgId}";

    private static readonly MemoryCacheEntryOptions CacheOptions = new MemoryCacheEntryOptions()
        .SetAbsoluteExpiration(TimeSpan.FromMinutes(30))
        .SetSlidingExpiration(TimeSpan.FromMinutes(10))
        .SetSize(1); // For size-limited cache — each entry counts as 1 unit

    public async Task<IReadOnlyList<CourseDto>?> GetOrFetchAsync(
        string orgId, CancellationToken ct = default)
    {
        var key = CacheKey(orgId);

        if (cache.TryGetValue(key, out IReadOnlyList<CourseDto>? cached))
        {
            logger.LogDebug(
                "Cache hit for courses. OrgId: {OrgId}, Key: {CacheKey}", orgId, key);
            return cached;
        }

        logger.LogDebug(
            "Cache miss for courses. OrgId: {OrgId}, fetching upstream.", orgId);

        var courses = await courseClient.GetCoursesByOrgAsync(orgId, ct);

        if (courses is not null)
        {
            cache.Set(key, courses, CacheOptions);
            logger.LogInformation(
                "Cached {CourseCount} courses for org {OrgId}. TTL: 30 min.",
                courses.Count, orgId);
        }

        return courses;
    }

    public void Invalidate(string orgId)
    {
        var key = CacheKey(orgId);
        cache.Remove(key);
        logger.LogInformation(
            "Cache invalidated for courses. OrgId: {OrgId}", orgId);
    }
}

Register and size the cache in Program.cs:

// Program.cs
builder.Services.AddMemoryCache(opts =>
{
    // Limit the cache to 100MB — prevents unbounded memory growth
    // as the number of institutions served grows
    opts.SizeLimit = 1024; // 1024 units — each entry is 1 unit above
    opts.CompactionPercentage = 0.25; // Remove 25% of entries when limit is hit
    opts.TrackStatistics = true; // Enables cache hit/miss metrics
});

builder.Services.AddSingleton<CourseCache>();

The SetSlidingExpiration combined with SetAbsoluteExpiration creates a TTL behaviour: entries expire 30 minutes after creation regardless of access frequency, but within that window they expire 10 minutes after the last access. For course data that changes on a daily cycle, this means a moderately active institution's data stays cached; an institution with infrequent users (a small school) does not hold stale data indefinitely.

Avoiding the thundering herd

When the cache for a high-traffic organisation expires, multiple concurrent requests will all get cache misses simultaneously and all make the upstream call at the same time. This is the thundering herd problem, and it is particularly acute at startup when the cache is cold.

The fix is a concurrent dictionary as a request coalescer:

// Infrastructure/CourseCache.cs — updated with request coalescing
public sealed class CourseCache(
    IMemoryCache cache,
    CourseServiceClient courseClient,
    ILogger<CourseCache> logger)
{
    // Track in-flight fetch operations — concurrent requests share one Task
    private readonly ConcurrentDictionary<string, Lazy<Task<IReadOnlyList<CourseDto>?>>>
        _inFlight = new();

    public async Task<IReadOnlyList<CourseDto>?> GetOrFetchAsync(
        string orgId, CancellationToken ct = default)
    {
        var key = CacheKey(orgId);

        if (cache.TryGetValue(key, out IReadOnlyList<CourseDto>? cached))
            return cached;

        // Coalesce concurrent cache misses — only one upstream call per key
        var lazyFetch = _inFlight.GetOrAdd(key,
            _ => new Lazy<Task<IReadOnlyList<CourseDto>?>>(
                () => FetchAndCacheAsync(orgId, key, ct)));

        try
        {
            return await lazyFetch.Value;
        }
        finally
        {
            _inFlight.TryRemove(key, out _);
        }
    }

    private async Task<IReadOnlyList<CourseDto>?> FetchAndCacheAsync(
        string orgId, string key, CancellationToken ct)
    {
        var courses = await courseClient.GetCoursesByOrgAsync(orgId, ct);
        if (courses is not null)
            cache.Set(key, courses, CacheOptions);
        return courses;
    }
}

Implementation: Redis for user-specific data

User enrollment status — which courses a specific student or teacher is actively engaged with — changes within a session. A student who enrolls in a course should see that course on their next dashboard load. This rules out in-memory caching with a long TTL, but does not rule out caching entirely — a short TTL with explicit invalidation on write operations provides freshness guarantees while reducing upstream load.

Install the Redis client:

dotnet add package Microsoft.Extensions.Caching.StackExchangeRedis
dotnet add package StackExchange.Redis

Configure in Program.cs:

builder.Services.AddStackExchangeRedisCache(opts =>
{
    opts.Configuration = builder.Configuration["Redis:ConnectionString"];
    opts.InstanceName  = "bff:"; // Prefix all keys — prevents collision with other services
});

The enrollment cache wrapper:

// Infrastructure/EnrollmentCache.cs
public sealed class EnrollmentCache(
    IDistributedCache cache,
    ILogger<EnrollmentCache> logger)
{
    private static string UserKey(string userId) => $"enrollment:{userId}";

    // Short TTL — enrollment status is user-specific and mutable within a session
    private static readonly DistributedCacheEntryOptions Options =
        new DistributedCacheEntryOptions()
            .SetAbsoluteExpirationRelativeToNow(TimeSpan.FromMinutes(5));

    public async Task<EnrollmentStatusDto?> GetAsync(
        string userId, CancellationToken ct = default)
    {
        var key  = UserKey(userId);
        var data = await cache.GetStringAsync(key, ct);

        if (data is null)
        {
            logger.LogDebug("Redis cache miss for enrollment. UserId: {UserId}", userId);
            return null;
        }

        logger.LogDebug("Redis cache hit for enrollment. UserId: {UserId}", userId);
        return JsonSerializer.Deserialize<EnrollmentStatusDto>(data);
    }

    public async Task SetAsync(
        string userId, EnrollmentStatusDto status, CancellationToken ct = default)
    {
        var key  = UserKey(userId);
        var data = JsonSerializer.Serialize(status);
        await cache.SetStringAsync(key, data, Options, ct);
    }

    public async Task InvalidateAsync(string userId, CancellationToken ct = default)
    {
        var key = UserKey(userId);
        await cache.RemoveAsync(key, ct);
        logger.LogInformation(
            "Redis cache invalidated for enrollment. UserId: {UserId}", userId);
    }
}

Cache-aside pattern in the aggregator

The aggregator uses the cache in a cache-aside pattern: check the cache first; on miss, fetch from upstream and populate the cache; on invalidation events, remove the entry.

// Aggregators/CourseAggregator.cs
public sealed class CourseAggregator(
    CourseCache courseCache,
    EnrollmentCache enrollmentCache,
    CourseServiceClient courseClient,
    ILogger<CourseAggregator> logger)
{
    public async Task<CourseDetailResponse> GetCourseDetailAsync(
        string courseId, string userId, CancellationToken ct = default)
    {
        // Try enrollment status from Redis cache first
        var enrollmentStatus = await enrollmentCache.GetAsync(userId, ct);

        if (enrollmentStatus is null)
        {
            logger.LogDebug(
                "Enrollment cache miss for user {UserId}, fetching upstream.", userId);
            var upstreamEnrollment = await courseClient
                .GetEnrollmentStatusAsync(userId, ct);

            if (upstreamEnrollment is not null)
            {
                enrollmentStatus = upstreamEnrollment;
                await enrollmentCache.SetAsync(userId, enrollmentStatus, ct);
            }
        }

        // Course detail from memory cache
        var courseDetail = await courseCache.GetOrFetchAsync(courseId, ct);

        return ShapeCourseDetail(courseDetail, enrollmentStatus);
    }
}

Invalidating on write: enrollment changes

When a user enrolls in or withdraws from a course, the BFF handles the POST/DELETE request. The enrollment cache must be invalidated immediately after the upstream write succeeds:

// Endpoints/EnrollmentEndpoints.cs
private static async Task<IResult> EnrollAsync(
    string courseId,
    HttpContext ctx,
    CourseServiceClient courseClient,
    EnrollmentCache enrollmentCache,
    CancellationToken ct)
{
    var userId = ctx.User.FindFirstValue(ClaimTypes.NameIdentifier)!;

    var result = await courseClient.EnrollAsync(courseId, userId, ct);
    if (result is null)
        return Results.Problem(
            detail: "Enrollment request could not be processed.",
            statusCode: StatusCodes.Status502BadGateway);

    // Invalidate cache immediately after successful write
    // The next GET will fetch fresh data from upstream
    await enrollmentCache.InvalidateAsync(userId, ct);

    return Results.Ok(result);
}

The invalidation-on-write pattern is simple and correct for a BFF architecture. It avoids the complexity of cache-through (writing to the cache as part of the write operation) and cache-update (updating the cached value without an upstream round-trip). Both of those patterns require the cache entry to always be in a valid state relative to the upstream — which is hard to guarantee when the upstream can be modified by systems other than the BFF.

The stale-data problems to watch for

1. Multiple BFF instances with in-memory caches

This is the most common caching mistake in a BFF deployed to multiple container instances. Two instances of the BFF each hold their own in-memory cache. Instance A's cache is invalidated; Instance B's cache still holds the stale entry. A user's requests can round-robin between instances — they see fresh data, then stale data, then fresh data again.

The fix is architectural: in-memory caches should only hold data that is either truly immutable (lookup tables, static reference data that never changes within a deployment lifetime) or whose staleness is acceptable and bounded (data with a short TTL where a brief period of inconsistency between instances is acceptable). User-specific data and data with write-based invalidation must use a distributed cache.

In the production system, the single ACI container instance made this a non-issue during initial deployment. The in-memory course cache was fine for one instance. When the architecture was being designed for potential multi-instance scaling, the course cache was moved to Redis — not because the single instance was problematic, but because the coupling between the caching strategy and the deployment topology was too tight.

2. TTL longer than the upstream change frequency

A 30-minute TTL on course catalogue data is reasonable when courses change at most once per day. If the product owner changes a course's enrollment capacity during an active session, users will see the old capacity for up to 30 minutes. This is an acceptable trade-off only if it has been explicitly agreed with the product team.

The conversation that needs to happen: "We cache course data for 30 minutes to reduce load on the course service. This means a course change takes up to 30 minutes to appear for users. Is that acceptable, or do we need to implement a cache invalidation webhook?" Not having this conversation leads to support tickets about "the system not updating."

In the production system, the course catalogue TTL was set to 30 minutes after explicit agreement with the product team. A cache invalidation endpoint (covered below) was added in the second month when an administrator needed to force an immediate refresh.

3. Cache key collisions

A cache key that does not include all dimensions of uniqueness produces collisions. The most dangerous variant in a BFF is a key that omits the user ID or organisation ID.

// ✗ Dangerous — same key for all users
var key = $"dashboard:courses";

// ✗ Still dangerous — same key for all users in a session
var key = $"dashboard:courses:session";

// ✓ Correct — unique per organisation
var key = $"courses:org:{orgId}";

// ✓ Correct — unique per user
var key = $"enrollment:{userId}";

A cache key collision between two organisations is a data leak. Organisation A's course list is returned to Organisation B's users. In the production system, every cache key was reviewed against the principle: "if two different users made this same request with different identities, would this key produce different results?" If yes, both identities must be in the key.

4. Caching error responses

A cache implementation that stores null results from upstream failures and serves them as cache hits is caching the absence of data as if it were data. The fix is explicit:

// Always check whether upstream returned a valid result before caching
var courses = await courseClient.GetCoursesByOrgAsync(orgId, ct);

if (courses is not null) // Only cache successful responses
{
    cache.Set(key, courses, CacheOptions);
}
// Do not cache null — let the next request try the upstream again
return courses;

This is why the CourseCache above only calls cache.Set inside the if (courses is not null) guard. Caching a null result from a temporarily unavailable service would mean every request for the next 30 minutes is served a null cache hit — extending the upstream outage far beyond its actual duration from the user's perspective.

Cache invalidation patterns

Cache invalidation is famously hard. The BFF has three practical patterns, each appropriate to different scenarios.

Pattern 1: TTL-based expiry (simplest, eventual consistency)

Set a TTL and accept the staleness window. Appropriate for shared reference data where bounded staleness is acceptable and invalidation events cannot be reliably detected.

// 30-minute TTL — course catalogue for an organisation
cache.Set(key, courses, new MemoryCacheEntryOptions()
    .SetAbsoluteExpiration(TimeSpan.FromMinutes(30)));

Advantages: no coordination required, predictable behaviour, simple to reason about. Disadvantages: staleness window can violate product expectations; TTL must be agreed with the product team.

Pattern 2: Write-through invalidation (most reliable for user-specific data)

Invalidate the cache entry immediately after any write operation that changes the cached data. The BFF already handles writes; the invalidation call is a single line after a successful upstream write.

Advantages: immediate consistency after writes, no separate invalidation infrastructure. Disadvantages: only covers writes that go through the BFF. If upstream data changes via a different path (direct API call, admin tool, another service), the BFF cache is not notified.

Pattern 3: Invalidation endpoint (for external events)

Expose a cache invalidation endpoint on the BFF that upstream services or admin tools can call when data changes. This is the pattern for "the upstream can change without going through the BFF."

// Endpoints/CacheEndpoints.cs
public static class CacheEndpoints
{
    public static IEndpointRouteBuilder MapCacheEndpoints(
        this IEndpointRouteBuilder app)
    {
        // Protected by an API key — not exposed to authenticated users
        app.MapPost("/internal/cache/invalidate/org/{orgId}",
            async (string orgId, CourseCache courseCache,
                   HttpContext ctx, IConfiguration config) =>
        {
            // Validate internal API key — this endpoint is not user-facing
            var apiKey = ctx.Request.Headers["X-Internal-Api-Key"].FirstOrDefault();
            if (apiKey != config["InternalApi:Key"])
                return Results.Unauthorized();

            courseCache.Invalidate(orgId);
            return Results.Ok(new { invalidated = true, orgId });
        })
        .WithName("InvalidateCourseCache")
        .ExcludeFromDescription(); // Do not expose in OpenAPI spec

        return app;
    }
}

In the production system, this endpoint was called by an administrative management tool when an institution administrator updated the course catalogue. The management tool made a POST to /internal/cache/invalidate/org/{orgId} after its upstream write completed. The BFF's cache was cleared; the next user request fetched fresh data.

The endpoint is protected by a static API key rather than the standard Feide authentication — it is an internal system-to-system call, not a user action. The key is injected as a secret environment variable, identical to the Feide client secret in Article 7.

Measuring cache effectiveness

Cache effectiveness is not self-evident without metrics. The production system tracked three numbers:

Hit rate by cache layer. For IMemoryCache, the MemoryCache.GetCurrentStatistics() API provides hit count and miss count. Log these periodically:

// Background service — logs cache stats every 5 minutes
public sealed class CacheMetricsService(
    IMemoryCache cache,
    TelemetryClient telemetry,
    ILogger<CacheMetricsService> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            await Task.Delay(TimeSpan.FromMinutes(5), ct);

            var stats = (cache as MemoryCache)?.GetCurrentStatistics();
            if (stats is null) continue;

            var hitRate = stats.TotalHits + stats.TotalMisses > 0
                ? (double)stats.TotalHits / (stats.TotalHits + stats.TotalMisses) * 100
                : 0;

            logger.LogInformation(
                "MemoryCache stats — Hits: {Hits}, Misses: {Misses}, " +
                "HitRate: {HitRate:F1}%, Entries: {EntryCount}, " +
                "EstimatedSize: {Size}",
                stats.TotalHits, stats.TotalMisses,
                hitRate, stats.CurrentEntryCount, stats.CurrentEstimatedSize);

            telemetry.GetMetric("Cache.HitRate").TrackValue(hitRate);
            telemetry.GetMetric("Cache.EntryCount").TrackValue(stats.CurrentEntryCount);
        }
    }
}

Upstream call reduction. Compare the number of BFF requests for course data with the number of actual calls the CourseServiceClient makes. The ratio should match the expected cache hit rate. If the BFF receives 500 dashboard requests per hour for an organisation and the course service receives 500 calls, the cache is not working. If it receives 12 calls (one per 30-minute TTL window during business hours), it is.

Latency delta between cache hits and misses. Log the cache outcome (hit/miss) alongside the aggregation duration in the DashboardAggregationCompleted telemetry event from Article 9. A Kusto query that splits duration by cache outcome reveals the actual latency benefit the cache provides — which is the number that justifies its complexity.

When to remove caching

Caching is sometimes introduced to mask a performance problem that should be fixed at the source. Before adding a cache layer, consider whether the upstream service is slow because it is under-indexed, under-resourced, or architecturally misdesigned — and whether fixing the source would make the cache unnecessary.

The production system removed the enrollment status cache in its second month. The upstream enrollment service had been slow due to a missing database index. After the index was added, the p95 response time dropped from 400ms to 18ms. At 18ms, the 5-minute Redis TTL on enrollment status introduced more staleness risk than the latency it saved. The cache was removed; the enrollment service was called directly on every request.

This is the correct outcome. A cache that is no longer needed is a cache that is no longer producing subtle bugs. The willingness to remove caching when the underlying problem is solved is as important as the willingness to add it when it is genuinely needed.

☰ Series navigation

A note on the code in this article. The observability setup shown here is derived from a production BFF built for a Norwegian enterprise education platform. Resource names, workspace identifiers, alert thresholds, and certain query specifics have been generalised to meet NDA obligations. The Serilog configuration, Application Insights integration, custom telemetry patterns, Kusto queries, and the specific operational decisions each choice addresses are drawn directly from what was deployed and monitored in production.

A BFF that aggregates multiple upstream services has an observability problem that a single-service system does not. When a request to GET /api/dashboard returns a 503, four upstream services are potential failure points. When it takes 2.8 seconds instead of the expected 300ms, any one of the three sequential aggregation phases might be the culprit. Without end-to-end traceability — a single thread of correlation that follows a request from the Vue application's fetch call through every BFF aggregator method and every upstream HTTP call — diagnosing production incidents means guessing.

This article builds that traceability: structured logging with Serilog, distributed tracing with Activity and correlation IDs, and the Application Insights configuration that ties them together into a queryable, alertable observability layer. It then covers the dashboard and alert setup that makes the difference between discovering an incident from a user report and discovering it from a monitor.

What observability means for this architecture

The request path for a dashboard load spans five distinct components:

Vue app (browser)
  └── fetch /api/dashboard
        └── BFF (.NET Core on ACI)
              ├── UserServiceClient     → User Service
              ├── NotificationClient    → Notification Service
              ├── CourseServiceClient   → Course Service
              └── SessionServiceClient  → Session Service

Full observability means being able to answer these questions from a single tool:

• Which upstream service caused this request to fail or slow down?

• What was the exact sequence of events for request X-Correlation-Id: abc-123?

• Is the BFF's p95 latency within the defined budget for this week?

• How many requests returned partial failures in the last 24 hours?

• Did the 2am deployment degrade response times compared to before?

Application Insights can answer all of these — but only if the telemetry is structured correctly from the start. Unstructured logs and missing correlation IDs produce a tool that has data but cannot connect it.

Serilog: structured logging foundation

Install the packages established in Article 4's Program.cs, plus the destructuring policy for request logging:

dotnet add package Serilog.AspNetCore
dotnet add package Serilog.Sinks.ApplicationInsights
dotnet add package Serilog.Enrichers.Environment
dotnet add package Serilog.Enrichers.Process
dotnet add package Serilog.Enrichers.Thread

Full Serilog configuration

The Serilog configuration in Program.cs merges static enrichers, dynamic log context enrichers, and the Application Insights sink:

// Program.cs
builder.Host.UseSerilog((ctx, services, cfg) => cfg
    .ReadFrom.Configuration(ctx.Configuration)
    .ReadFrom.Services(services)
    .Enrich.FromLogContext()
    .Enrich.WithMachineName()
    .Enrich.WithEnvironmentName()
    .Enrich.WithProperty("Service",     "bff")
    .Enrich.WithProperty("Version",     ctx.Configuration["AppVersion"] ?? "unknown")
    .Enrich.WithProperty("Environment", ctx.HostingEnvironment.EnvironmentName)
    .WriteTo.Console(new RenderedCompactJsonFormatter())
    .WriteTo.ApplicationInsights(
        services.GetRequiredService<TelemetryConfiguration>(),
        TelemetryConverter.Traces,
        restrictedToMinimumLevel: LogEventLevel.Information));

The AppVersion property — injected as an environment variable in the ACI deployment — is the deployed image tag (the Git commit SHA from Article 7). Every log entry carries it. When a regression appears in Application Insights, filtering by Version immediately isolates whether the regression started with a specific deployment.

appsettings.json: log level configuration

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.Hosting.Lifetime": "Information",
        "System": "Warning",
        "System.Net.Http": "Warning"
      }
    }
  }
}

The System.Net.Http override is important. Without it, every outgoing HTTP request from the typed clients emits verbose debug logs about connection pools, headers, and DNS resolution — the majority of which are noise in production. Setting it to Warning keeps the log volume manageable and the signal-to-noise ratio high.

Structured log messages: writing for queryability

The difference between a log entry that helps and one that does not is almost entirely in whether its properties can be queried independently. Serilog's message template syntax — curly braces with named properties — is the mechanism.

// ✗ Unstructured — cannot be queried by orgId or courseCount
_logger.LogInformation($"Fetched {courses.Count} courses for org {orgId}");

// ✓ Structured — orgId and courseCount are queryable properties
_logger.LogInformation(
    "Fetched {CourseCount} courses for organisation {OrgId}",
    courses.Count, orgId);

In Application Insights, the structured version produces a customDimensions object with CourseCount and OrgId as named fields. A Kusto query can then aggregate course fetch counts by organisation, find organisations with unusually low course counts, or identify correlation between slow responses and specific organisations.

Aggregator-level logging

The aggregator logs the complete outcome of each aggregation — duration, upstream call results, partial failures — as a single structured entry:

// Aggregators/DashboardAggregator.cs
public async Task<DashboardResponse> AggregateAsync(
    string userId, CancellationToken ct = default)
{
    var sw = Stopwatch.StartNew();
    var partialFailures = new List<string>();

    using var _ = _logger.BeginScope(new Dictionary<string, object>
    {
        ["UserId"] = userId,
        ["AggregationType"] = "Dashboard"
    });

    _logger.LogInformation("Dashboard aggregation started for user {UserId}", userId);

    // ... aggregation logic from Article 4 ...

    sw.Stop();
    _logger.LogInformation(
        "Dashboard aggregation completed. " +
        "Duration: {DurationMs}ms, " +
        "CourseCount: {CourseCount}, " +
        "SessionCount: {SessionCount}, " +
        "NotificationCount: {NotificationCount}, " +
        "PartialFailures: {PartialFailureCount}, " +
        "FailedServices: {FailedServices}",
        sw.ElapsedMilliseconds,
        response.Courses.Count,
        response.UpcomingSessions.Count,
        response.Notifications.Count,
        partialFailures.Count,
        string.Join(",", partialFailures));

    return response;
}

Every aggregation produces exactly one completion log entry. In Application Insights, a query over DurationMs for these entries produces an accurate latency distribution for the dashboard endpoint across every upstream combination. No APM agent or custom metric is required — the structured log is the metric.

Correlation IDs: threading the trace

The CorrelationIdMiddleware from Article 4 ensures every request has a correlation ID. The missing piece in that implementation was propagating the ID through to Application Insights so log entries and dependency calls are all linked under the same operation.

Wiring the correlation ID to Application Insights operation ID

Application Insights uses Activity from System.Diagnostics as its distributed tracing primitive. The Activity.Current.Id is the operation ID that links all telemetry for a single request. The correlation ID middleware should use this ID rather than generating its own:

// Middleware/CorrelationIdMiddleware.cs — updated
public sealed class CorrelationIdMiddleware(RequestDelegate next)
{
    private const string CorrelationIdHeader = "X-Correlation-Id";

    public async Task InvokeAsync(HttpContext ctx)
    {
        // Prefer the inbound header (set by Front Door or API client)
        // Fall back to the Activity ID created by ASP.NET Core's tracing
        var correlationId =
            ctx.Request.Headers[CorrelationIdHeader].FirstOrDefault()
            ?? Activity.Current?.Id
            ?? ctx.TraceIdentifier;

        // Set it on the current Activity so Application Insights picks it up
        Activity.Current?.SetTag("correlation.id", correlationId);

        // Add to the Serilog log context for every log entry in this request
        using (LogContext.PushProperty("CorrelationId", correlationId))
        {
            ctx.Response.Headers[CorrelationIdHeader] = correlationId;
            await next(ctx);
        }
    }
}

With this wiring, searching Application Insights for a specific correlation ID surfaces:

• The incoming BFF request (as a request telemetry item)

• Every LogInformation / LogWarning entry during that request (as trace items)

• Every outgoing HTTP call to an upstream service (as dependency items)

All linked under the same operation_Id. This is the end-to-end trace.

Application Insights: SDK configuration

The Application Insights SDK auto-collects request telemetry, dependency calls, and exceptions. Configure it in Program.cs:

// Program.cs
builder.Services.AddApplicationInsightsTelemetry(options =>
{
    options.ConnectionString =
        builder.Configuration["ApplicationInsights:ConnectionString"];
    options.EnableAdaptiveSampling = false; // Disable sampling in production BFF
    options.EnableDependencyTrackingTelemetryModule = true;
    options.EnableRequestTrackingTelemetryModule    = true;
});

// Add a telemetry initialiser to enrich every telemetry item
// with the same properties Serilog adds to log entries
builder.Services.AddSingleton<ITelemetryInitializer, BffTelemetryInitializer>();

// Telemetry/BffTelemetryInitializer.cs
public sealed class BffTelemetryInitializer(IConfiguration config) : ITelemetryInitializer
{
    private readonly string _version     = config["AppVersion"] ?? "unknown";
    private readonly string _environment = config["ASPNETCORE_ENVIRONMENT"] ?? "Production";

    public void Initialize(ITelemetry telemetry)
    {
        telemetry.Context.Cloud.RoleName    = "bff";
        telemetry.Context.Component.Version = _version;

        if (telemetry is ISupportProperties props)
        {
            props.Properties["Service"]     = "bff";
            props.Properties["Version"]     = _version;
            props.Properties["Environment"] = _environment;
        }
    }
}

EnableAdaptiveSampling = false is a deliberate choice for a BFF. Adaptive sampling reduces telemetry volume by dropping a percentage of requests — which is appropriate for high-volume services where cost is a concern. A BFF serving an education platform with a bounded user base generates manageable telemetry volume. Disabling sampling means every request, every dependency call, and every exception is recorded — which is the correct trade-off when the primary goal is incident diagnosis rather than cost management.

RoleName = "bff" ensures that in Application Insights' Application Map, the BFF node is labelled correctly and distinct from the upstream services. Without this, every service in the map appears as a generic unnamed cloud role.

Custom telemetry: tracking aggregation outcomes

The SDK auto-tracks requests and dependencies. What it cannot track automatically is the business-level outcome of an aggregation — how many partial failures occurred, how long each upstream phase took, which upstream service was the slowest on a given request. Custom metrics fill this gap.

// Telemetry/AggregationTelemetry.cs
public sealed class AggregationTelemetryService(TelemetryClient telemetryClient)
{
    public void TrackDashboardAggregation(
        string userId,
        long durationMs,
        int courseCount,
        int sessionCount,
        IReadOnlyList<string> partialFailures)
    {
        // Custom event — queryable by name in Application Insights
        var evt = new EventTelemetry("DashboardAggregationCompleted");
        evt.Properties["UserId"]             = userId;
        evt.Properties["PartialFailures"]    = string.Join(",", partialFailures);
        evt.Properties["HasPartialFailure"]  = (partialFailures.Count > 0).ToString();
        evt.Metrics["DurationMs"]            = durationMs;
        evt.Metrics["CourseCount"]           = courseCount;
        evt.Metrics["SessionCount"]          = sessionCount;
        evt.Metrics["PartialFailureCount"]   = partialFailures.Count;
        telemetryClient.TrackEvent(evt);

        // Custom metric — appears in Metrics Explorer for trending
        telemetryClient.GetMetric("DashboardAggregation.DurationMs")
            .TrackValue(durationMs);

        if (partialFailures.Count > 0)
        {
            telemetryClient.GetMetric("DashboardAggregation.PartialFailures")
                .TrackValue(partialFailures.Count);

            foreach (var service in partialFailures)
            {
                var failureEvt = new EventTelemetry("UpstreamServiceFailure");
                failureEvt.Properties["Service"]    = service;
                failureEvt.Properties["Endpoint"]   = "Dashboard";
                failureEvt.Properties["UserId"]     = userId;
                telemetryClient.TrackEvent(failureEvt);
            }
        }
    }

    public IOperationHolder<DependencyTelemetry> TrackUpstreamPhase(
        string phaseName, string upstreamService)
    {
        var dependency = new DependencyTelemetry
        {
            Name   = $"{upstreamService} - {phaseName}",
            Type   = "BFF Aggregation Phase",
            Target = upstreamService
        };
        return telemetryClient.StartOperation(dependency);
    }
}

Inject and use in the aggregator:

// Aggregators/DashboardAggregator.cs — updated with custom telemetry
public async Task<DashboardResponse> AggregateAsync(
    string userId, CancellationToken ct = default)
{
    var sw = Stopwatch.StartNew();
    var partialFailures = new List<string>();

    // Phase 1: independent calls with per-phase timing
    using var phase1 = _telemetry.TrackUpstreamPhase("Phase1-Parallel", "User+Notification");
    var profileTask      = _userClient.GetProfileAsync(userId, ct);
    var notificationTask = _notificationClient.GetUnreadCountAsync(userId, ct);
    await Task.WhenAll(profileTask, notificationTask);
    phase1.Telemetry.Success = true;

    var profile = profileTask.Result;
    if (profile is null)
    {
        _telemetryService.TrackEvent("DashboardAggregationFailed",
            new Dictionary<string, string>
            {
                ["Reason"]  = "ProfileServiceUnavailable",
                ["UserId"]  = userId
            });
        throw new BffAggregationException("User profile service unavailable.");
    }

    // Phase 2
    using var phase2 = _telemetry.TrackUpstreamPhase("Phase2-Courses", "CourseService");
    var courses = await _courseClient.GetCoursesByOrgAsync(profile.OrgId, ct);
    phase2.Telemetry.Success = courses is not null;
    if (courses is null) partialFailures.Add("courses");

    // Phase 3
    IReadOnlyList<SessionDto>? sessions = null;
    if (courses is not null && courses.Count > 0)
    {
        using var phase3 = _telemetry.TrackUpstreamPhase("Phase3-Sessions", "SessionService");
        sessions = await _sessionClient.GetUpcomingAsync(
            courses.Select(c => c.Id).ToArray(), 3, ct);
        phase3.Telemetry.Success = sessions is not null;
        if (sessions is null) partialFailures.Add("sessions");
    }

    var response = BuildResponse(profile, courses, sessions,
        notificationTask.Result, partialFailures);

    sw.Stop();
    _telemetryService.TrackDashboardAggregation(
        userId, sw.ElapsedMilliseconds,
        response.Courses.Count, response.UpcomingSessions.Count,
        partialFailures);

    return response;
}

Each aggregation phase is now a named dependency item in Application Insights. The Application Map shows the BFF node, its dependency on Phase1-Parallel, Phase2-Courses, and Phase3-Sessions, and the duration of each phase for each request. When a dashboard load is slow, the map immediately identifies which phase — and therefore which upstream service — is responsible.

Request logging: the Serilog request pipeline

UseSerilogRequestLogging() replaces ASP.NET Core's default request logging with Serilog's structured equivalent. Configure it to include the correlation ID and response size:

// Program.cs
app.UseSerilogRequestLogging(opts =>
{
    opts.EnrichDiagnosticContext = (diagCtx, httpCtx) =>
    {
        diagCtx.Set("RequestHost",     httpCtx.Request.Host.Value);
        diagCtx.Set("RequestScheme",   httpCtx.Request.Scheme);
        diagCtx.Set("UserAgent",       httpCtx.Request.Headers.UserAgent.ToString());
        diagCtx.Set("CorrelationId",
            httpCtx.Response.Headers["X-Correlation-Id"].FirstOrDefault() ?? "none");

        if (httpCtx.User.Identity?.IsAuthenticated == true)
            diagCtx.Set("UserId",
                httpCtx.User.FindFirstValue(ClaimTypes.NameIdentifier));
    };

    // Suppress health probe logs — they are noise at 30s intervals
    opts.GetLevel = (httpCtx, elapsed, ex) =>
    {
        if (httpCtx.Request.Path.StartsWithSegments("/health"))
            return LogEventLevel.Verbose; // Verbose is below minimum level — effectively suppressed
        if (ex is not null || httpCtx.Response.StatusCode >= 500)
            return LogEventLevel.Error;
        if (httpCtx.Response.StatusCode >= 400)
            return LogEventLevel.Warning;
        return LogEventLevel.Information;
    };
});

The health probe suppression is not cosmetic. At 30-second intervals, health probes generate 2,880 log entries per day per instance — entries that contain no operational information and inflate the Application Insights ingestion cost. Suppressing them by setting their level to Verbose (below the Information minimum) keeps the log volume meaningful.

Tracking the Vue application: browser telemetry

Application Insights has a JavaScript SDK that tracks client-side page loads, AJAX requests, and exceptions. Installing it in the Vue application completes the end-to-end trace — a slow page load can now be correlated with the specific BFF request that served it.

npm install @microsoft/applicationinsights-web

// src/telemetry/appInsights.ts
import { ApplicationInsights } from '@microsoft/applicationinsights-web'

export const appInsights = new ApplicationInsights({
  config: {
    connectionString: import.meta.env.VITE_APPINSIGHTS_CONNECTION_STRING,
    enableAutoRouteTracking: true,    // Track Vue Router navigations as page views
    enableCorsCorrelation: true,      // Propagate correlation headers on fetch calls
    correlationHeaderExcludedDomains: ['*.dataporten.no'], // Don't add headers to Feide
    disableFetchTracking: false,      // Track all fetch calls (BFF API calls)
    enableRequestHeaderTracking: true,
    enableResponseHeaderTracking: true
  }
})

appInsights.loadAppInsights()

// src/main.ts
import { appInsights } from './telemetry/appInsights'
import { useSessionStore } from './stores/session'

appInsights.trackPageView()

// Set the authenticated user context once the session is known
// This links all telemetry from this browser session to the user
const app = createApp(App)
app.use(pinia)
app.use(router)

const session = useSessionStore()
session.initialise().then(() => {
  if (session.profile) {
    appInsights.setAuthenticatedUserContext(
      session.profile.principalName,
      session.profile.orgId,
      true // Store in cookie for cross-session correlation
    )
  }
})

app.mount('#app')

enableCorsCorrelation: true is the key setting. With this enabled, the Application Insights SDK automatically adds Request-Context and Request-Id headers to every fetch call the Vue application makes. The BFF receives these headers and links its server-side telemetry to the same operation ID as the browser-side telemetry. In Application Insights' end-to-end transaction view, a single operation shows the browser page load, the fetch /api/dashboard call, and every upstream dependency the BFF triggered — all as one unified trace.

Kusto queries: turning telemetry into answers

The Application Insights data model is queried with Kusto Query Language (KQL). The following queries are the ones that were actually pinned to the production dashboard and alerted on.

BFF request latency by endpoint

requests
| where timestamp > ago(24h)
| where cloud_RoleName == "bff"
| where name !contains "health"
| summarize
    p50  = percentile(duration, 50),
    p95  = percentile(duration, 95),
    p99  = percentile(duration, 99),
    count = count()
    by name
| order by p95 desc

This query identifies which BFF endpoints are slowest at the p95 level — the level that matters for real user experience, not average which hides tail latency.

Partial failure rate over time

customEvents
| where timestamp > ago(24h)
| where name == "UpstreamServiceFailure"
| summarize failureCount = count() by
    Service = tostring(customDimensions["Service"]),
    bin(timestamp, 1h)
| render timechart

This is the alert query. When CourseService partial failures spike from 0 to 40 in an hour, the chart shows the exact moment the upstream service degraded — before any user report arrives.

Aggregation duration distribution

customEvents
| where timestamp > ago(24h)
| where name == "DashboardAggregationCompleted"
| extend
    durationMs   = todouble(customMeasurements["DurationMs"]),
    hasFailure   = tobool(customDimensions["HasPartialFailure"])
| summarize
    p50  = percentile(durationMs, 50),
    p95  = percentile(durationMs, 95),
    count = count()
    by hasFailure

This reveals something the standard latency query does not: whether partial failures (degraded responses) are faster or slower than fully successful responses. In the production system, partial failures were consistently faster because the failed upstream service had timed out rather than returned slowly — the timeout was the signal, not the duration. This query made that visible.

Error rate by status code

requests
| where timestamp > ago(1h)
| where cloud_RoleName == "bff"
| summarize count() by resultCode
| render piechart

A simple query, but critical for incident triage. A spike in 503s identifies a BFF-level failure (upstream services down). A spike in 401s identifies an authentication issue. A spike in 500s identifies an unhandled exception in the BFF itself.

End-to-end trace for a specific correlation ID

let correlationId = "abc-123-def-456";
union requests, dependencies, traces, exceptions
| where timestamp > ago(24h)
| where operation_Id contains correlationId
    or customDimensions["CorrelationId"] == correlationId
| order by timestamp asc
| project timestamp, itemType, name, duration, success,
          message, customDimensions

This is the incident diagnosis query. A user reports an error at 14:32 and provides the correlation ID from the UI (the traceId in the ErrorDisplay component from Article 5). This query returns every telemetry item — request, dependency calls, log entries, exceptions — for that specific request, in chronological order.

Dashboard configuration

The production Application Insights workbook had four panels pinned for daily review and incident response:

Panel 1: Request volume and error rate (30-minute bins)

requests
| where cloud_RoleName == "bff"
| where name !contains "health"
| summarize
    total     = count(),
    errors    = countif(success == false),
    errorRate = round(100.0 * countif(success == false) / count(), 2)
    by bin(timestamp, 30m)
| render timechart with (series = errorRate)

Panel 2: Upstream service availability

dependencies
| where cloud_RoleName == "bff"
| where type == "Http"
| summarize
    total   = count(),
    failed  = countif(success == false),
    failPct = round(100.0 * countif(success == false) / count(), 2)
    by target, bin(timestamp, 1h)
| where failed > 0
| order by failPct desc

Panel 3: Aggregation latency heatmap

customEvents
| where name == "DashboardAggregationCompleted"
| extend durationMs = todouble(customMeasurements["DurationMs"])
| summarize count() by
    latencyBucket = case(
        durationMs < 200,   "< 200ms",
        durationMs < 500,   "200–500ms",
        durationMs < 1000,  "500ms–1s",
        durationMs < 2000,  "1–2s",
        ">= 2s"),
    bin(timestamp, 1h)
| render timechart

Panel 4: Top exceptions in the last hour

exceptions
| where cloud_RoleName == "bff"
| where timestamp > ago(1h)
| summarize count() by type, outerMessage
| order by count_ desc
| take 10

Alerts

Three alerts were active in the production system. Each was configured in Azure Monitor with an action group that sent an email and a Teams webhook notification.

Alert 1: Error rate threshold

// Fires when error rate exceeds 5% over a 5-minute window
requests
| where cloud_RoleName == "bff"
| where name !contains "health"
| where timestamp > ago(5m)
| summarize
    total  = count(),
    errors = countif(success == false)
| extend errorRate = 100.0 * errors / total
| where errorRate > 5

Threshold: 5% error rate. Evaluation frequency: every 5 minutes. Severity: 2 (High).

Alert 2: Upstream service degradation

// Fires when any upstream service fails more than 10 times in 10 minutes
customEvents
| where name == "UpstreamServiceFailure"
| where timestamp > ago(10m)
| summarize failureCount = count() by Service = tostring(customDimensions["Service"])
| where failureCount > 10

Threshold: 10 failures. Evaluation frequency: every 5 minutes. Severity: 1 (Critical).

This alert fires before the error rate alert in most upstream outage scenarios. When the course service goes down, the first few dozen requests produce partial failure responses (200 with partialFailures: ["courses"]) rather than 5xx errors. The error rate alert would not fire; this alert catches the upstream degradation regardless of whether the BFF successfully served a degraded response.

Alert 3: Aggregation latency budget

// Fires when p95 aggregation duration exceeds 1500ms over 15 minutes
customEvents
| where name == "DashboardAggregationCompleted"
| where timestamp > ago(15m)
| summarize p95 = percentile(todouble(customMeasurements["DurationMs"]), 95)
| where p95 > 1500

Threshold: 1500ms p95. Evaluation frequency: every 5 minutes. Severity: 2 (High).

The 1500ms threshold was derived from the production latency budget: 300ms for Phase 1, 300ms for Phase 2, 300ms for Phase 3, 600ms buffer for BFF processing and network. When p95 exceeds 1500ms, one of the upstream services is slow — the dependency telemetry identifies which one.

What the production system learned about observability

Health probe log suppression was added after the first week. The initial configuration logged every health probe at Information level. After one week of ACI deployment with 30-second probe intervals, the Application Insights log volume was 40% health probe entries. The GetLevel override was added in week two and immediately reduced ingestion cost and improved signal clarity.

The AppVersion property on every telemetry item paid off in the third deployment. A latency regression appeared in the p95 chart after the third deployment to production. Filtering customEvents by Version == "sha-abc123" versus Version == "sha-def456" isolated the regression to the new deployment within two minutes. Without the version property, the investigation would have started with checking the deployment log to determine when the regression began.

Partial failure alerts preceded user reports by an average of 12 minutes. In the three upstream service degradations that occurred during the production period, the UpstreamServiceFailure alert fired an average of 12 minutes before any user submitted a support ticket. In two of the three cases, the upstream team was already aware before the first user contacted support. The BFF's partial failure model — returning degraded responses rather than errors — meant users experienced degraded functionality rather than outages, reducing the severity of each incident.

setAuthenticatedUserContext was not added until month two. The browser-side Application Insights setup initially did not set the authenticated user context. This meant browser telemetry could not be correlated with a specific user's session when investigating a reported issue. Adding setAuthenticatedUserContext after month two connected the browser page view telemetry to the same user ID used in server-side logs — making the end-to-end trace genuinely end-to-end.

The complete observability picture

A production incident on this system — a user reports the dashboard is slow — resolves as follows:

1. The user reads the traceId from the error display or the support team extracts it from the correlation ID in the request log.

2. The end-to-end trace query returns every item for that request in 3 seconds.

3. The dependency telemetry shows Phase 3 (Sessions) took 2,400ms — the session service was the culprit.

4. The upstream service failure alert fired 8 minutes before the user reported the issue.

5. The session service team's runbook is triggered.

6. Resolution.

This is what observability looks like when it is designed in rather than added later. Every decision in this series — structured logs, correlation IDs, custom aggregation events, the traceId in the Vue error component, the AppVersion on every telemetry item — was made with this incident resolution flow in mind.

Series conclusion

This is the ninth and final article in the core series. The BFF is designed, built, secured, deployed, tested, and observable. What was built:

• A Vue 3 frontend with a typed API layer generated from the BFF's OpenAPI spec, composables with consistent error handling, and browser telemetry connected to the server-side trace.

• A .NET Core 8 BFF with Minimal API endpoints, a typed client / aggregator / contract architecture, Feide OIDC integration using the Token Handler pattern, and a layered test suite from unit through contract.

• An Azure IaaS deployment with Azure Container Instances, Azure Front Door, and a full CI/CD pipeline from commit to production with a manual approval gate.

• An observability layer with Serilog structured logging, distributed tracing via Activity and correlation IDs, custom Application Insights telemetry, and production-validated KQL queries and alerts.

The three supplementary articles — caching strategies, brownfield migration with the Strangler Fig pattern, and resilience patterns with Polly — extend the architecture into the production scenarios most likely to arise once the core system is running. They are written to be read independently as those needs arise.

☰ Series navigation

A note on the code in this article. The testing strategy, test fixtures, and code examples shown here are derived from a production BFF built for a Norwegian enterprise education platform. Service names, domain models, and certain structural details have been generalised to meet NDA obligations. The test architecture, WebApplicationFactory configuration, Pact contract setup, and the specific failure modes each test layer is designed to catch are drawn directly from what was written and maintained in production.

A BFF sits at a boundary. On one side, the Vue application depends on it for every piece of data it renders. On the other side, it depends on upstream services it does not own. Both sides of that boundary can change. Both sides have broken production in real systems that lacked the test coverage to catch the breakage before deployment.

The testing strategy for a BFF is therefore not the same as for an isolated service. It has to answer three distinct questions that a single testing layer cannot answer alone: does the aggregation logic produce the right output given specific inputs? does the running service behave correctly end to end with real HTTP machinery? and does the contract the BFF exposes to the Vue application stay stable as both sides evolve independently?

This article builds a layered answer to those three questions — unit tests for the aggregation and shaping logic, integration tests using WebApplicationFactory for the full HTTP pipeline, and consumer-driven contract tests using Pact to enforce the Vue-to-BFF contract at the CI level.

The testing pyramid, applied to a BFF

The standard testing pyramid — many unit tests, fewer integration tests, fewest end-to-end tests — applies to BFF testing with one modification: contract tests sit alongside integration tests, not above them. They are not end-to-end tests. They are fast, isolated, and run in CI. They occupy a distinct position in the pyramid because they address a concern that neither unit nor integration tests cover: whether the two independent codebases (the BFF and the Vue application) agree on the shape of their shared interface.

           ┌──────────────┐
           │   E2E tests  │  ← Minimal — Playwright smoke tests only
           └──────────────┘
      ┌──────────────────────┐
      │  Integration tests   │  ← WebApplicationFactory, full HTTP pipeline
      │  Contract tests      │  ← Pact, Vue↔BFF interface verification
      └──────────────────────┘
  ┌──────────────────────────────┐
  │        Unit tests            │  ← Aggregators, shaping logic, error handling
  └──────────────────────────────┘

Each layer catches a different class of failure. Unit tests catch logic errors in isolation. Integration tests catch wiring errors — misconfigured middleware, incorrect route mapping, broken serialisation. Contract tests catch interface drift — changes to either side that invalidate the shared contract. None of these layers is redundant with the others.

Project setup

The test projects mirror the source project structure. Each concern gets its own project with its own dependencies:

dotnet new xunit -n EducationPlatform.Bff.UnitTests
dotnet new xunit -n EducationPlatform.Bff.IntegrationTests
dotnet new xunit -n EducationPlatform.Bff.ContractTests

# Unit test dependencies
cd EducationPlatform.Bff.UnitTests
dotnet add reference ../EducationPlatform.Bff
dotnet add package NSubstitute
dotnet add package FluentAssertions

# Integration test dependencies
cd ../EducationPlatform.Bff.IntegrationTests
dotnet add reference ../EducationPlatform.Bff
dotnet add package Microsoft.AspNetCore.Mvc.Testing
dotnet add package NSubstitute
dotnet add package FluentAssertions

# Contract test dependencies (provider side)
cd ../EducationPlatform.Bff.ContractTests
dotnet add reference ../EducationPlatform.Bff
dotnet add package PactNet
dotnet add package Microsoft.AspNetCore.Mvc.Testing

Layer 1: Unit tests

Unit tests cover the aggregation logic and response shaping in isolation. The subjects under test are the aggregators — the classes that orchestrate upstream calls, handle partial failures, and shape responses into the Vue contract. The upstream clients are substituted with NSubstitute mocks.

Testing the happy path

// EducationPlatform.Bff.UnitTests/Aggregators/DashboardAggregatorTests.cs
public class DashboardAggregatorTests
{
    private readonly UserServiceClient _userClient;
    private readonly CourseServiceClient _courseClient;
    private readonly SessionServiceClient _sessionClient;
    private readonly NotificationServiceClient _notificationClient;
    private readonly DashboardAggregator _aggregator;

    public DashboardAggregatorTests()
    {
        _userClient         = Substitute.For<UserServiceClient>();
        _courseClient       = Substitute.For<CourseServiceClient>();
        _sessionClient      = Substitute.For<SessionServiceClient>();
        _notificationClient = Substitute.For<NotificationServiceClient>();

        _aggregator = new DashboardAggregator(
            _userClient,
            _courseClient,
            _sessionClient,
            _notificationClient,
            Substitute.For<ILogger<DashboardAggregator>>());
    }

    [Fact]
    public async Task AggregateAsync_AllServicesAvailable_ReturnsMappedResponse()
    {
        // Arrange
        const string userId = "ingrid.solberg@skole.no";

        _userClient.GetProfileAsync(userId, Arg.Any<CancellationToken>())
            .Returns(new UserProfileDto(
                "Ingrid", "Solberg",
                OrgId: "uninett",
                RoleCode: "TEACHER",
                AvatarPath: "i-solberg.jpg"));

        _notificationClient.GetUnreadCountAsync(userId, Arg.Any<CancellationToken>())
            .Returns(3);

        _courseClient.GetCoursesByOrgAsync("uninett", Arg.Any<CancellationToken>())
            .Returns([
                new CourseDto("c-1",
                    new CourseMetadataDto("Mathematics — Year 9", "MATH-9", null!),
                    new EnrollmentDto(30, 24, 0),
                    new CourseStatusDto("ACTIVE", DateTimeOffset.UtcNow))
            ]);

        _sessionClient.GetUpcomingAsync(
                Arg.Is<string[]>(ids => ids.Contains("c-1")),
                3,
                Arg.Any<CancellationToken>())
            .Returns([
                new SessionDto("s-1", "Integration review",
                    DateTimeOffset.Parse("2025-04-08T09:00:00"),
                    "Mathematics — Year 9", Room: "204")
            ]);

        // Act
        var result = await _aggregator.AggregateAsync(userId);

        // Assert
        result.User.DisplayName.Should().Be("Ingrid Solberg");
        result.User.Role.Should().Be("Teacher");
        result.User.AvatarUrl.Should().Be("/media/avatars/i-solberg.jpg");

        result.Courses.Should().HaveCount(1);
        result.Courses[0].Title.Should().Be("Mathematics — Year 9");
        result.Courses[0].EnrollmentLabel.Should().Be("24 / 30");
        result.Courses[0].EnrollmentPercent.Should().Be(80);
        result.Courses[0].Status.Should().Be("Active");

        result.UpcomingSessions.Should().HaveCount(1);
        result.UpcomingSessions[0].LocationLabel.Should().Be("Room 204");

        result.Notifications.Count.Should().Be(3);
        result.PartialFailures.Should().BeEmpty();
    }
}

Testing partial failure handling

This is the test the happy-path test cannot catch: what happens when an upstream service returns null — either due to unavailability or a resilience handler exhausting its retries.

[Fact]
public async Task AggregateAsync_CourseServiceUnavailable_ReturnsDegradedResponse()
{
    // Arrange
    const string userId = "ingrid.solberg@skole.no";

    _userClient.GetProfileAsync(userId, Arg.Any<CancellationToken>())
        .Returns(new UserProfileDto("Ingrid", "Solberg", "uninett", "TEACHER", null));

    _notificationClient.GetUnreadCountAsync(userId, Arg.Any<CancellationToken>())
        .Returns(0);

    // Course service unavailable — client returns null
    _courseClient.GetCoursesByOrgAsync("uninett", Arg.Any<CancellationToken>())
        .Returns((IReadOnlyList<CourseDto>?)null);

    // Act
    var result = await _aggregator.AggregateAsync(userId);

    // Assert — response is still structurally valid
    result.Should().NotBeNull();
    result.User.DisplayName.Should().Be("Ingrid Solberg");
    result.Courses.Should().BeEmpty();
    result.UpcomingSessions.Should().BeEmpty(); // No courses → no sessions fetched
    result.PartialFailures.Should().Contain("courses");

    // Session service should not have been called — no course IDs to query with
    await _sessionClient.DidNotReceive()
        .GetUpcomingAsync(Arg.Any<string[]>(), Arg.Any<int>(), Arg.Any<CancellationToken>());
}

[Fact]
public async Task AggregateAsync_ProfileServiceUnavailable_ThrowsBffAggregationException()
{
    // Arrange
    _userClient.GetProfileAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
        .Returns((UserProfileDto?)null);

    _notificationClient.GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
        .Returns(0);

    // Act & Assert — profile is required; its absence is a hard failure
    await _aggregator.Invoking(a => a.AggregateAsync("any-user"))
        .Should().ThrowAsync<BffAggregationException>()
        .WithMessage("*User profile service unavailable*");
}

Testing response shaping

Shaping logic deserves its own tests, independent of aggregation orchestration. The shaping methods were private in the production aggregator — testing them through the public AggregateAsync method is correct, but targeted shaping tests are faster to write and easier to read when verifying edge cases:

[Theory]
[InlineData(30, 30, 100)]
[InlineData(0,  30, 0)]
[InlineData(24, 30, 80)]
[InlineData(1,  3,  33)]   // Rounds correctly
[InlineData(0,  0,  0)]    // Zero capacity — no division by zero
public async Task AggregateAsync_EnrollmentPercent_CalculatesCorrectly(
    int enrolled, int capacity, int expectedPercent)
{
    // Arrange
    SetupValidProfile("test-user");
    _notificationClient.GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
        .Returns(0);
    _courseClient.GetCoursesByOrgAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
        .Returns([new CourseDto("c-1",
            new CourseMetadataDto("Test Course", "TC-1", null!),
            new EnrollmentDto(capacity, enrolled, 0),
            new CourseStatusDto("ACTIVE", DateTimeOffset.UtcNow))]);
    _sessionClient.GetUpcomingAsync(Arg.Any<string[]>(), Arg.Any<int>(), Arg.Any<CancellationToken>())
        .Returns([]);

    // Act
    var result = await _aggregator.AggregateAsync("test-user");

    // Assert
    result.Courses[0].EnrollmentPercent.Should().Be(expectedPercent);
}

[Theory]
[InlineData("TEACHER",  "Teacher")]
[InlineData("STUDENT",  "Student")]
[InlineData("ADMIN",    "Administrator")]
[InlineData("UNKNOWN",  "Unknown")]
[InlineData("",         "Unknown")]
public async Task AggregateAsync_RoleTranslation_MapsCorrectly(
    string roleCode, string expectedRole)
{
    SetupValidProfile("test-user", roleCode: roleCode);
    _notificationClient.GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
        .Returns(0);
    _courseClient.GetCoursesByOrgAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
        .Returns([]);

    var result = await _aggregator.AggregateAsync("test-user");

    result.User.Role.Should().Be(expectedRole);
}

private void SetupValidProfile(string userId, string roleCode = "TEACHER") =>
    _userClient.GetProfileAsync(userId, Arg.Any<CancellationToken>())
        .Returns(new UserProfileDto("Test", "User", "uninett", roleCode, null));

The [Theory] / [InlineData] pattern is the right tool for shaping edge cases — it tests the same logic with multiple inputs without duplicating test structure. The division-by-zero case (0 / 0) is the one that caused a production exception in an early deployment; it is now a first-class test case.

Layer 2: Integration tests with WebApplicationFactory

Integration tests verify the full HTTP pipeline: middleware execution order, route mapping, authentication enforcement, serialisation, and error handling. They use WebApplicationFactory<Program> from Microsoft.AspNetCore.Mvc.Testing, which hosts the real application in memory with substituted dependencies.

The test factory

// EducationPlatform.Bff.IntegrationTests/BffWebApplicationFactory.cs
public sealed class BffWebApplicationFactory : WebApplicationFactory<Program>
{
    public UserServiceClient UserClient { get; } =
        Substitute.For<UserServiceClient>();
    public CourseServiceClient CourseClient { get; } =
        Substitute.For<CourseServiceClient>();
    public SessionServiceClient SessionClient { get; } =
        Substitute.For<SessionServiceClient>();
    public NotificationServiceClient NotificationClient { get; } =
        Substitute.For<NotificationServiceClient>();

    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureTestServices(services =>
        {
            // Replace real typed clients with substitutes
            services.RemoveAll<UserServiceClient>();
            services.RemoveAll<CourseServiceClient>();
            services.RemoveAll<SessionServiceClient>();
            services.RemoveAll<NotificationServiceClient>();

            services.AddSingleton(UserClient);
            services.AddSingleton(CourseClient);
            services.AddSingleton(SessionClient);
            services.AddSingleton(NotificationClient);

            // Replace real Data Protection with ephemeral keys for tests
            services.AddDataProtection()
                .UseEphemeralDataProtectionProvider();

            // Use test authentication — bypass real Feide OIDC
            services.AddAuthentication("Test")
                .AddScheme<AuthenticationSchemeOptions, TestAuthHandler>(
                    "Test", _ => { });
        });

        builder.UseEnvironment("Testing");
    }
}

The TestAuthHandler simulates an authenticated user without going through the Feide OIDC flow:

// EducationPlatform.Bff.IntegrationTests/TestAuthHandler.cs
public sealed class TestAuthHandler(
    IOptionsMonitor<AuthenticationSchemeOptions> options,
    ILoggerFactory logger,
    UrlEncoder encoder)
    : AuthenticationHandler<AuthenticationSchemeOptions>(options, logger, encoder)
{
    public const string UserId = "ingrid.solberg@skole.no";
    public const string OrgId  = "uninett";

    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        // Check for the test auth header — allows tests to simulate unauthenticated requests
        if (!Request.Headers.ContainsKey("X-Test-Auth"))
            return Task.FromResult(AuthenticateResult.Fail("No test auth header."));

        var claims = new[]
        {
            new Claim(ClaimTypes.NameIdentifier, UserId),
            new Claim(ClaimTypes.Name, "Ingrid Solberg"),
            new Claim(ClaimTypes.Email, "ingrid.solberg@skole.no"),
            new Claim("feidePersonPrincipalName", UserId),
            new Claim("eduPersonPrimaryAffiliation", "staff"),
            new Claim("eduPersonOrgDN", $"dc={OrgId},dc=no")
        };

        var identity  = new ClaimsIdentity(claims, "Test");
        var principal = new ClaimsPrincipal(identity);
        var ticket    = new AuthenticationTicket(principal, "Test");

        return Task.FromResult(AuthenticateResult.Success(ticket));
    }
}

Using a header (X-Test-Auth) to trigger test authentication allows the same factory to test both authenticated and unauthenticated scenarios without changing the factory configuration between tests.

Testing the dashboard endpoint

// EducationPlatform.Bff.IntegrationTests/Endpoints/DashboardEndpointTests.cs
public class DashboardEndpointTests(BffWebApplicationFactory factory)
    : IClassFixture<BffWebApplicationFactory>
{
    private HttpClient CreateAuthenticatedClient() =>
        factory.CreateClient(new WebApplicationFactoryClientOptions
        {
            AllowAutoRedirect = false
        })
        .WithDefaultRequestHeaders(h => h.Add("X-Test-Auth", "true"));

    [Fact]
    public async Task GET_Dashboard_AuthenticatedUser_Returns200WithCorrectShape()
    {
        // Arrange
        factory.UserClient
            .GetProfileAsync(TestAuthHandler.UserId, Arg.Any<CancellationToken>())
            .Returns(new UserProfileDto("Ingrid", "Solberg",
                TestAuthHandler.OrgId, "TEACHER", null));

        factory.NotificationClient
            .GetUnreadCountAsync(TestAuthHandler.UserId, Arg.Any<CancellationToken>())
            .Returns(2);

        factory.CourseClient
            .GetCoursesByOrgAsync(TestAuthHandler.OrgId, Arg.Any<CancellationToken>())
            .Returns([]);

        var client = CreateAuthenticatedClient();

        // Act
        var response = await client.GetAsync("/api/dashboard");

        // Assert
        response.StatusCode.Should().Be(HttpStatusCode.OK);

        var body = await response.Content.ReadFromJsonAsync<DashboardResponse>();
        body.Should().NotBeNull();
        body!.User.DisplayName.Should().Be("Ingrid Solberg");
        body.Notifications.Count.Should().Be(2);
        body.Courses.Should().BeEmpty();
        body.PartialFailures.Should().BeEmpty();
    }

    [Fact]
    public async Task GET_Dashboard_UnauthenticatedRequest_Returns401()
    {
        // Arrange — client without X-Test-Auth header
        var client = factory.CreateClient(new WebApplicationFactoryClientOptions
        {
            AllowAutoRedirect = false
        });

        // Act
        var response = await client.GetAsync("/api/dashboard");

        // Assert
        response.StatusCode.Should().Be(HttpStatusCode.Unauthorized);
    }

    [Fact]
    public async Task GET_Dashboard_ProfileServiceDown_Returns503WithProblemDetails()
    {
        // Arrange — profile service returns null (upstream unavailable)
        factory.UserClient
            .GetProfileAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns((UserProfileDto?)null);

        factory.NotificationClient
            .GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(0);

        var client = CreateAuthenticatedClient();

        // Act
        var response = await client.GetAsync("/api/dashboard");

        // Assert
        response.StatusCode.Should().Be(HttpStatusCode.ServiceUnavailable);

        var problem = await response.Content
            .ReadFromJsonAsync<ProblemDetails>();
        problem!.Title.Should().Be("Upstream service unavailable");
        problem.Status.Should().Be(503);
    }

    [Fact]
    public async Task GET_Dashboard_CourseServiceDown_Returns200WithPartialFailure()
    {
        // Arrange — course service returns null, but profile is available
        factory.UserClient
            .GetProfileAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(new UserProfileDto("Ingrid", "Solberg",
                TestAuthHandler.OrgId, "TEACHER", null));

        factory.NotificationClient
            .GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(0);

        factory.CourseClient
            .GetCoursesByOrgAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns((IReadOnlyList<CourseDto>?)null);

        var client = CreateAuthenticatedClient();

        // Act
        var response = await client.GetAsync("/api/dashboard");

        // Assert — still a 200, not a 503
        response.StatusCode.Should().Be(HttpStatusCode.OK);

        var body = await response.Content.ReadFromJsonAsync<DashboardResponse>();
        body!.Courses.Should().BeEmpty();
        body.PartialFailures.Should().Contain("courses");
    }

    [Fact]
    public async Task GET_Dashboard_ResponseContainsCorrelationIdHeader()
    {
        factory.UserClient
            .GetProfileAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(new UserProfileDto("Ingrid", "Solberg",
                TestAuthHandler.OrgId, "TEACHER", null));
        factory.NotificationClient
            .GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(0);
        factory.CourseClient
            .GetCoursesByOrgAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns([]);

        var client = CreateAuthenticatedClient();
        var requestCorrelationId = Guid.NewGuid().ToString();
        client.DefaultRequestHeaders.Add("X-Correlation-Id", requestCorrelationId);

        var response = await client.GetAsync("/api/dashboard");

        // The same correlation ID must be echoed back in the response
        response.Headers.Should().ContainKey("X-Correlation-Id");
        response.Headers.GetValues("X-Correlation-Id").First()
            .Should().Be(requestCorrelationId);
    }
}

The correlation ID test is worth calling out. It is an integration test concern, not a unit test concern — it verifies that the middleware is registered in the pipeline and executes correctly. A unit test of CorrelationIdMiddleware in isolation would verify the logic; this test verifies the middleware is actually wired into the application.

Layer 3: Consumer-driven contract tests with Pact

Contract tests address a problem that neither unit nor integration tests can: the two independent codebases that share an interface — the Vue application and the BFF — can each pass their own tests while simultaneously breaking the other's expectations.

Consumer-driven contract testing (CDCT) with Pact inverts the usual testing direction. The consumer (Vue application) defines what it expects from the provider (BFF) in a contract file — a Pact. The provider runs that contract against its actual implementation and verifies it is satisfied. Neither side needs to run the other's tests. The contract is the shared artefact.

Consumer side: generating the Pact in Vue

The consumer test runs in the Vue application's test suite using @pact-foundation/pact. It verifies that the Vue composables consume the BFF's response correctly, and in doing so, generates a Pact file describing exactly what the BFF must return.

// frontend/tests/contracts/dashboard.pact.spec.ts
import { PactV3, MatchersV3 } from '@pact-foundation/pact'
import path from 'path'
import { apiClient } from '@/api/client'
import type { DashboardResponse } from '@/api/types'

const { like, eachLike, string, integer, boolean } = MatchersV3

const provider = new PactV3({
  consumer: 'education-platform-vue',
  provider: 'education-platform-bff',
  dir: path.resolve(__dirname, '../../pacts'),
  port: 4321
})

describe('Dashboard contract', () => {
  it('returns a valid dashboard response for an authenticated user', async () => {
    await provider
      .addInteraction({
        states: [{ description: 'user ingrid.solberg@skole.no exists with courses' }],
        uponReceiving: 'a GET request for the dashboard',
        withRequest: {
          method: 'GET',
          path: '/api/dashboard',
          headers: { Accept: 'application/json' }
        },
        willRespondWith: {
          status: 200,
          headers: { 'Content-Type': 'application/json' },
          body: {
            user: like({
              displayName: string('Ingrid Solberg'),
              role:        string('Teacher'),
              avatarUrl:   string('/media/avatars/i-solberg.jpg')
            }),
            courses: eachLike({
              id:                string('c-1'),
              title:             string('Mathematics — Year 9'),
              code:              string('MATH-9'),
              enrollmentLabel:   string('24 / 30'),
              enrollmentPercent: integer(80),
              status:            string('Active')
            }),
            upcomingSessions: eachLike({
              id:            string('s-1'),
              title:         string('Integration review'),
              startsAt:      string('2025-04-08T09:00:00'),
              courseTitle:   string('Mathematics — Year 9'),
              locationLabel: string('Room 204')
            }),
            notifications: like({
              count: integer(3)
            }),
            partialFailures: []
          }
        }
      })
      .executeTest(async mockServer => {
        // Point the API client at the Pact mock server
        const original = globalThis.fetch
        globalThis.fetch = (input, init) => {
          const url = typeof input === 'string'
            ? input.replace('/api', mockServer.url)
            : input
          return original(url, init)
        }

        const data = await apiClient.get<DashboardResponse>('/dashboard')

        // Verify the composable can handle the response
        expect(data.user.displayName).toBeTruthy()
        expect(data.courses).toBeInstanceOf(Array)
        expect(data.notifications.count).toBeGreaterThanOrEqual(0)
        expect(data.partialFailures).toBeInstanceOf(Array)
      })
  })

  it('returns 401 for unauthenticated requests', async () => {
    await provider
      .addInteraction({
        states: [{ description: 'no authenticated session' }],
        uponReceiving: 'an unauthenticated GET request for the dashboard',
        withRequest: {
          method: 'GET',
          path: '/api/dashboard'
        },
        willRespondWith: {
          status: 401,
          body: like({
            title:  string('Unauthorized'),
            status: integer(401)
          })
        }
      })
      .executeTest(async mockServer => {
        const original = globalThis.fetch
        globalThis.fetch = (input, init) =>
          original(typeof input === 'string'
            ? input.replace('/api', mockServer.url) : input, init)

        await expect(
          apiClient.get<DashboardResponse>('/dashboard')
        ).rejects.toMatchObject({ status: 401 })
      })
  })
})

Running this test suite generates a Pact file at pacts/education-platform-vue-education-platform-bff.json. This file is the contract — the formal record of what the Vue application expects.

Provider side: verifying the Pact in the BFF

The BFF verifies the generated Pact against its actual implementation using PactNet and WebApplicationFactory. The verification spins up the real BFF (with substituted upstream clients), executes each interaction defined in the Pact, and asserts the response matches the contract.

// EducationPlatform.Bff.ContractTests/DashboardPactProviderTests.cs
public class DashboardPactProviderTests : IClassFixture<BffWebApplicationFactory>
{
    private readonly BffWebApplicationFactory _factory;
    private readonly ITestOutputHelper _output;

    public DashboardPactProviderTests(
        BffWebApplicationFactory factory,
        ITestOutputHelper output)
    {
        _factory = factory;
        _output  = output;
    }

    [Fact]
    public async Task BFF_SatisfiesVueConsumerContract()
    {
        // Arrange — set up state handlers to satisfy Pact provider states
        SetupProviderStates();

        // Start the BFF on a random port using WebApplicationFactory
        var server = _factory.Server;
        server.BaseAddress = new Uri("http://localhost");

        var config = new PactVerifierConfig
        {
            Outputters = [new XUnitOutput(_output)],
            LogLevel    = PactLogLevel.Information
        };

        var pactPath = Path.Combine(
            Directory.GetCurrentDirectory(),
            "..", "..", "..", "..", "..", // Navigate to repo root
            "frontend", "pacts",
            "education-platform-vue-education-platform-bff.json");

        // Act & Assert
        await new PactVerifier("education-platform-bff", config)
            .WithHttpEndpoint(server.BaseAddress)
            .WithFileSource(new FileInfo(pactPath))
            .WithProviderStateUrl(new Uri(server.BaseAddress, "/pact/provider-states"))
            .VerifyAsync();
    }

    private void SetupProviderStates()
    {
        // "user ingrid.solberg@skole.no exists with courses"
        _factory.UserClient
            .GetProfileAsync("ingrid.solberg@skole.no", Arg.Any<CancellationToken>())
            .Returns(new UserProfileDto("Ingrid", "Solberg", "uninett", "TEACHER",
                "i-solberg.jpg"));

        _factory.CourseClient
            .GetCoursesByOrgAsync("uninett", Arg.Any<CancellationToken>())
            .Returns([
                new CourseDto("c-1",
                    new CourseMetadataDto("Mathematics — Year 9", "MATH-9", null!),
                    new EnrollmentDto(30, 24, 0),
                    new CourseStatusDto("ACTIVE", DateTimeOffset.UtcNow))
            ]);

        _factory.SessionClient
            .GetUpcomingAsync(Arg.Any<string[]>(), 3, Arg.Any<CancellationToken>())
            .Returns([
                new SessionDto("s-1", "Integration review",
                    DateTimeOffset.Parse("2025-04-08T09:00:00"),
                    "Mathematics — Year 9", Room: "204")
            ]);

        _factory.NotificationClient
            .GetUnreadCountAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(3);

        // "no authenticated session" — no setup needed; TestAuthFactory
        // returns 401 for requests without the X-Test-Auth header
    }
}

The provider state endpoint is a lightweight Minimal API registered in the test factory that the Pact verifier calls before each interaction to set up the correct data state:

// BffWebApplicationFactory.cs — add provider state endpoint
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
    builder.ConfigureTestServices(services => { /* ... existing setup ... */ });

    builder.Configure(app =>
    {
        // Provider states endpoint — only registered in test environment
        app.Map("/pact/provider-states", stateApp =>
        {
            stateApp.Run(async ctx =>
            {
                var body = await ctx.Request.ReadFromJsonAsync<ProviderStateRequest>();
                // State setup is handled by the substitute configuration above
                // This endpoint just acknowledges the state transition
                ctx.Response.StatusCode = 200;
                await ctx.Response.WriteAsJsonAsync(new { acknowledged = true });
            });
        });

        app.UseRouting();
        app.UseAuthentication();
        app.UseAuthorization();
        app.UseEndpoints(endpoints => endpoints.MapControllers());
    });
}

private sealed record ProviderStateRequest(string State, string Consumer);

The CI workflow for contract tests

The Pact file flows through CI as an artefact. The Vue consumer tests generate it; the BFF provider tests verify it:

# .github/workflows/contract-tests.yml
name: Contract Tests

on: [push, pull_request]

jobs:
  consumer-generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - name: Install dependencies
        working-directory: ./frontend
        run: npm ci
      - name: Run consumer contract tests
        working-directory: ./frontend
        run: npm run test:contracts
      - name: Upload Pact file
        uses: actions/upload-artifact@v4
        with:
          name: pact-files
          path: frontend/pacts/*.json

  provider-verify:
    runs-on: ubuntu-latest
    needs: consumer-generate
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with: { dotnet-version: '8.0.x' }
      - name: Download Pact file
        uses: actions/download-artifact@v4
        with:
          name: pact-files
          path: frontend/pacts
      - name: Run provider verification
        run: dotnet test EducationPlatform.Bff.ContractTests

The provider-verify job depends on consumer-generate. If the Vue consumer tests fail to generate a valid Pact file, the provider verification never runs. If the BFF's implementation no longer satisfies the Pact, the provider verification fails and the build is blocked. The contract mismatch surfaces in CI before either codebase reaches staging.

What the production system learned about testing

Integration tests caught the OnRedirectToLogin bug before it reached staging. The test GET_Dashboard_UnauthenticatedRequest_Returns401 was written after the bug was discovered in local development. Its presence in the integration suite meant it was caught in CI on every subsequent pull request. Tests written in response to bugs are the highest-return tests in a suite.

Pact contract tests caught a field rename. In the second month of the project, the BFF renamed avatarUrl to profileImageUrl in a refactor. The TypeScript type check in the Vue application caught it for components that referenced the field directly. The Pact consumer test caught it for the contract — the generated Pact still specified avatarUrl, and the BFF provider verification failed because the response now contained profileImageUrl. The fix was a conscious decision: keep avatarUrl for backward compatibility, add profileImageUrl as an alias, then migrate in a subsequent release.

The [Theory] / [InlineData] pattern found the division-by-zero bug. The enrollment percentage calculation was tested only for the typical case initially. Adding [InlineData(0, 0, 0)] to the theory immediately failed — the implementation did not guard against zero capacity. The guard was added in the same commit. Without the theory, this would have been a production error on the first course with no enrollment configured.

What comes next

The final article in the core series brings the operational picture together: structured logging, distributed tracing, and Azure Application Insights — how to make the running BFF observable, how to connect the traces from Vue through the BFF to upstream services, and what the dashboard configuration looks like when you need to diagnose an incident at 2am.

☰ Series navigation

A note on the code in this article. The pipeline configuration, Dockerfile, and infrastructure definitions shown here are derived from a production deployment built for a Norwegian enterprise education platform. Registry names, resource group identifiers, subscription IDs, and certain environment-specific configuration values have been generalised to meet NDA obligations. The deployment strategy, container configuration, secret management approach, and the specific operational decisions each choice addresses are drawn directly from what was deployed and operated in production.

The BFF is built. Authentication works. The Vue application consumes the API layer cleanly. What remains is getting all of it into production reliably, repeatedly, and without the kind of manual steps that turn deployments into incidents.

This article covers the full deployment pipeline: writing a production-grade Dockerfile for the .NET Core BFF, building and tagging images in CI, pushing to Azure Container Registry, and running the service on Azure Container Instances. It then covers the routing layer — Azure Front Door in front of the BFF — and addresses the APIM question directly: when it adds genuine value and when it adds cost without benefit.

The deployment approach is IaaS rather than PaaS. Azure Container Instances was chosen over App Service because the production system needed predictable container isolation, direct control over the runtime environment, and a deployment model where the exact image that passed CI is the exact image running in production. ACI provides all three without the operational overhead of a full Kubernetes cluster.

The Dockerfile

The BFF Dockerfile uses a multi-stage build. The first stage compiles and publishes the application. The second stage runs it. The published output from the first stage is the only thing copied into the final image — build tools, SDK, and intermediate files stay out of the production image entirely.

# Dockerfile

# ── Stage 1: Build ────────────────────────────────────────────────────────────
FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build
WORKDIR /src

# Copy project file and restore dependencies separately from source
# This layer is cached as long as the .csproj does not change
COPY ["EducationPlatform.Bff/EducationPlatform.Bff.csproj", "EducationPlatform.Bff/"]
RUN dotnet restore "EducationPlatform.Bff/EducationPlatform.Bff.csproj" \
    --runtime linux-musl-x64

# Copy source and publish
COPY . .
WORKDIR "/src/EducationPlatform.Bff"
RUN dotnet publish "EducationPlatform.Bff.csproj" \
    --configuration Release \
    --runtime linux-musl-x64 \
    --self-contained true \
    --output /app/publish \
    -p:PublishSingleFile=true \
    -p:PublishTrimmed=true

# ── Stage 2: Runtime ──────────────────────────────────────────────────────────
FROM mcr.microsoft.com/dotnet/runtime-deps:8.0-alpine AS runtime
WORKDIR /app

# Create non-root user — never run production containers as root
RUN addgroup -S bff && adduser -S bff -G bff
USER bff

# Copy only the published output from the build stage
COPY --from=build --chown=bff:bff /app/publish .

# Health check — ACI uses this to determine container readiness
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health/live || exit 1

EXPOSE 8080
ENV ASPNETCORE_URLS=http://+:8080

ENTRYPOINT ["./EducationPlatform.Bff"]

Several decisions here warrant explanation.

Alpine base with linux-musl-x64 runtime and --self-contained true. The Alpine image is significantly smaller than the default Debian-based image — the final runtime image sits around 90MB rather than 300MB. Self-contained publishing includes the .NET runtime in the output, which means the runtime image does not need a .NET runtime layer at all. The runtime-deps base image provides only the native dependencies that a self-contained .NET binary requires.

PublishSingleFile=true and PublishTrimmed=true. Single-file publishing packages the application and its dependencies into one executable. Trimming removes unused framework code from the output. Together they reduce the published output to roughly a third of an untrimmed multi-file publish. In a deployment model where the image is rebuilt and repushed on every merge to main, smaller images mean faster pushes and faster container starts.

Non-root user. Running as root inside a container is a security risk that is trivially avoidable. The adduser step creates a dedicated system user; the COPY --chown ensures the published files are owned by that user. ACI does not require root for any of the operations the BFF performs.

HEALTHCHECK directive. The health check command uses wget — available in Alpine — rather than curl, which is not included by default. The /health/live endpoint was defined in Article 4; it returns 200 if the process is responsive, without checking upstream dependencies. ACI monitors this endpoint to determine whether the container should receive traffic.

The CI pipeline

The production system used GitHub Actions. The pipeline has three jobs: build-and-test, docker-build-and-push, and deploy-to-aci. The jobs run sequentially — deployment only proceeds if the tests pass and the image is published successfully.

# .github/workflows/deploy.yml
name: Build and Deploy BFF

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  REGISTRY: educationplatformbff.azurecr.io
  IMAGE_NAME: bff
  RESOURCE_GROUP: rg-education-platform-prod
  CONTAINER_GROUP: cg-bff-prod
  CONTAINER_NAME: bff

jobs:
  # ── Job 1: Build and test ───────────────────────────────────────────────────
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET 8
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Restore dependencies
        run: dotnet restore

      - name: Build
        run: dotnet build --no-restore --configuration Release

      - name: Run tests
        run: dotnet test --no-build --configuration Release --verbosity normal

      # Generate OpenAPI spec and validate Vue types in CI
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Vue dependencies
        working-directory: ./frontend
        run: npm ci

      - name: Start BFF for type generation
        run: |
          dotnet run --project EducationPlatform.Bff \
            --configuration Release &
          sleep 8  # Wait for startup

      - name: Generate API types
        working-directory: ./frontend
        run: npm run generate:api:ci
        env:
          BFF_SWAGGER_URL: http://localhost:8080/swagger/v1/swagger.json

      - name: TypeScript type check
        working-directory: ./frontend
        run: npx tsc --noEmit

  # ── Job 2: Build and push Docker image ─────────────────────────────────────
  docker-build-and-push:
    runs-on: ubuntu-latest
    needs: build-and-test
    if: github.ref == 'refs/heads/main'  # Push only on main, not PRs
    outputs:
      image-tag: ${{ steps.meta.outputs.tags }}
      image-digest: ${{ steps.build-push.outputs.digest }}

    steps:
      - uses: actions/checkout@v4

      - name: Login to Azure Container Registry
        uses: azure/docker-login@v1
        with:
          login-server: ${{ env.REGISTRY }}
          username: ${{ secrets.ACR_USERNAME }}
          password: ${{ secrets.ACR_PASSWORD }}

      - name: Extract metadata for Docker
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: \({{ env.REGISTRY }}/\){{ env.IMAGE_NAME }}
          tags: |
            type=sha,prefix=,format=short
            type=raw,value=latest,enable={{is_default_branch}}

      - name: Build and push Docker image
        id: build-push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  # ── Job 3: Deploy to Azure Container Instances ──────────────────────────────
  deploy-to-aci:
    runs-on: ubuntu-latest
    needs: docker-build-and-push
    if: github.ref == 'refs/heads/main'
    environment: production

    steps:
      - name: Login to Azure
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}

      - name: Deploy to Azure Container Instances
        uses: azure/cli@v1
        with:
          azcliversion: latest
          inlineScript: |
            az container create \
              --resource-group ${{ env.RESOURCE_GROUP }} \
              --name ${{ env.CONTAINER_GROUP }} \
              --image \({{ env.REGISTRY }}/\){{ env.IMAGE_NAME }}:${{ github.sha }} \
              --registry-login-server ${{ env.REGISTRY }} \
              --registry-username ${{ secrets.ACR_USERNAME }} \
              --registry-password ${{ secrets.ACR_PASSWORD }} \
              --cpu 1 \
              --memory 1.5 \
              --ports 8080 \
              --protocol TCP \
              --restart-policy Always \
              --environment-variables \
                ASPNETCORE_ENVIRONMENT=Production \
                Services__UserService__BaseUrl=${{ secrets.USER_SERVICE_URL }} \
                Services__CourseService__BaseUrl=${{ secrets.COURSE_SERVICE_URL }} \
                Services__SessionService__BaseUrl=${{ secrets.SESSION_SERVICE_URL }} \
                Services__NotificationService__BaseUrl=${{ secrets.NOTIFICATION_SERVICE_URL }} \
                ApplicationInsights__ConnectionString=${{ secrets.APPINSIGHTS_CONNECTION_STRING }} \
              --secure-environment-variables \
                Feide__ClientId=${{ secrets.FEIDE_CLIENT_ID }} \
                Feide__ClientSecret=${{ secrets.FEIDE_CLIENT_SECRET }} \
                DataProtection__Key=${{ secrets.DATA_PROTECTION_KEY }} \
              --health-probe-http-path /health/live \
              --health-probe-port 8080 \
              --health-probe-interval-in-seconds 30

Three points on the pipeline design:

The image tag uses the Git commit SHA, not latest. The latest tag is updated in the registry, but the ACI deployment command references the SHA-tagged image explicitly. This means the deployed image and the CI build that produced it are always traceable to a specific commit. A latest deployment is unauditable — you cannot tell from the running container which commit it came from.

--secure-environment-variables for secrets. Azure CLI's az container create accepts two environment variable flags. --environment-variables sets variables that appear in the container's environment and are visible in the Azure portal. --secure-environment-variables sets variables that are injected securely and are not visible after deployment — they do not appear in portal logs or CLI output. All credentials use the secure flag. Service base URLs, which are not secrets, use the standard flag — they are useful to inspect from the portal when debugging connectivity issues.

environment: production on the deploy job. GitHub Environments add a required review gate before the deployment runs. In the production system, merges to main triggered an automatic build and test, but the actual ACI deployment required a manual approval from a second engineer. This is a lightweight but effective change control mechanism.

Data protection: encrypting the session cookie

The BFF uses ASP.NET Core's Data Protection API to encrypt the session cookie that holds the Feide tokens. In a single-instance deployment this works out of the box — the key ring is generated on startup and lives in memory. In a deployment with container restarts or multiple instances, the key ring must be persisted externally, or users are signed out every time the container restarts.

The production system persisted the key ring to Azure Blob Storage:

dotnet add package Microsoft.AspNetCore.DataProtection.AzureStorage
dotnet add package Azure.Storage.Blobs

// Program.cs — Data Protection configuration
var blobServiceClient = new BlobServiceClient(
    builder.Configuration["DataProtection:StorageConnectionString"]);

var containerClient = blobServiceClient.GetBlobContainerClient("data-protection");
await containerClient.CreateIfNotExistsAsync();

builder.Services
    .AddDataProtection()
    .PersistKeysToAzureBlobStorage(containerClient, "bff-keys.xml")
    .SetApplicationName("education-platform-bff")
    .SetDefaultKeyLifetime(TimeSpan.FromDays(90));

The SetApplicationName call is important. Data Protection uses the application name as part of the key derivation. If you deploy two versions of the BFF simultaneously — during a rolling update — they must share the same application name to be able to decrypt each other's cookies. Omitting this caused sign-out loops during the first rolling update in the production system.

Azure Container Registry: image retention policy

The pipeline pushes a new image on every merge to main. Without a retention policy, the registry accumulates images indefinitely. The production system used a lifecycle policy to retain the last 10 images and delete older untagged manifests:

# Set retention policy — keep 10 most recent images, purge after 30 days
az acr config retention update \
  --registry educationplatformbff \
  --status enabled \
  --days 30 \
  --type UntaggedManifests

# One-time cleanup of untagged images older than 1 day
az acr run \
  --registry educationplatformbff \
  --cmd "acr purge --filter 'bff:.*' --untagged --ago 30d" \
  /dev/null

This is housekeeping, but it matters at the registry billing level. Azure Container Registry charges for storage by GB, and a registry that accumulates 200 untagged image layers over six months costs meaningfully more than one that retains 10.

Azure Container Instances: the infrastructure definition

The az container create command in the pipeline creates or updates the container group. For infrastructure that changes infrequently — CPU allocation, memory, port mapping — an ARM template or Bicep definition is more auditable than a long CLI command. The production system used a Bicep definition for the baseline infrastructure, with the CI pipeline overriding only the image tag on each deployment:

// infra/bff-container.bicep
param location string = resourceGroup().location
param imageTag string
param acrLoginServer string
param acrUsername string
@secure()
param acrPassword string
@secure()
param feideClientId string
@secure()
param feideClientSecret string
@secure()
param dataProtectionConnectionString string
param appInsightsConnectionString string
param userServiceUrl string
param courseServiceUrl string
param sessionServiceUrl string
param notificationServiceUrl string

resource containerGroup 'Microsoft.ContainerInstance/containerGroups@2023-05-01' = {
  name: 'cg-bff-prod'
  location: location
  properties: {
    osType: 'Linux'
    restartPolicy: 'Always'

    imageRegistryCredentials: [
      {
        server: acrLoginServer
        username: acrUsername
        password: acrPassword
      }
    ]

    containers: [
      {
        name: 'bff'
        properties: {
          image: '\({acrLoginServer}/bff:\){imageTag}'
          ports: [{ port: 8080, protocol: 'TCP' }]

          resources: {
            requests: { cpu: 1, memoryInGB: 1 }
            limits:   { cpu: 1, memoryInGB: 1 }  // Hard limits — predictable billing
          }

          environmentVariables: [
            { name: 'ASPNETCORE_ENVIRONMENT',              value: 'Production' }
            { name: 'ASPNETCORE_URLS',                     value: 'http://+:8080' }
            { name: 'Services__UserService__BaseUrl',       value: userServiceUrl }
            { name: 'Services__CourseService__BaseUrl',     value: courseServiceUrl }
            { name: 'Services__SessionService__BaseUrl',    value: sessionServiceUrl }
            { name: 'Services__NotificationService__BaseUrl', value: notificationServiceUrl }
            { name: 'ApplicationInsights__ConnectionString', value: appInsightsConnectionString }
            { name: 'Feide__ClientId',      secureValue: feideClientId }
            { name: 'Feide__ClientSecret',  secureValue: feideClientSecret }
            { name: 'DataProtection__StorageConnectionString',
                      secureValue: dataProtectionConnectionString }
          ]

          livenessProbe: {
            httpGet: { path: '/health/live', port: 8080, scheme: 'HTTP' }
            initialDelaySeconds: 10
            periodSeconds: 30
            failureThreshold: 3
          }

          readinessProbe: {
            httpGet: { path: '/health/ready', port: 8080, scheme: 'HTTP' }
            initialDelaySeconds: 5
            periodSeconds: 10
            failureThreshold: 3
          }
        }
      }
    ]

    ipAddress: {
      type: 'Public'
      ports: [{ port: 8080, protocol: 'TCP' }]
      dnsNameLabel: 'education-platform-bff'
    }
  }
}

output containerFqdn string = containerGroup.properties.ipAddress.fqdn

The Bicep definition is committed to the repository. The sensitive parameters are passed at deploy time from GitHub Secrets. This gives you infrastructure-as-code for everything that does not change per deployment, and runtime injection for everything that does.

Azure Front Door: routing and TLS termination

ACI containers have public IP addresses but no TLS. Azure Front Door sits in front, terminates TLS, and provides a single stable hostname for both the Vue application (static files from Azure Storage or a CDN origin) and the BFF (the ACI container).

The routing rules:

• https://platform.example.no/api/* → BFF container (education-platform-bff.{region}.azurecontainer.io:8080)

• https://platform.example.no/* → Vue application static files (Azure Blob Storage static website)

// infra/front-door.bicep (abbreviated)
resource frontDoorProfile 'Microsoft.Cdn/profiles@2023-05-01' = {
  name: 'afd-education-platform'
  location: 'global'
  sku: { name: 'Standard_AzureFrontDoor' }
}

// BFF origin group
resource bffOriginGroup 'Microsoft.Cdn/profiles/originGroups@2023-05-01' = {
  parent: frontDoorProfile
  name: 'og-bff'
  properties: {
    loadBalancingSettings: {
      sampleSize: 4
      successfulSamplesRequired: 3
      additionalLatencyInMilliseconds: 50
    }
    healthProbeSettings: {
      probePath: '/health/ready'
      probeRequestType: 'GET'
      probeProtocol: 'Http'
      probeIntervalInSeconds: 30
    }
  }
}

resource bffOrigin 'Microsoft.Cdn/profiles/originGroups/origins@2023-05-01' = {
  parent: bffOriginGroup
  name: 'bff-aci'
  properties: {
    hostName: bffContainerFqdn  // Output from bff-container.bicep
    httpPort: 8080
    originHostHeader: bffContainerFqdn
    priority: 1
    weight: 1000
    enabledState: 'Enabled'
  }
}

// Route: /api/* → BFF
resource bffRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2023-05-01' = {
  name: 'route-bff'
  properties: {
    originGroup: { id: bffOriginGroup.id }
    patternsToMatch: ['/api/*']
    forwardingProtocol: 'HttpOnly'  // Front Door → ACI is internal, HTTP is fine
    httpsRedirect: 'Enabled'
    linkToDefaultDomain: 'Enabled'
  }
}

Front Door adds two things the ACI container cannot provide on its own: a trusted TLS certificate on a custom domain, and global edge caching for the Vue application's static assets. The BFF responses are not cached at the Front Door layer — they are authenticated and user-specific — but the Vue JS/CSS bundles benefit significantly from edge caching across Azure's PoPs.

One Front Door note from production: the forwardingProtocol: 'HttpOnly' between Front Door and ACI is intentional. The BFF container listens on HTTP on port 8080. The TLS boundary is at Front Door — the traffic between Front Door and ACI traverses Azure's internal network, which does not leave Microsoft's infrastructure. Establishing a second TLS hop to ACI adds latency and complexity without adding meaningful security. This is a deliberate, documented trade-off, not a configuration oversight.

Azure API Management: when it adds value and when it does not

API Management sits between Front Door and the BFF in the architecture described in Article 3. Whether to include it in the production deployment is a question the architecture series has deferred until here — because the answer depends on what you are actually deploying, and the honest answer is nuanced.

When APIM is worth the overhead

Centralised JWT validation before the BFF. APIM can validate the Feide JWT at the network perimeter — before the request reaches the BFF — using an inbound policy. This offloads cryptographic validation from the BFF and means an invalid token never consumes BFF resources:

<!-- APIM inbound policy -->
<inbound>
  <validate-jwt header-name="Authorization" failed-validation-httpcode="401">
    <openid-config url="https://auth.dataporten.no/.well-known/openid-configuration" />
    <audiences>
      <audience>your-client-id</audience>
    </audiences>
  </validate-jwt>
  <base />
</inbound>

Rate limiting per client or per user. APIM's rate limit policies can throttle by subscription key, IP, or JWT claim. For a platform with institutional clients, rate limiting per organisation prevents one institution's usage patterns from affecting another's:

<rate-limit-by-key calls="1000" renewal-period="60"
  counter-key="@(context.Request.Headers.GetValueOrDefault("X-Org-Id", "anonymous"))" />

Request logging with correlation across tenants. APIM emits structured request logs to Application Insights that include the subscription key, caller IP, response code, and latency — with no code changes to the BFF. For a multi-tenant education platform, this per-organisation visibility is valuable for capacity planning and SLA reporting.

When APIM adds cost without benefit

Single-tenant, single-client deployments. If the BFF serves one Vue application for one organisation, APIM's multi-tenancy features are unused overhead. The Standard tier costs roughly €130/month. For a deployment that would not use routing policies, subscription management, or the developer portal, that is €130/month for request proxying that Front Door already provides.

When the BFF handles auth itself. The production system this series describes authenticates via Feide's OIDC flow — a server-side redirect flow, not a bearer token in the request header. APIM's JWT validation policy is not applicable. The auth boundary is the cookie session managed by the BFF, not a token at the network perimeter. In this specific configuration, APIM's primary value proposition does not apply.

The honest answer for this production system: APIM was not included in the production deployment. The authentication model (cookie-based session, not JWT in header), the single-tenant deployment, and the cost overhead put it outside the value threshold. Front Door provided TLS termination, routing, and basic DDoS protection. The BFF provided everything else. APIM would be the first thing added if the platform expanded to serve multiple institutions as independent tenants with per-tenant rate limiting requirements.

This is the decision the architecture series promised in Article 3: here is the specific context, here is the reasoning, here is the call.

Environment promotion: staging before production

The production pipeline had two environments: staging and production. The staging environment used the same ACI / Front Door topology with different resource names and configuration values. Every push to main deployed to staging automatically. Promotion to production required a manual approval gate in GitHub Environments.

The staging ACI container pointed to staging instances of the upstream services. The Feide integration used Feide's test environment (https://auth.dataporten-test.no), which allows test institution credentials without affecting production identity records.

The environment variable difference between staging and production was entirely in GitHub Secrets — the Bicep definition was identical. This is the correct model: infrastructure code is environment-agnostic; environment-specific values are injected at deployment time.

Rollback

ACI's deployment model creates or replaces a container group. There is no built-in rollback command. The production rollback procedure was:

# Redeploy the last known-good image tag (stored as a GitHub Actions output)
az container create \
  --resource-group rg-education-platform-prod \
  --name cg-bff-prod \
  --image educationplatformbff.azurecr.io/bff:${LAST_GOOD_SHA} \
  # ... remaining flags identical to the original deployment

The last-good SHA was recorded as a GitHub Actions environment variable after each successful deployment. This is manual, but it is fast — a rollback to the previous image completes in under two minutes, which is the ACI container start time plus the registry pull time.

For teams that need zero-downtime rollbacks, the correct tool is Azure Container Apps or AKS rather than ACI. ACI's container group replacement causes a brief interruption — typically 30 to 60 seconds — while the new container starts and the health probe validates it. For the production education platform, deployments were scheduled during low-traffic windows (evenings, weekends) and the brief interruption was acceptable.

Observability wiring: Application Insights in the container

The Serilog Application Insights sink configured in Article 4 requires one environment variable to function: the Application Insights connection string. This was injected as a plain (non-secure) environment variable in the ACI deployment — connection strings are not credentials in the traditional sense, but they do identify your Application Insights resource. The production team treated them as non-secret but non-public.

Verify the telemetry pipeline is working after the first deployment:

# Query Application Insights for BFF requests in the last 5 minutes
az monitor app-insights query \
  --app ai-education-platform \
  --analytics-query "requests | where timestamp > ago(5m) | project timestamp, name, resultCode, duration | order by timestamp desc | limit 20"

If the BFF is running and the connection string is correct, this query returns the last 20 requests with their status codes and durations within seconds of them completing. No requests appearing means either the container is not running, the connection string is wrong, or the Serilog sink is not configured. Article 9 covers the full observability setup in depth.

The complete deployment, end to end

A merge to main triggers this sequence:

1. GitHub Actions: run .NET tests, generate OpenAPI types, TypeScript type check.

2. If all pass: build Docker image tagged with the commit SHA, push to ACR.

3. Manual approval gate (GitHub Environments) — second engineer reviews.

4. Deploy: az container create replaces the existing ACI container group with the new image.

5. ACI pulls the image from ACR, starts the container, waits for /health/live to return 200.

6. Azure Front Door health probe (/health/ready) validates upstream connectivity.

7. Once both probes pass, the container receives traffic.

8. Application Insights begins receiving telemetry within 30 seconds of startup.

Total time from merge to production traffic: approximately 8 to 12 minutes, including the approval gate. The approval gate accounts for roughly 2 of those minutes on average — the remainder is build, push, and container start time.

What comes next

The BFF is deployed, authenticated, and observable. The final two articles in the core series address the engineering discipline that keeps it that way: Article 8 covers testing strategy — unit, integration, and consumer-driven contract tests with Pact — and Article 9 covers the full observability setup with structured logging, distributed tracing, and Application Insights dashboards.

☰ Series navigation

A note on the code in this article. The implementation shown here is derived from a production authentication integration built for a Norwegian enterprise education platform using Feide as the identity provider. Tenant identifiers, internal endpoint paths, and certain configuration details have been generalised to meet NDA obligations. The OAuth 2.0 / OIDC flow, Token Handler pattern implementation, session management strategy, and the specific failure modes each decision addresses are drawn directly from what was deployed and operated in production.

Authentication is the decision in a BFF architecture where getting it wrong is most expensive to undo. A poorly designed aggregation layer can be refactored incrementally. A poorly designed authentication boundary — tokens in the browser, session management scattered across client and server, a leaky security perimeter — creates vulnerabilities that propagate into every part of the system and are painful to retrofit.

This article covers the authentication architecture for the education platform at the centre of this series. The identity provider is Feide — the Norwegian government-issued federated identity system used by educational institutions across Norway, from primary schools to universities. Feide is OIDC-compliant and follows standard OAuth 2.0 flows, but its institutional context introduces specific requirements around organisation-scoped claims and role hierarchies that shape implementation decisions.

The core argument of this article: the BFF is the right place to own authentication, tokens should never reach the browser, and cookie-based sessions managed server-side are more secure and simpler to reason about than browser-held tokens — despite what the proliferation of JWT-in-localStorage tutorials might suggest.

Why tokens in the browser are the wrong model

Before the implementation, the security argument deserves to be made explicitly, because the alternative — storing access tokens in localStorage or sessionStorage and attaching them to requests from the Vue application — is common, documented in many identity provider tutorials, and genuinely wrong for this class of application.

The problem is the browser's threat model. localStorage is accessible to any JavaScript running on the page. In a complex web application with third-party dependencies — analytics scripts, support widgets, UI libraries — the attack surface for cross-site scripting is real. A single XSS vulnerability in any dependency gives an attacker access to every token in storage. An access token for Feide, which carries institutional identity and role claims, is a meaningful target in an education context.

HttpOnly cookies are not accessible to JavaScript at all. An XSS attack that compromises a page's JavaScript cannot read an HttpOnly cookie. The cookie is attached to requests by the browser's network stack, not by application code. This does not eliminate all attack vectors — CSRF remains a concern — but it removes the entire class of token theft via script injection, which is the higher-probability attack.

The Token Handler pattern implements this correctly: the BFF holds the access token server-side, issues a session cookie to the browser, and exchanges the cookie for the token on every upstream API call. The browser never sees the token. The Vue application never handles authentication directly. This is not additional complexity — it is relocating complexity from the browser (where it cannot be properly secured) to the server (where it can).

Feide: what it is and what it provides

Feide (Felles Elektronisk IDentitet — common electronic identity) is the identity federation service operated by Sikt for Norwegian educational institutions. It provides federated single sign-on across universities, university colleges, and primary and secondary schools. An institution's staff and students authenticate with their institutional credentials; Feide issues identity tokens that carry organisation membership, role information, and a persistent identifier that is stable across sessions.

For an education platform, this means:

• Users authenticate once with their institution's credentials — no separate account registration

• The platform receives verified organisational membership and role claims (eduPersonAffiliation, eduPersonPrimaryAffiliation, orgMembership)

• A stable, pseudonymous identifier (feidePersonPrincipalName, typically username@institution.no) is available for user records

• The platform can scope data access by institution without maintaining its own organisation identity store

Feide exposes a standard OIDC provider at https://auth.dataporten.no. The integration uses the Authorization Code flow with PKCE, which is the correct flow for server-side applications that can keep a client secret. The production system used Feide's Dataporten platform, which wraps Feide identity with additional APIs for group membership and course data — though those APIs are not covered here as they are specific to the platform's data architecture.

The authentication flow, end to end

The full flow involves four parties: the Vue application (browser), the BFF (.NET Core), Feide (the identity provider), and the upstream services.

The browser participates in the OIDC flow via redirects only — it is never given a token. The BFF holds all three tokens (access, ID, refresh) in an encrypted server-side session. The Vue application interacts with the BFF exclusively via its session cookie.

Setting up OIDC in .NET Core

Install the required packages:

dotnet add package Microsoft.AspNetCore.Authentication.OpenIdConnect
dotnet add package Microsoft.AspNetCore.Authentication.Cookies

The authentication configuration in Program.cs:

// Program.cs

var feideConfig = builder.Configuration.GetSection("Feide");

builder.Services
    .AddAuthentication(options =>
    {
        options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
    })
    .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme, options =>
    {
        options.Cookie.Name = "__bff_session";
        options.Cookie.HttpOnly = true;
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        options.Cookie.SameSite = SameSiteMode.Strict;
        options.Cookie.MaxAge = TimeSpan.FromHours(8); // Align with Feide session lifetime
        options.SlidingExpiration = true;
        options.ExpireTimeSpan = TimeSpan.FromHours(8);

        // Redirect API requests to 401 instead of the login page
        options.Events.OnRedirectToLogin = ctx =>
        {
            if (ctx.Request.Path.StartsWithSegments("/api"))
            {
                ctx.Response.StatusCode = StatusCodes.Status401Unauthorized;
                return Task.CompletedTask;
            }
            ctx.Response.Redirect(ctx.RedirectUri);
            return Task.CompletedTask;
        };
    })
    .AddOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme, options =>
    {
        options.Authority = feideConfig["Authority"]; // https://auth.dataporten.no
        options.ClientId = feideConfig["ClientId"];
        options.ClientSecret = feideConfig["ClientSecret"];

        options.ResponseType = OpenIdConnectResponseType.Code; // Auth Code flow
        options.UsePkce = true;

        options.Scope.Clear();
        options.Scope.Add("openid");
        options.Scope.Add("profile");
        options.Scope.Add("email");
        options.Scope.Add("groups");        // Feide group membership
        options.Scope.Add("userinfo-feide"); // Feide-specific claims

        options.CallbackPath = "/auth/callback";
        options.SignedOutCallbackPath = "/auth/signout-callback";

        options.SaveTokens = true; // Stores tokens in the session — critical for Token Handler

        options.GetClaimsFromUserInfoEndpoint = true;

        // Map Feide-specific claims to standard .NET claim types
        options.ClaimActions.MapJsonKey(ClaimTypes.Email, "email");
        options.ClaimActions.MapJsonKey("feide:orgid", "eduPersonOrgDN");
        options.ClaimActions.MapJsonKey("feide:role", "eduPersonPrimaryAffiliation");
        options.ClaimActions.MapJsonKey("feide:principal", "feidePersonPrincipalName");

        options.TokenValidationParameters = new TokenValidationParameters
        {
            NameClaimType = "feidePersonPrincipalName",
            RoleClaimType = "eduPersonAffiliation"
        };

        options.Events = new OpenIdConnectEvents
        {
            OnTokenValidated = ctx =>
            {
                // Add the Feide principal name as the NameIdentifier claim
                // so ctx.User.FindFirstValue(ClaimTypes.NameIdentifier) works
                // consistently throughout the BFF
                var principal = ctx.Principal!;
                var feidePrincipal = principal.FindFirstValue("feidePersonPrincipalName");
                if (feidePrincipal is not null)
                {
                    var identity = (ClaimsIdentity)principal.Identity!;
                    identity.AddClaim(new Claim(ClaimTypes.NameIdentifier, feidePrincipalName));
                }
                return Task.CompletedTask;
            },

            OnAuthenticationFailed = ctx =>
            {
                var logger = ctx.HttpContext.RequestServices
                    .GetRequiredService<ILogger<Program>>();
                logger.LogError(ctx.Exception,
                    "Feide authentication failed. CorrelationId: {CorrelationId}",
                    ctx.HttpContext.TraceIdentifier);
                ctx.Response.Redirect("/auth/error");
                ctx.HandleResponse();
                return Task.CompletedTask;
            }
        };
    });

builder.Services.AddAuthorization();

Three decisions in this configuration deserve attention.

SaveTokens = true is the Token Handler pivot. This instructs the OIDC middleware to persist the access token, ID token, and refresh token in the encrypted cookie session. The BFF retrieves the access token from the session on every upstream API call. Without this, the token exchange would need to be implemented manually.

The OnRedirectToLogin event handler separates browser and API requests. Without this, a request to /api/dashboard with an expired session returns a 302 redirect to the Feide login page — which the fetch call in the Vue composable receives as a 200 with HTML content and breaks silently. The handler returns a clean 401 for API paths, which the useApi composable handles explicitly.

Claim mapping from Feide-specific types to standard .NET claim types. Feide's userinfo endpoint returns claims with LDAP-style keys (eduPersonPrimaryAffiliation, feidePersonPrincipalName). The ClaimActions.MapJsonKey calls map these to keys the BFF's claim-reading code can use consistently. The OnTokenValidated event ensures ClaimTypes.NameIdentifier is set from the Feide principal name — so the user ID extraction in every aggregator (ctx.User.FindFirstValue(ClaimTypes.NameIdentifier)) works without Feide-specific knowledge.

The auth endpoints

Three endpoints handle the authentication lifecycle:

// Endpoints/AuthEndpoints.cs
public static class AuthEndpoints
{
    public static IEndpointRouteBuilder MapAuthEndpoints(
        this IEndpointRouteBuilder app)
    {
        app.MapGet("/auth/login", LoginAsync);
        app.MapGet("/auth/logout", LogoutAsync).RequireAuthorization();
        app.MapGet("/auth/me", GetCurrentUserAsync).RequireAuthorization();

        return app;
    }

    // Triggers the OIDC challenge — redirects to Feide
    private static IResult LoginAsync(HttpContext ctx)
    {
        var returnUrl = ctx.Request.Query["returnUrl"].FirstOrDefault() ?? "/";

        // Validate returnUrl to prevent open redirects
        if (!Uri.TryCreate(returnUrl, UriKind.Relative, out _))
            returnUrl = "/";

        return Results.Challenge(
            new AuthenticationProperties { RedirectUri = returnUrl },
            [OpenIdConnectDefaults.AuthenticationScheme]);
    }

    // Signs out locally and triggers Feide end-session endpoint
    private static async Task<IResult> LogoutAsync(HttpContext ctx)
    {
        await ctx.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
        return Results.SignOut(
            new AuthenticationProperties { RedirectUri = "/" },
            [OpenIdConnectDefaults.AuthenticationScheme]);
    }

    // Returns the current user's profile — consumed by the Vue session store
    private static IResult GetCurrentUserAsync(HttpContext ctx)
    {
        var user = ctx.User;

        var profile = new AuthenticatedUserResponse(
            PrincipalName: user.FindFirstValue("feidePersonPrincipalName")!,
            DisplayName: user.FindFirstValue(ClaimTypes.Name)
                ?? user.FindFirstValue("feidePersonPrincipalName")!,
            Email: user.FindFirstValue(ClaimTypes.Email),
            Role: TranslateFeideRole(user.FindFirstValue("feidePersonPrincipalName")!,
                  user.FindFirstValue("eduPersonPrimaryAffiliation")),
            OrgId: ExtractOrgId(user.FindFirstValue("eduPersonOrgDN"))
        );

        return Results.Ok(profile);
    }

    private static string TranslateFeideRole(string principal, string? affiliationCode) =>
        affiliationCode switch
        {
            "staff"    => "Teacher",
            "student"  => "Student",
            "faculty"  => "Teacher",
            "employee" => "Staff",
            _          => "Unknown"
        };

    // eduPersonOrgDN is an LDAP DN: dc=uninett,dc=no → extract org identifier
    private static string? ExtractOrgId(string? orgDn)
    {
        if (orgDn is null) return null;
        var parts = orgDn.Split(',');
        return parts.FirstOrDefault(p => p.StartsWith("dc=", StringComparison.OrdinalIgnoreCase))
            ?.Split('=').ElementAtOrDefault(1);
    }
}

The /auth/me endpoint is what the Vue session store calls on application load to hydrate the user profile. It reads from the claims already in the session — no upstream call required. This is fast and safe: the session cookie validates the user's identity; the claims in the cookie provide the profile data.

The Token Handler: forwarding tokens to upstream services

The most important implementation detail in this architecture is how the access token — held server-side in the session — is forwarded to upstream services on behalf of the authenticated user.

The Token Handler is a DelegatingHandler that intercepts every HttpClient call and attaches the access token from the current user's session:

// Infrastructure/FeideTokenHandler.cs
public sealed class FeideTokenHandler(IHttpContextAccessor contextAccessor)
    : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken ct)
    {
        var ctx = contextAccessor.HttpContext;

        if (ctx?.User.Identity?.IsAuthenticated == true)
        {
            // Retrieve the access token stored by SaveTokens = true
            var accessToken = await ctx.GetTokenAsync(
                CookieAuthenticationDefaults.AuthenticationScheme,
                "access_token");

            if (accessToken is not null)
            {
                request.Headers.Authorization =
                    new AuthenticationHeaderValue("Bearer", accessToken);
            }
            else
            {
                // Token missing from session — likely expired without refresh
                // Log and let the upstream return 401, which the BFF maps to a 503
                var logger = ctx.RequestServices
                    .GetRequiredService<ILogger<FeideTokenHandler>>();
                logger.LogWarning(
                    "Access token not available in session for user {User}. " +
                    "Request to {RequestUri} will proceed without authorization header.",
                    ctx.User.FindFirstValue(ClaimTypes.NameIdentifier),
                    request.RequestUri);
            }
        }

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

Register it as a transient service and attach it to every typed client:

// Program.cs
builder.Services.AddTransient<FeideTokenHandler>();

builder.Services.AddHttpClient<CourseServiceClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["Services:CourseService:BaseUrl"]!))
    .AddHttpMessageHandler<FeideTokenHandler>()
    .AddStandardResilienceHandler();

builder.Services.AddHttpClient<SessionServiceClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["Services:SessionService:BaseUrl"]!))
    .AddHttpMessageHandler<FeideTokenHandler>()
    .AddStandardResilienceHandler();

// Repeat for every upstream client

The FeideTokenHandler is registered once and applied to every HTTP client that calls authenticated upstream services. The upstream services receive a standard Bearer token in the Authorization header — they never know or care that the token came from a server-side session rather than a browser-held JWT.

Token refresh: handling expiry transparently

Feide access tokens have a limited lifetime. In the production system, tokens expired after one hour. A user with an active eight-hour session must have their token refreshed transparently without being redirected to Feide to re-authenticate.

The refresh is handled by an OIDC events hook that fires when the cookie session is validated:

// Infrastructure/TokenRefreshService.cs
public sealed class TokenRefreshService(IHttpClientFactory httpClientFactory)
{
    public async Task<bool> TryRefreshAsync(HttpContext ctx)
    {
        var refreshToken = await ctx.GetTokenAsync(
            CookieAuthenticationDefaults.AuthenticationScheme,
            "refresh_token");

        if (refreshToken is null) return false;

        var client = httpClientFactory.CreateClient();
        var feideAuthority = ctx.RequestServices
            .GetRequiredService<IConfiguration>()["Feide:Authority"];

        var tokenResponse = await client.PostAsync(
            $"{feideAuthority}/openid/token",
            new FormUrlEncodedContent(new Dictionary<string, string>
            {
                ["grant_type"]    = "refresh_token",
                ["refresh_token"] = refreshToken,
                ["client_id"]     = ctx.RequestServices
                    .GetRequiredService<IConfiguration>()["Feide:ClientId"]!,
                ["client_secret"] = ctx.RequestServices
                    .GetRequiredService<IConfiguration>()["Feide:ClientSecret"]!
            }));

        if (!tokenResponse.IsSuccessStatusCode)
        {
            var logger = ctx.RequestServices.GetRequiredService<ILogger<TokenRefreshService>>();
            logger.LogWarning(
                "Token refresh failed for user {User}. Status: {Status}. " +
                "User will need to re-authenticate.",
                ctx.User.FindFirstValue(ClaimTypes.NameIdentifier),
                tokenResponse.StatusCode);
            return false;
        }

        var tokens = await tokenResponse.Content
            .ReadFromJsonAsync<TokenRefreshResponse>();

        // Update the tokens stored in the session
        var authResult = await ctx.AuthenticateAsync(
            CookieAuthenticationDefaults.AuthenticationScheme);

        if (authResult?.Properties is null) return false;

        authResult.Properties.UpdateTokenValue("access_token", tokens!.AccessToken);
        authResult.Properties.UpdateTokenValue("expires_at",
            DateTimeOffset.UtcNow
                .AddSeconds(tokens.ExpiresIn)
                .ToString("o"));

        if (tokens.RefreshToken is not null)
            authResult.Properties.UpdateTokenValue("refresh_token", tokens.RefreshToken);

        await ctx.SignInAsync(
            CookieAuthenticationDefaults.AuthenticationScheme,
            authResult.Principal!,
            authResult.Properties);

        return true;
    }

    private sealed record TokenRefreshResponse(
        [property: JsonPropertyName("access_token")] string AccessToken,
        [property: JsonPropertyName("expires_in")] int ExpiresIn,
        [property: JsonPropertyName("refresh_token")] string? RefreshToken
    );
}

Wire the refresh into the FeideTokenHandler, so it fires automatically when the token is close to expiry:

// Infrastructure/FeideTokenHandler.cs — updated
public sealed class FeideTokenHandler(
    IHttpContextAccessor contextAccessor,
    TokenRefreshService tokenRefresh)
    : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken ct)
    {
        var ctx = contextAccessor.HttpContext;

        if (ctx?.User.Identity?.IsAuthenticated == true)
        {
            var expiresAt = await ctx.GetTokenAsync(
                CookieAuthenticationDefaults.AuthenticationScheme,
                "expires_at");

            // Refresh proactively if within 5 minutes of expiry
            if (DateTimeOffset.TryParse(expiresAt, out var expiry)
                && expiry < DateTimeOffset.UtcNow.AddMinutes(5))
            {
                await tokenRefresh.TryRefreshAsync(ctx);
            }

            var accessToken = await ctx.GetTokenAsync(
                CookieAuthenticationDefaults.AuthenticationScheme,
                "access_token");

            if (accessToken is not null)
                request.Headers.Authorization =
                    new AuthenticationHeaderValue("Bearer", accessToken);
        }

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

The five-minute proactive refresh window prevents the edge case where a token expires between the check and the upstream call completing. The refresh is synchronous within the handler, which adds latency to requests that trigger it — in practice, this happens at most once per hour per user, and the upstream call still completes successfully.

Register TokenRefreshService:

builder.Services.AddTransient<TokenRefreshService>();

CSRF protection

SameSite=Strict on the session cookie is the first line of CSRF defence — cross-site requests do not include the cookie at all. For the production system, where the Vue application and the BFF share an origin (same domain, served behind Azure Front Door), SameSite=Strict was sufficient.

For deployments where the Vue application and BFF are on different subdomains, SameSite=Lax is required, and explicit CSRF token validation is necessary. The BFF generates a CSRF token, sets it in a non-HttpOnly cookie (so the Vue application's JavaScript can read it), and the Vue apiClient attaches it as a request header:

// Middleware/CsrfMiddleware.cs
public sealed class CsrfMiddleware(RequestDelegate next, IAntiforgery antiforgery)
{
    public async Task InvokeAsync(HttpContext ctx)
    {
        if (ctx.Request.Path.StartsWithSegments("/api")
            && !HttpMethods.IsGet(ctx.Request.Method)
            && !HttpMethods.IsHead(ctx.Request.Method))
        {
            await antiforgery.ValidateRequestAsync(ctx);
        }

        // Set the CSRF token cookie on every response so Vue can read it
        var tokens = antiforgery.GetAndStoreTokens(ctx);
        ctx.Response.Cookies.Append("XSRF-TOKEN", tokens.RequestToken!, new CookieOptions
        {
            HttpOnly = false, // Must be readable by JavaScript
            Secure = true,
            SameSite = SameSiteMode.Lax
        });

        await next(ctx);
    }
}

In the Vue apiClient, the CSRF token is read from the cookie and attached to mutation requests:

// src/api/client.ts — CSRF-aware post
function getCsrfToken(): string | null {
  const match = document.cookie.match(/XSRF-TOKEN=([^;]+)/)
  return match ? decodeURIComponent(match[1]) : null
}

export const apiClient = {
  async post<T>(path: string, body: unknown, init?: RequestInit): Promise<T> {
    const csrfToken = getCsrfToken()
    const response = await fetch(`/api${path}`, {
      ...init,
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        ...(csrfToken ? { 'X-XSRF-TOKEN': csrfToken } : {}),
        ...init?.headers
      },
      body: JSON.stringify(body),
      credentials: 'include'
    })
    return handleResponse<T>(response)
  }
}

In the production system, the shared-origin deployment made this unnecessary. It is included here because the pattern is needed the moment the deployment topology changes.

The Vue session store: connecting auth to the UI

The Vue application needs to know whether the user is authenticated, and if so, who they are. The session store from Article 5 calls the /auth/me endpoint on application startup:

// src/stores/session.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import { apiClient, ApiResponseError } from '@/api/client'
import type { AuthenticatedUserResponse } from '@/api/types'

export const useSessionStore = defineStore('session', () => {
  const profile = ref<AuthenticatedUserResponse | null>(null)
  const isAuthenticated = computed(() => profile.value !== null)
  const isLoading = ref(false)

  async function initialise() {
    isLoading.value = true
    try {
      profile.value = await apiClient.get<AuthenticatedUserResponse>('/auth/me')
    } catch (e) {
      if (e instanceof ApiResponseError && e.status === 401) {
        // Not authenticated — expected on first visit
        profile.value = null
      } else {
        // Unexpected error — log but do not block the application
        console.error('Session initialisation failed:', e)
        profile.value = null
      }
    } finally {
      isLoading.value = false
    }
  }

  function redirectToLogin(returnUrl = window.location.pathname) {
    window.location.href = `/auth/login?returnUrl=${encodeURIComponent(returnUrl)}`
  }

  function clearSession() {
    profile.value = null
    window.location.href = '/auth/logout'
  }

  return {
    profile,
    isAuthenticated,
    isLoading,
    initialise,
    redirectToLogin,
    clearSession
  }
})

Initialise the store in App.vue before rendering protected routes:

<!-- src/App.vue -->
<script setup lang="ts">
import { onMounted } from 'vue'
import { useSessionStore } from '@/stores/session'

const session = useSessionStore()
onMounted(() => session.initialise())
</script>

And protect routes with a navigation guard:

// src/router/index.ts
import { useSessionStore } from '@/stores/session'

router.beforeEach(async (to) => {
  if (!to.meta.requiresAuth) return true

  const session = useSessionStore()

  // Wait for session to initialise on first navigation
  if (session.isLoading) {
    await new Promise<void>(resolve => {
      const stop = watch(session.isLoading, loading => {
        if (!loading) { stop(); resolve() }
      })
    })
  }

  if (!session.isAuthenticated) {
    session.redirectToLogin(to.fullPath)
    return false
  }

  return true
})

The navigation guard waits for the session initialisation to complete before evaluating authentication status. Without this wait, a page refresh on a protected route redirects to login before the /auth/me response has returned — even for authenticated users.

The appsettings configuration

// appsettings.json
{
  "Feide": {
    "Authority": "https://auth.dataporten.no",
    "ClientId": "",
    "ClientSecret": ""
  }
}

ClientId and ClientSecret are empty in appsettings.json and are never committed to source control. In Azure Container Instances, they are injected as environment variables:

Feide__ClientId       → injected from Azure Key Vault reference
Feide__ClientSecret   → injected from Azure Key Vault reference

.NET's configuration system maps double-underscore environment variable names to nested JSON paths, so Feide__ClientId maps to Feide.ClientId. Article 7 covers the Key Vault reference configuration in the ACI deployment pipeline.

What the production system learned about Feide integration

Several decisions were revised during the production deployment:

The session cookie lifetime must align with Feide's session. An early implementation used a 24-hour cookie with a one-hour Feide access token and no refresh logic. The result: after one hour, the session cookie was valid but the access token was expired. Every upstream call returned 401. The fix — proactive token refresh in the FeideTokenHandler — was added in the second sprint after first deployment. The current eight-hour cookie lifetime and five-minute refresh window are the values that matched observed usage patterns.

GetClaimsFromUserInfoEndpoint = true is required for Feide-specific claims. The standard ID token from Feide does not include organisation membership or affiliation claims — these come from the Feide userinfo endpoint. Without GetClaimsFromUserInfoEndpoint = true, the BFF receives only the standard OIDC claims and the role translation returns "Unknown" for every user. This was a non-obvious configuration gap that took half a day to diagnose in the staging environment.

The OnRedirectToLogin event handler is not optional. Before it was added, the Vue application's composables received HTML login-page redirects as successful 200 responses. The useDashboard composable silently failed to parse HTML as JSON, data.value remained null, and the dashboard rendered in a permanently loading state. The fix was the API-path 401 handler in the cookie options — immediate and unambiguous failure is more debuggable than silent null data.

What comes next

With authentication established at the BFF boundary, the next article addresses deployment: building the Docker image, publishing artifacts through the pipeline, and running the BFF on Azure Container Instances — including environment variable injection for secrets and the health probe configuration that keeps the container in rotation when it is healthy and out of it when it is not.

☰ Series navigation

A note on the code in this article. The implementation shown here is derived from a production Vue 3 application built for a Norwegian enterprise education platform. Service names, domain models, and certain structural details have been generalised to meet NDA obligations. The composable patterns, type generation pipeline, error handling strategies, and the specific production problems each decision addresses are drawn directly from what was shipped and maintained in production.

Article 4 built the BFF service. This article builds the other side of the contract — the Vue 3 layer that consumes it. The BFF gives your frontend a stable, shaped API. What you do with that API on the client side determines whether your components stay clean or accumulate the same adapter logic the BFF was supposed to eliminate.

The goal is a client API layer where every component receives typed, ready-to-render data from a composable, error states are handled consistently and not improvised per-component, and a change to the BFF's response schema surfaces as a compile-time error in TypeScript before it reaches the browser. This is achievable — the production system this series is based on ran this setup in CI — but it requires deliberate structure from the start.

This article covers the full stack: OpenAPI type generation, the base useApi composable, screen-level composables built on top of it, error boundary strategy, and the patterns that did not survive contact with production alongside the ones that did.

The type generation pipeline

The contract between the Vue application and the BFF should be enforced by the type system, not by convention or documentation. The mechanism is straightforward: the BFF publishes an OpenAPI spec, a generation script turns that spec into TypeScript interfaces, and those interfaces are imported wherever the API response is consumed.

Install the generator:

npm install -D openapi-typescript

Add the generation script to package.json:

{
  "scripts": {
    "generate:api": "openapi-typescript http://localhost:5000/swagger/v1/swagger.json --output src/api/types.gen.ts",
    "generate:api:ci": "openapi-typescript $BFF_SWAGGER_URL --output src/api/types.gen.ts"
  }
}

The generate:api script targets the local BFF running in development. The generate:api:ci variant uses an environment variable pointing to the staging BFF — the same version that will be deployed alongside the frontend build. This matters: generating types from a different BFF version than the one you are deploying against defeats the purpose of the pipeline.

Running this against the BFF built in Article 4 produces a file like this (abbreviated):

// src/api/types.gen.ts — generated, do not edit manually
export interface components {
  schemas: {
    DashboardResponse: {
      user: components['schemas']['UserProfileResponse'];
      courses: components['schemas']['CourseResponse'][];
      upcomingSessions: components['schemas']['SessionResponse'][];
      notifications: components['schemas']['NotificationSummary'];
      partialFailures: string[];
    };
    UserProfileResponse: {
      displayName: string;
      role: string;
      avatarUrl: string | null;
    };
    CourseResponse: {
      id: string;
      title: string;
      code: string;
      enrollmentLabel: string;
      enrollmentPercent: number;
      status: string;
    };
    SessionResponse: {
      id: string;
      title: string;
      startsAt: string;
      courseTitle: string;
      locationLabel: string;
    };
    NotificationSummary: {
      count: number;
    };
  };
}

Create a single re-export file that the rest of the application imports from. Never import from types.gen.ts directly — doing so couples every consumer to the generated file's internal structure, which changes every time the generator runs:

// src/api/types.ts
import type { components } from './types.gen'

export type DashboardResponse = components['schemas']['DashboardResponse']
export type UserProfileResponse = components['schemas']['UserProfileResponse']
export type CourseResponse = components['schemas']['CourseResponse']
export type SessionResponse = components['schemas']['SessionResponse']
export type NotificationSummary = components['schemas']['NotificationSummary']

This indirection layer is the difference between a type generation pipeline and a type generation obligation. The generated file changes freely; the re-export file changes only when the public contract deliberately changes.

Make type generation a CI gate. In the production system, the CI pipeline ran generate:api:ci and then tsc --noEmit. A BFF response shape change that broke the Vue application's types failed the build before deployment. This caught contract mismatches three times in the project's lifetime — each time before a broken build reached staging.

The base composable: useApi

Every API call in the application goes through a single base composable. This is the most important structural decision in the client API layer, and the one most frequently skipped in Vue projects that start simple and grow into a tangle of inconsistent error handling.

The base composable is responsible for three things and only three things: executing a fetch function, managing the loading/error/data state lifecycle, and normalising errors into a consistent shape.

// src/composables/useApi.ts
import { ref, readonly, type Ref } from 'vue'

export interface ApiError {
  status: number
  title: string
  detail: string
  traceId: string | null
}

export interface UseApiReturn<T> {
  data: Ref<T | null>
  error: Ref<ApiError | null>
  isLoading: Ref<boolean>
  execute: () => Promise<void>
}

export function useApi<T>(
  fetchFn: () => Promise<T>,
  options: { immediate?: boolean } = {}
): UseApiReturn<T> {
  const data = ref<T | null>(null) as Ref<T | null>
  const error = ref<ApiError | null>(null)
  const isLoading = ref(false)

  const execute = async () => {
    isLoading.value = true
    error.value = null

    try {
      data.value = await fetchFn()
    } catch (e) {
      error.value = normaliseError(e)
      data.value = null
    } finally {
      isLoading.value = false
    }
  }

  if (options.immediate) {
    execute()
  }

  return {
    data: readonly(data) as Ref<T | null>,
    error: readonly(error) as Ref<ApiError | null>,
    isLoading: readonly(isLoading) as Ref<boolean>,
    execute
  }
}

function normaliseError(e: unknown): ApiError {
  // BFF returns Problem Details (RFC 7807) — parse the structured body
  if (e instanceof ApiResponseError) {
    return {
      status: e.status,
      title: e.title,
      detail: e.detail,
      traceId: e.traceId
    }
  }

  // Network failure — no response body
  if (e instanceof TypeError && e.message.includes('fetch')) {
    return {
      status: 0,
      title: 'Network error',
      detail: 'Could not reach the server. Check your connection.',
      traceId: null
    }
  }

  // Unexpected — still normalise
  return {
    status: -1,
    title: 'Unexpected error',
    detail: e instanceof Error ? e.message : 'An unknown error occurred.',
    traceId: null
  }
}

The readonly wrappers on data and error are deliberate. Components receive the state refs but cannot mutate them directly — mutations go through execute. This prevents a class of bugs where a component sets data.value = null as a local workaround and breaks another component consuming the same state.

The HTTP client and error class

The base composable uses an ApiResponseError that wraps the BFF's Problem Details response. This is the class that bridges the HTTP layer with the composable's error normalisation:

// src/api/client.ts
export class ApiResponseError extends Error {
  constructor(
    public readonly status: number,
    public readonly title: string,
    public readonly detail: string,
    public readonly traceId: string | null
  ) {
    super(`\({status}: \){title}`)
  }
}

async function handleResponse<T>(response: Response): Promise<T> {
  if (response.ok) {
    return response.json() as Promise<T>
  }

  // Attempt to parse Problem Details body
  let problem = { title: 'Error', detail: 'An error occurred.', traceId: null }
  try {
    const body = await response.json()
    problem = {
      title: body.title ?? problem.title,
      detail: body.detail ?? problem.detail,
      traceId: body.traceId ?? null
    }
  } catch {
    // Non-JSON error body — use defaults
  }

  throw new ApiResponseError(
    response.status,
    problem.title,
    problem.detail,
    problem.traceId
  )
}

export const apiClient = {
  async get<T>(path: string, init?: RequestInit): Promise<T> {
    const response = await fetch(`/api${path}`, {
      ...init,
      headers: {
        'Accept': 'application/json',
        ...init?.headers
      },
      credentials: 'include' // Send session cookie
    })
    return handleResponse<T>(response)
  },

  async post<T>(path: string, body: unknown, init?: RequestInit): Promise<T> {
    const response = await fetch(`/api${path}`, {
      ...init,
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        ...init?.headers
      },
      body: JSON.stringify(body),
      credentials: 'include'
    })
    return handleResponse<T>(response)
  }
}

credentials: 'include' ensures the session cookie is sent with every request — the BFF's authentication is cookie-based, as established in the architecture. This is a single configuration point; forgetting it per-request was a failure mode caught in development.

The path prefix /api is injected once here. Components and composables never construct full URLs — they pass paths (/dashboard, /courses/c-1) and the client handles the rest.

Screen-level composables

The base composable handles mechanics. Screen-level composables handle intent — they know which BFF endpoint to call, what type the response is, and what derived state the component tree needs.

// src/composables/useDashboard.ts
import { computed } from 'vue'
import { useApi } from './useApi'
import { apiClient } from '@/api/client'
import type { DashboardResponse } from '@/api/types'

export function useDashboard() {
  const { data, error, isLoading, execute } = useApi<DashboardResponse>(
    () => apiClient.get<DashboardResponse>('/dashboard'),
    { immediate: true }
  )

  // Derived state — components consume these, not raw data
  const user = computed(() => data.value?.user ?? null)
  const courses = computed(() => data.value?.courses ?? [])
  const upcomingSessions = computed(() => data.value?.upcomingSessions ?? [])
  const notificationCount = computed(() => data.value?.notifications.count ?? 0)

  // Surface partial failure state for component-level degradation handling
  const hasPartialFailure = computed(
    () => (data.value?.partialFailures?.length ?? 0) > 0
  )
  const partialFailures = computed(() => data.value?.partialFailures ?? [])

  return {
    // State
    user,
    courses,
    upcomingSessions,
    notificationCount,
    hasPartialFailure,
    partialFailures,
    // Loading / error
    isLoading,
    error,
    // Manual refresh
    refresh: execute
  }
}

Three things to notice here.

Derived computed refs, not raw data. The component does not receive data.value?.courses — it receives courses, a computed ref with a [] fallback. This removes null-guard boilerplate from every component that consumes this composable. The fallback values are defined once, in the composable, not scattered across template expressions.

partialFailures is surfaced explicitly. The BFF returns this field (built in Article 4) when some upstream services failed but the response was still structurally valid. The composable exposes hasPartialFailure and partialFailures so components can render degraded states with a specific message rather than a generic error.

immediate: true fires the fetch on composable creation. The dashboard fetches its data as soon as the composable is created — which happens when the component mounts. For detail screens that require a parameter (a course ID, a session ID), immediate is false and execute is called explicitly once the parameter is available.

Using the composable in a component

<!-- src/views/DashboardView.vue -->
<script setup lang="ts">
import { useDashboard } from '@/composables/useDashboard'
import UserProfileCard from '@/components/UserProfileCard.vue'
import CourseListPanel from '@/components/CourseListPanel.vue'
import UpcomingSessionsList from '@/components/UpcomingSessionsList.vue'
import NotificationBadge from '@/components/NotificationBadge.vue'
import PartialFailureBanner from '@/components/PartialFailureBanner.vue'
import LoadingSpinner from '@/components/LoadingSpinner.vue'
import ErrorDisplay from '@/components/ErrorDisplay.vue'

const {
  user,
  courses,
  upcomingSessions,
  notificationCount,
  hasPartialFailure,
  partialFailures,
  isLoading,
  error,
  refresh
} = useDashboard()
</script>

<template>
  <div class="dashboard">
    <LoadingSpinner v-if="isLoading" />

    <ErrorDisplay
      v-else-if="error"
      :error="error"
      @retry="refresh"
    />

    <template v-else>
      <PartialFailureBanner
        v-if="hasPartialFailure"
        :failures="partialFailures"
      />

      <UserProfileCard v-if="user" :profile="user" />

      <div class="dashboard-body">
        <CourseListPanel :courses="courses" />
        <UpcomingSessionsList :sessions="upcomingSessions" />
      </div>

      <NotificationBadge :count="notificationCount" />
    </template>
  </div>
</template>

The component contains no fetch calls, no try/catch, no null guards beyond v-if="user", and no type assertions. It destructures the composable and binds to named refs. If the BFF's UserProfileResponse type changes — say, displayName is renamed to fullName — TypeScript flags every component binding that uses the old name before the code compiles.

Parameterised composables: detail screens

Not all composables fire immediately. Detail screens receive an ID from the route and fetch on mount with that ID.

// src/composables/useCourseDetail.ts
import { computed, watch, type Ref } from 'vue'
import { useApi } from './useApi'
import { apiClient } from '@/api/client'
import type { CourseDetailResponse } from '@/api/types'

export function useCourseDetail(courseId: Ref<string>) {
  const { data, error, isLoading, execute } = useApi<CourseDetailResponse>(
    () => apiClient.get<CourseDetailResponse>(`/courses/${courseId.value}`),
    { immediate: false } // Do not fire until courseId is known
  )

  // Fire whenever courseId changes — handles navigation between detail pages
  watch(courseId, () => execute(), { immediate: true })

  const course = computed(() => data.value ?? null)
  const sessions = computed(() => data.value?.sessions ?? [])
  const enrollmentOpen = computed(() => data.value?.enrollment.isOpen ?? false)

  return { course, sessions, enrollmentOpen, isLoading, error, refresh: execute }
}

The watch with { immediate: true } fires on mount with the initial courseId value, and re-fires whenever the ID changes — which happens when the user navigates from one course detail to another without unmounting the view. Forgetting this watch was a bug caught in dev: navigating from course A to course B showed course A's data until the component was destroyed and recreated. The watch fixes it structurally.

Using the composable in the view:

<!-- src/views/CourseDetailView.vue -->
<script setup lang="ts">
import { toRef } from 'vue'
import { useRoute } from 'vue-router'
import { useCourseDetail } from '@/composables/useCourseDetail'

const route = useRoute()
const courseId = toRef(() => route.params.courseId as string)

const { course, sessions, enrollmentOpen, isLoading, error, refresh } =
  useCourseDetail(courseId)
</script>

toRef(() => ...) creates a reactive ref from the route param — it updates when the route changes, which triggers the watch in the composable.

Error boundaries: the component-level strategy

The base composable normalises errors into ApiError. But where errors are rendered is a component-level concern, and three distinct strategies apply depending on the screen.

Strategy 1: Inline error with retry

For primary data on a screen where failure should be surfaced and recoverable:

<!-- src/components/ErrorDisplay.vue -->
<script setup lang="ts">
import type { ApiError } from '@/composables/useApi'

defineProps<{
  error: ApiError
}>()

const emit = defineEmits<{
  retry: []
}>()
</script>

<template>
  <div class="error-display" role="alert">
    <p class="error-title">{{ error.title }}</p>
    <p class="error-detail">{{ error.detail }}</p>
    <p v-if="error.traceId" class="error-trace">
      Reference: {{ error.traceId }}
    </p>
    <button @click="emit('retry')">Try again</button>
  </div>
</template>

The traceId renders in the UI. Support engineers ask users for it when investigating incidents. This is a small detail with outsized operational value — when a user reports a 503 and can read out a trace ID, an engineer can find the exact request in Application Insights in seconds.

Strategy 2: Partial failure banner

For degraded responses where some data loaded and some did not — surfaced via partialFailures from the BFF:

<!-- src/components/PartialFailureBanner.vue -->
<script setup lang="ts">
const props = defineProps<{
  failures: string[]
}>()

const failureLabels: Record<string, string> = {
  courses: 'course list',
  sessions: 'upcoming sessions',
  notifications: 'notifications'
}

const failureDescription = computed(() =>
  props.failures
    .map(f => failureLabels[f] ?? f)
    .join(' and ')
)
</script>

<template>
  <div class="partial-failure-banner" role="status">
    Some content could not be loaded ({{ failureDescription }}).
    The page may be incomplete.
  </div>
</template>

This component renders alongside the data that did load, rather than replacing it. The user sees a partially populated dashboard with an honest explanation — not a full-screen error for a non-critical failure.

Strategy 3: Silent fallback for non-critical widgets

For widgets where failure is genuinely inconsequential — a notification count badge, a "last login" display:

<!-- src/components/NotificationBadge.vue -->
<script setup lang="ts">
defineProps<{ count: number }>()
// count arrives as 0 from the composable fallback if the upstream failed.
// No error state needed — 0 is a valid, renderable value.
</script>

<template>
  <span v-if="count > 0" class="badge">{{ count }}</span>
</template>

The composable's notificationCount defaults to 0 when the notification service failed. The badge component renders nothing if the count is 0 — which is indistinguishable from "no notifications" to the user. This is the correct trade-off for a non-critical UI element.

The principle: choose the error strategy based on what the user can do in response to the failure, not based on technical severity. A 503 on the profile service warrants a full error display with retry. A 503 on the notification service warrants silence.

Write operations: POST, PATCH, and mutation composables

Read composables are straightforward — fire on mount, expose derived state. Write composables are different: they are triggered by user interaction, need to track submission state separately from loading state, and must handle validation errors from the BFF distinctly from network errors.

// src/composables/useCourseEnrollment.ts
import { ref } from 'vue'
import { apiClient, ApiResponseError } from '@/api/client'
import type { EnrollmentRequest, EnrollmentResponse } from '@/api/types'

export function useCourseEnrollment() {
  const isSubmitting = ref(false)
  const validationErrors = ref<Record<string, string>>({})
  const submitError = ref<string | null>(null)
  const isSuccess = ref(false)

  const enroll = async (courseId: string, payload: EnrollmentRequest) => {
    isSubmitting.value = true
    validationErrors.value = {}
    submitError.value = null
    isSuccess.value = false

    try {
      await apiClient.post<EnrollmentResponse>(
        `/courses/${courseId}/enrollment`,
        payload
      )
      isSuccess.value = true
    } catch (e) {
      if (e instanceof ApiResponseError) {
        if (e.status === 422) {
          // BFF returns validation errors as an extensions object
          validationErrors.value = (e as any).extensions?.errors ?? {}
        } else {
          submitError.value = e.detail
        }
      } else {
        submitError.value = 'Could not complete enrollment. Please try again.'
      }
    } finally {
      isSubmitting.value = false
    }
  }

  return {
    enroll,
    isSubmitting,
    validationErrors,
    submitError,
    isSuccess
  }
}

The distinction between validationErrors (field-level, from a 422) and submitError (message-level, from any other error) mirrors how the BFF handles these two failure modes. The BFF returns structured validation errors on 422; the component receives them as a record and maps them to field labels. Any other failure becomes a banner message, not a field annotation.

Shared state: when a composable is not enough

Most composables are created per-component and their state is local to that component's lifetime. Occasionally, state needs to be shared across components that are not in a parent-child relationship — the authenticated user's profile is the clearest example.

The solution in the production system was a Pinia store for session state only, with everything else in per-screen composables:

// src/stores/session.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import { apiClient } from '@/api/client'
import type { UserProfileResponse } from '@/api/types'

export const useSessionStore = defineStore('session', () => {
  const profile = ref<UserProfileResponse | null>(null)
  const isAuthenticated = computed(() => profile.value !== null)

  async function fetchProfile() {
    try {
      profile.value = await apiClient.get<UserProfileResponse>('/auth/me')
    } catch {
      profile.value = null
    }
  }

  function clearSession() {
    profile.value = null
  }

  return { profile, isAuthenticated, fetchProfile, clearSession }
})

The session store is initialised once in App.vue on mount. Every component that needs the user's display name or role reads from the store rather than making another BFF call. Everything else — courses, sessions, notifications — stays in per-screen composables. This is the minimum viable use of global state: use it only when the data genuinely needs to outlive any single component's lifetime.

The complete data flow, end to end

To make the layers concrete:

BFF OpenAPI spec
  ↓  openapi-typescript
src/api/types.gen.ts
  ↓  re-exported via
src/api/types.ts
  ↓  imported by
src/composables/useDashboard.ts
  ↓  typed return value consumed by
src/views/DashboardView.vue
  ↓  typed props passed to
src/components/CourseListPanel.vue

Every link in this chain is type-checked. A change at the BFF end propagates as a TypeScript error through every layer until every consumer is updated. No runtime surprises. No "it worked in development" moments in staging.

What the production system learned

A few failure modes that did not survive contact with production and the decisions that replaced them:

axios interceptors for error handling. The first implementation used an Axios response interceptor to normalise errors globally. This worked until two endpoints needed different error handling behaviour — one needed to suppress 404s silently, another needed to escalate 403s to a full-page redirect. Interceptor configuration became conditional logic that was harder to reason about than per-composable handling. The apiClient wrapper with handleResponse replaced it: explicit, co-located, composable-specific where needed.

Loading state in Vuex before Pinia. The early implementation tracked isLoading for every API call in a Vuex module keyed by endpoint name. Components dispatched actions and read loading state from the store. This scaled poorly — the store grew large, loading state leaked between navigations, and testing required mocking the entire store for any component test. Per-composable isLoading refs fixed all three problems.

Direct fetch calls in components. Several components in the early sprint made fetch calls directly in onMounted. This was fast to write and immediately problematic: no shared loading state, no consistent error handling, no type safety, and no way to test the fetch logic independently of the component. The useApi base composable was introduced at sprint 4 and all direct fetch calls were migrated over two weeks.

What comes next

The API layer is complete on both sides — the BFF shapes and serves, the Vue composables consume and distribute. The next article addresses the most architecturally consequential decision in the implementation: authentication. Specifically, how Feide — Norway's government-issued identity provider for the education sector — is integrated via the BFF using the Token Handler pattern, why this requires server-side session management, and why tokens should never reach the browser in this architecture.

☰ Series navigation

A note on the code in this article. The implementation shown here is derived from a production BFF built for a Norwegian enterprise education platform. Service names, domain models, and certain structural details have been generalised to meet NDA obligations. The architectural patterns, code structure, error handling strategies, and the specific problems each decision solves are drawn directly from what was deployed and operated in production. Nothing here is invented for illustration.

The previous two articles covered what a BFF should do and why it earns its place in your architecture. This article covers how to build one — in .NET Core, with Minimal APIs, from an empty project to a production-ready service that aggregates upstream calls, shapes responses for Vue, and handles failures gracefully.

There is a gap between "here is the pattern" and "here is the thing running in production," and most articles stop before bridging it. This one does not. The code examples are complete enough to be followed, the decisions behind them are explained, and the production failure modes they address are named.

Project setup and structure

Start with a minimal .NET 8 Web API project. The BFF does not need controllers — Minimal APIs are the right tool here. They are explicit, lightweight, and push route organisation into the project structure rather than into a controller inheritance hierarchy.

dotnet new web -n EducationPlatform.Bff
cd EducationPlatform.Bff
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
dotnet add package Microsoft.Extensions.Http.Resilience
dotnet add package Microsoft.AspNetCore.Authentication.Cookies
dotnet add package Serilog.AspNetCore
dotnet add package Serilog.Sinks.ApplicationInsights

The project structure that emerged from the production implementation:

EducationPlatform.Bff/
├── Endpoints/
│   ├── DashboardEndpoints.cs
│   ├── CourseEndpoints.cs
│   └── SessionEndpoints.cs
├── Aggregators/
│   ├── DashboardAggregator.cs
│   └── CourseAggregator.cs
├── Clients/
│   ├── UserServiceClient.cs
│   ├── CourseServiceClient.cs
│   ├── SessionServiceClient.cs
│   └── NotificationServiceClient.cs
├── Contracts/
│   ├── Requests/
│   └── Responses/
├── Errors/
│   └── BffProblemDetails.cs
├── Middleware/
│   └── CorrelationIdMiddleware.cs
└── Program.cs

The separation between Clients and Aggregators is the key structural decision. Clients know how to talk to one upstream service. Aggregators know how to compose multiple client calls into a single, shaped response. Endpoints know which aggregator to call and how to map the result to an HTTP response. No layer bleeds into another's concern.

Program.cs: wiring the service

The entry point registers services, configures HTTP clients, and maps endpoints. Keep it declarative — the configuration intent should be readable without tracing through implementation details.

using EducationPlatform.Bff.Clients;
using EducationPlatform.Bff.Endpoints;
using EducationPlatform.Bff.Middleware;
using Serilog;

var builder = WebApplication.CreateBuilder(args);

// Logging — Serilog with Application Insights sink
builder.Host.UseSerilog((ctx, cfg) => cfg
    .ReadFrom.Configuration(ctx.Configuration)
    .Enrich.FromLogContext()
    .Enrich.WithProperty("Service", "bff")
    .WriteTo.Console()
    .WriteTo.ApplicationInsights(
        ctx.Configuration["ApplicationInsights:ConnectionString"],
        TelemetryConverter.Traces));

// HTTP clients with resilience
builder.Services.AddHttpClient<UserServiceClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["Services:UserService:BaseUrl"]!))
    .AddStandardResilienceHandler();

builder.Services.AddHttpClient<CourseServiceClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["Services:CourseService:BaseUrl"]!))
    .AddStandardResilienceHandler();

builder.Services.AddHttpClient<SessionServiceClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["Services:SessionService:BaseUrl"]!))
    .AddStandardResilienceHandler();

builder.Services.AddHttpClient<NotificationServiceClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["Services:NotificationService:BaseUrl"]!))
    .AddStandardResilienceHandler();

// Aggregators
builder.Services.AddScoped<DashboardAggregator>();
builder.Services.AddScoped<CourseAggregator>();

// Auth — covered in depth in Article 6
builder.Services.AddAuthentication("cookie")
    .AddCookie("cookie");
builder.Services.AddAuthorization();

// Problem details for structured error responses
builder.Services.AddProblemDetails();

var app = builder.Build();

// Middleware pipeline
app.UseMiddleware<CorrelationIdMiddleware>();
app.UseSerilogRequestLogging();
app.UseAuthentication();
app.UseAuthorization();

// Endpoint registration
app.MapDashboardEndpoints();
app.MapCourseEndpoints();
app.MapSessionEndpoints();

app.Run();

AddStandardResilienceHandler() comes from Microsoft.Extensions.Http.Resilience. It wires retry, circuit breaker, timeout, and hedging policies with sensible defaults — without requiring manual Polly configuration for the standard case. Article Extra E covers customising these policies for partial failure scenarios that the standard handler does not cover.

The typed HTTP clients

Each upstream service gets a dedicated typed client. The client is responsible for one thing: making HTTP calls to that service and deserialising the response. It does not shape, transform, or make decisions about what the frontend needs.

// Clients/CourseServiceClient.cs
public sealed class CourseServiceClient(HttpClient http, ILogger<CourseServiceClient> logger)
{
    public async Task<IReadOnlyList<CourseDto>?> GetCoursesByOrgAsync(
        string orgId,
        CancellationToken ct = default)
    {
        try
        {
            var response = await http.GetAsync($"courses?orgId={orgId}", ct);
            response.EnsureSuccessStatusCode();
            return await response.Content.ReadFromJsonAsync<IReadOnlyList<CourseDto>>(ct);
        }
        catch (HttpRequestException ex)
        {
            logger.LogWarning(ex,
                "Course service unavailable for orgId {OrgId}. StatusCode: {Status}",
                orgId, ex.StatusCode);
            return null; // Caller decides how to handle absence
        }
    }

    public async Task<CourseDetailDto?> GetCourseDetailAsync(
        string courseId,
        CancellationToken ct = default)
    {
        try
        {
            var response = await http.GetAsync($"courses/{courseId}", ct);
            if (response.StatusCode == HttpStatusCode.NotFound) return null;
            response.EnsureSuccessStatusCode();
            return await response.Content.ReadFromJsonAsync<CourseDetailDto>(ct);
        }
        catch (HttpRequestException ex)
        {
            logger.LogWarning(ex,
                "Failed to retrieve course {CourseId}. StatusCode: {Status}",
                courseId, ex.StatusCode);
            return null;
        }
    }
}

Returning null on upstream failure is a deliberate choice. The client signals absence; the aggregator decides whether absence means degraded response or hard failure. This keeps failure policy out of the client and in the layer that understands what the client surface needs.

The DTOs the client deserialises into mirror the upstream service's response shape exactly. They are internal types — they never leave the BFF:

// Contracts internal upstream DTOs - never exposed to Vue
internal sealed record CourseDto(
    string Id,
    CourseMetadataDto Metadata,
    EnrollmentDto Enrollment,
    CourseStatusDto Status
);

internal sealed record CourseMetadataDto(
    string Title,
    string Code,
    CurriculumDto Curriculum
);

internal sealed record EnrollmentDto(int Capacity, int Enrolled, int Waitlist);
internal sealed record CourseStatusDto(string Code, DateTimeOffset Since);

The aggregator: orchestrating upstream calls

The aggregator is the most important class in the BFF. It owns the dependency graph of upstream calls, executes them efficiently, shapes the merged result into a response the Vue application can consume directly, and decides how to handle partial failures.

// Aggregators/DashboardAggregator.cs
public sealed class DashboardAggregator(
    UserServiceClient userClient,
    CourseServiceClient courseClient,
    SessionServiceClient sessionClient,
    NotificationServiceClient notificationClient,
    ILogger<DashboardAggregator> logger)
{
    public async Task<DashboardResponse> AggregateAsync(
        string userId,
        CancellationToken ct = default)
    {
        var partialFailures = new List<string>();

        // Phase 1: independent calls in parallel
        var profileTask = userClient.GetProfileAsync(userId, ct);
        var notificationTask = notificationClient.GetUnreadCountAsync(userId, ct);

        await Task.WhenAll(profileTask, notificationTask);

        var profile = profileTask.Result;

        // Profile is required — cannot render a meaningful dashboard without it
        if (profile is null)
        {
            logger.LogError("User profile unavailable for userId {UserId}. Aborting aggregation.", userId);
            throw new BffAggregationException("User profile service unavailable.");
        }

        // Phase 2: depends on orgId from profile
        var courses = await courseClient.GetCoursesByOrgAsync(profile.OrgId, ct);
        if (courses is null)
        {
            logger.LogWarning("Course service unavailable for org {OrgId}. Returning degraded response.", profile.OrgId);
            partialFailures.Add("courses");
        }

        // Phase 3: depends on courseIds from Phase 2
        IReadOnlyList<SessionDto>? sessions = null;
        if (courses is not null && courses.Count > 0)
        {
            var courseIds = courses.Select(c => c.Id).ToArray();
            sessions = await sessionClient.GetUpcomingAsync(courseIds, limit: 3, ct);
            if (sessions is null)
            {
                logger.LogWarning("Session service unavailable. Returning degraded response.");
                partialFailures.Add("sessions");
            }
        }

        return new DashboardResponse(
            User: ShapeUserProfile(profile),
            Courses: courses?.Select(ShapeCourse).ToList() ?? [],
            UpcomingSessions: sessions?.Select(ShapeSession).ToList() ?? [],
            Notifications: new NotificationSummary(notificationTask.Result ?? 0),
            PartialFailures: partialFailures
        );
    }

    // Shape methods: upstream DTO → Vue response contract
    private static UserProfileResponse ShapeUserProfile(UserProfileDto dto) =>
        new(
            DisplayName: $"{dto.FirstName} {dto.LastName}",
            Role: TranslateRole(dto.RoleCode),
            AvatarUrl: dto.AvatarPath is not null
                ? $"/media/avatars/{dto.AvatarPath}"
                : null
        );

    private static CourseResponse ShapeCourse(CourseDto dto) =>
        new(
            Id: dto.Id,
            Title: dto.Metadata.Title,
            Code: dto.Metadata.Code,
            EnrollmentLabel: $"{dto.Enrollment.Enrolled} / {dto.Enrollment.Capacity}",
            EnrollmentPercent: dto.Enrollment.Capacity > 0
                ? (int)Math.Round((dto.Enrollment.Enrolled / (double)dto.Enrollment.Capacity) * 100)
                : 0,
            Status: TranslateStatus(dto.Status.Code)
        );

    private static SessionResponse ShapeSession(SessionDto dto) =>
        new(
            Id: dto.Id,
            Title: dto.Title,
            StartsAt: dto.StartsAt.ToString("yyyy-MM-ddTHH:mm:ss"),
            CourseTitle: dto.CourseTitle,
            LocationLabel: dto.Room is not null ? $"Room {dto.Room}" : "Online"
        );

    private static string TranslateRole(string roleCode) => roleCode switch
    {
        "TEACHER" => "Teacher",
        "STUDENT" => "Student",
        "ADMIN"   => "Administrator",
        _         => "Unknown"
    };

    private static string TranslateStatus(string statusCode) => statusCode switch
    {
        "ACTIVE"   => "Active",
        "INACTIVE" => "Inactive",
        "DRAFT"    => "Draft",
        _          => statusCode
    };
}

Three decisions worth making explicit here:

Profile failure is a hard error; course and session failure is degraded. The dashboard cannot render without a user profile — there is no meaningful fallback. Course and session data, by contrast, can fail independently. The Vue component handles courses: [] and partialFailures: ["courses"] by showing an empty state with an appropriate message. This distinction — required vs. supplementary data — must be made per-aggregator based on what each screen actually needs.

Shape methods are private and co-located with the aggregator. The shaping logic belongs next to the aggregation logic it serves. A separate CourseShaper class would be indirection without benefit at this scale. If shaping logic grows complex enough to warrant extraction, that is a signal to reconsider the response contract design.

The partialFailures list is part of the response contract. The Vue application receives this and uses it to decide what to render. This is not error handling hidden from the client — it is explicit communication of what succeeded and what did not, at the response level.

The response contracts

The types exposed to the Vue application are defined separately from the internal upstream DTOs. This is the BFF's external contract — it should be stable and versioned independently of internal implementation.

// Contracts/Responses/DashboardResponse.cs
public sealed record DashboardResponse(
    UserProfileResponse User,
    IReadOnlyList<CourseResponse> Courses,
    IReadOnlyList<SessionResponse> UpcomingSessions,
    NotificationSummary Notifications,
    IReadOnlyList<string> PartialFailures
);

public sealed record UserProfileResponse(
    string DisplayName,
    string Role,
    string? AvatarUrl
);

public sealed record CourseResponse(
    string Id,
    string Title,
    string Code,
    string EnrollmentLabel,
    int EnrollmentPercent,
    string Status
);

public sealed record SessionResponse(
    string Id,
    string Title,
    string StartsAt,
    string CourseTitle,
    string LocationLabel
);

public sealed record NotificationSummary(int Count);

Using record types for response contracts gives structural equality, immutability, and clean JSON serialisation out of the box. The records are not annotated with [JsonPropertyName] unless the Vue convention demands camelCase divergence from the default serialiser behaviour — which .NET's JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase handles globally.

The endpoint layer

Endpoints are thin. They authenticate the request, extract route or query parameters, call the aggregator, and return the result. Nothing more.

// Endpoints/DashboardEndpoints.cs
public static class DashboardEndpoints
{
    public static IEndpointRouteBuilder MapDashboardEndpoints(
        this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/dashboard")
            .RequireAuthorization();

        group.MapGet("/", GetDashboardAsync)
            .WithName("GetDashboard")
            .WithOpenApi();

        return app;
    }

    private static async Task<IResult> GetDashboardAsync(
        HttpContext ctx,
        DashboardAggregator aggregator,
        CancellationToken ct)
    {
        var userId = ctx.User.FindFirstValue(ClaimTypes.NameIdentifier);

        if (userId is null)
            return Results.Problem(
                detail: "Authenticated user identity could not be resolved.",
                statusCode: StatusCodes.Status401Unauthorized);

        try
        {
            var response = await aggregator.AggregateAsync(userId, ct);
            return Results.Ok(response);
        }
        catch (BffAggregationException ex)
        {
            return Results.Problem(
                detail: ex.Message,
                statusCode: StatusCodes.Status503ServiceUnavailable,
                title: "Upstream service unavailable");
        }
    }
}

The endpoint does not know what an aggregator does internally. It knows how to interpret the result and how to translate a BffAggregationException into a 503 Problem Details response. This is the correct division.

Route grouping and versioning

Route groups keep related endpoints together and make versioning explicit when it becomes necessary:

// For stable endpoints — no version in path
var group = app.MapGroup("/api/dashboard").RequireAuthorization();

// When a breaking contract change is required
var v2Group = app.MapGroup("/api/v2/dashboard").RequireAuthorization();

In the production system, versioned groups were introduced only twice in the service's lifetime — both during major screen redesigns. Day-to-day contract evolution was additive only, keeping the URL stable. This is the versioning discipline described in Article 2 in practice.

Error handling: the BFF error contract

The Vue application needs consistent, structured error information. .NET's Problem Details (RFC 7807) provides this structure out of the box, and the BFF should use it exclusively.

// Errors/BffProblemDetails.cs
public sealed class BffAggregationException(string message) : Exception(message);
public sealed class BffNotFoundException(string resource) 
    : Exception($"Resource not found: {resource}");

// Global exception handler registered in Program.cs
app.UseExceptionHandler(exceptionApp =>
{
    exceptionApp.Run(async ctx =>
    {
        ctx.Response.ContentType = "application/problem+json";

        var ex = ctx.Features.Get<IExceptionHandlerFeature>()?.Error;
        var logger = ctx.RequestServices.GetRequiredService<ILogger<Program>>();

        var (status, title, detail) = ex switch
        {
            BffAggregationException e =>
                (503, "Upstream service unavailable", e.Message),
            BffNotFoundException e =>
                (404, "Resource not found", e.Message),
            OperationCanceledException =>
                (499, "Request cancelled", "The request was cancelled by the client."),
            _ =>
                (500, "Unexpected error", "An unexpected error occurred. Correlation ID: " +
                    ctx.TraceIdentifier)
        };

        logger.LogError(ex, "Unhandled exception. CorrelationId: {CorrelationId}", ctx.TraceIdentifier);

        ctx.Response.StatusCode = status;
        await ctx.Response.WriteAsJsonAsync(new
        {
            type = $"https://bff.educationplatform.no/errors/{title.ToLower().Replace(' ', '-')}",
            title,
            status,
            detail,
            traceId = ctx.TraceIdentifier
        });
    });
});

The traceId in every error response is the correlation ID that threads through Application Insights. When a 503 appears in the Vue application and an engineer opens Application Insights, searching by traceId surfaces every log entry for that request — BFF logs, upstream client logs, the exception itself. This is not gold-plating; it is the minimum viable observability for a service that aggregates multiple upstreams.

Correlation ID middleware

Every request entering the BFF should carry a correlation ID that propagates to every upstream call. This is the mechanism that makes request tracing work across service boundaries.

// Middleware/CorrelationIdMiddleware.cs
public sealed class CorrelationIdMiddleware(RequestDelegate next)
{
    private const string CorrelationIdHeader = "X-Correlation-Id";

    public async Task InvokeAsync(HttpContext ctx)
    {
        var correlationId = ctx.Request.Headers[CorrelationIdHeader].FirstOrDefault()
            ?? Activity.Current?.Id
            ?? ctx.TraceIdentifier;

        ctx.Response.Headers[CorrelationIdHeader] = correlationId;

        using (LogContext.PushProperty("CorrelationId", correlationId))
        {
            await next(ctx);
        }
    }
}

And in each typed client, the correlation ID is forwarded on every outgoing request:

// Clients/CourseServiceClient.cs — updated constructor
public sealed class CourseServiceClient(
    HttpClient http,
    IHttpContextAccessor contextAccessor,
    ILogger<CourseServiceClient> logger)
{
    private void AttachCorrelationId(HttpRequestMessage request)
    {
        var correlationId = contextAccessor.HttpContext?
            .Response.Headers["X-Correlation-Id"].FirstOrDefault();
        if (correlationId is not null)
            request.Headers.TryAddWithoutValidation("X-Correlation-Id", correlationId);
    }

    public async Task<IReadOnlyList<CourseDto>?> GetCoursesByOrgAsync(
        string orgId, CancellationToken ct = default)
    {
        var request = new HttpRequestMessage(HttpMethod.Get, $"courses?orgId={orgId}");
        AttachCorrelationId(request);
        try
        {
            var response = await http.SendAsync(request, ct);
            response.EnsureSuccessStatusCode();
            return await response.Content.ReadFromJsonAsync<IReadOnlyList<CourseDto>>(ct);
        }
        catch (HttpRequestException ex)
        {
            logger.LogWarning(ex,
                "Course service unavailable for orgId {OrgId}", orgId);
            return null;
        }
    }
}

Register IHttpContextAccessor in Program.cs:

builder.Services.AddHttpContextAccessor();

Configuration and appsettings

The BFF reads service base URLs, authentication configuration, and Application Insights connection string from appsettings.json, with environment-specific overrides injected as environment variables in Azure Container Instances.

// appsettings.json
{
  "Services": {
    "UserService": { "BaseUrl": "https://user-service.internal/" },
    "CourseService": { "BaseUrl": "https://course-service.internal/" },
    "SessionService": { "BaseUrl": "https://session-service.internal/" },
    "NotificationService": { "BaseUrl": "https://notification-service.internal/" }
  },
  "ApplicationInsights": {
    "ConnectionString": "" // Injected at runtime via environment variable
  },
  "Authentication": {
    "Cookie": {
      "Name": "__bff_session",
      "HttpOnly": true,
      "Secure": true,
      "SameSite": "Strict"
    }
  }
}

The appsettings.json contains non-sensitive defaults. Secrets — connection strings, service credentials — are never checked into source control. In Azure Container Instances, they are injected as environment variables or pulled from Azure Key Vault at startup. Article 7 covers this configuration pattern in the deployment pipeline.

OpenAPI and type generation

Enable OpenAPI in Program.cs:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(opts =>
{
    opts.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Education Platform BFF",
        Version = "v1",
        Description = "Backend for Frontend — Vue web application"
    });
});

// In development only
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

The generated OpenAPI spec at /swagger/v1/swagger.json is the source of truth for the Vue application's TypeScript types. In the monorepo, a generate:api script runs openapi-typescript against this spec during development and in CI:

// package.json (Vue project)
{
  "scripts": {
    "generate:api": "openapi-typescript http://localhost:5000/swagger/v1/swagger.json -o src/api/types.gen.ts"
  }
}

The generated types.gen.ts imports directly into Vue composables. If the BFF changes a response type and the Vue application's composable does not update to match, TypeScript catches it at compile time — not at runtime in production.

Health checks

A BFF running in Azure Container Instances needs health endpoints for the container readiness and liveness probes:

builder.Services.AddHealthChecks()
    .AddUrlGroup(
        new Uri(builder.Configuration["Services:UserService:BaseUrl"] + "health"),
        "user-service")
    .AddUrlGroup(
        new Uri(builder.Configuration["Services:CourseService:BaseUrl"] + "health"),
        "course-service");

// In app pipeline
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false // Liveness: BFF process is alive, no dependency checks
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = _ => true, // Readiness: all upstream services reachable
    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
});

The distinction between liveness and readiness matters in ACI. Liveness failure restarts the container. Readiness failure removes it from the load balancer without restarting. A BFF that is running but cannot reach an upstream service should be removed from traffic, not restarted — hence the separate endpoints. Article 7 wires these to the ACI container group configuration.

A complete request, traced end to end

To make the moving parts concrete, here is the full lifecycle of a GET /api/dashboard request:

1. Request arrives at Azure Front Door. TLS terminated. JWT validated by Azure API Management.

2. APIM forwards the request to the BFF container, adding X-Correlation-Id if not present.

3. CorrelationIdMiddleware extracts the correlation ID, adds it to the log context, and sets it on the response header.

4. Authentication middleware validates the session cookie and populates HttpContext.User.

5. The GetDashboard endpoint handler extracts userId from claims.

6. DashboardAggregator.AggregateAsync fires Phase 1 calls — UserServiceClient and NotificationServiceClient — in parallel, each forwarding X-Correlation-Id.

7. Profile returned. Phase 2: CourseServiceClient fetches by orgId.

8. Courses returned. Phase 3: SessionServiceClient fetches upcoming sessions by courseIds.

9. Aggregator shapes all results into DashboardResponse, recording any partial failures.

10. Endpoint returns 200 OK with the shaped response body and X-Correlation-Id header.

11. Serilog writes a structured request log entry to Application Insights, including correlation ID, duration, status code, and upstream call counts.

Every step is observable. Every failure is traceable. The Vue application receives a single, coherent response in a shape it can consume without transformation.

What comes next

This article built the BFF service from structure to running implementation. The next article builds the other side of the contract — the Vue 3 API layer: composables that consume the BFF, typed against the generated OpenAPI spec, with error handling and loading states that map cleanly to what the BFF returns.

☰ Series navigation

This is not a rhetorical question. All three patterns address the same underlying tension — the mismatch between what backend services expose and what frontend clients need — but they address it differently, at different layers, with different cost profiles and different failure modes. Choosing the wrong abstraction early is expensive to undo. Choosing the right one requires understanding not just what each pattern does, but what each pattern is designed to resist.

This article gives each pattern a fair hearing, identifies where each genuinely wins, and then addresses the question every architect eventually faces: can they coexist, and if so, how?

The common problem, three different answers

All three abstractions exist because of the same structural tension: backend services are organised around domain entities and service boundaries; frontend clients are organised around screens, interactions, and user tasks. These two organisational principles produce different, often incompatible data shapes.

The three patterns answer this tension differently:

• API Gateway says: standardise the entry point, enforce cross-cutting concerns, and route requests to the right service — but leave shape and aggregation to the client or the services themselves.

• GraphQL says: let the client declare exactly what data it needs in a single query, and build a schema that spans service boundaries so the server can resolve it.

• BFF says: create a dedicated server-side layer, owned by the frontend team, that aggregates and shapes data specifically for one client surface.

Each answer implies a different locus of complexity. API Gateway concentrates complexity in infrastructure. GraphQL concentrates it in the schema and resolver layer. BFF concentrates it in the service itself. Where you want that complexity to live — and who you want to own it — is a significant part of the decision.

API Gateway

What it is designed to do

An API Gateway sits at the network perimeter and handles concerns that apply uniformly across all traffic entering the system: authentication and authorisation enforcement, rate limiting, TLS termination, request routing, logging, and protocol translation. In Azure, this is Azure API Management. In AWS, it is Amazon API Gateway. In a self-managed cluster, it might be Kong or Nginx.

The Gateway's job is to be a consistent, reliable entry point — not to understand what any individual client needs from any particular service. It routes a request to the right upstream service and returns what that service returns, perhaps with light transformation, caching, or throttling applied.

Where it wins

Cross-cutting concerns at scale. Rate limiting, IP allowlisting, API key management, OAuth 2.0 token validation, and request logging are applied once, at the Gateway, and are invisible to every upstream service. Without a Gateway, each service implements these independently, inconsistently, and at higher total cost. This is the Gateway's clearest and most defensible value.

Protocol and version mediation. A Gateway can expose a REST interface in front of gRPC services, or route v1 requests to legacy services while v2 requests go to new implementations — without the client needing to know the upstream topology changed. This is particularly valuable during service migrations.

Traffic management. Circuit breaking, retry policies, canary routing, and A/B traffic splitting are Gateway-layer concerns that do not belong in application code. A well-configured Gateway protects upstream services from traffic spikes and provides the operational levers to manage deployments safely.

Where it falls over

It does not solve the aggregation problem. A Gateway routes requests; it does not compose them. A screen that requires data from four services still requires four round trips from the client, or a Gateway orchestration configuration so complex it is effectively a new service in disguise. Some Gateways support request aggregation through scripting (Kong's Lua plugins, APIM's policies), but this is instrumenting infrastructure to do application logic — a direction that leads to unmaintainable policy files.

It cannot be client-specific. A Gateway enforces the same behaviour for all clients. A web application, a mobile app, and a third-party integration all receive the same treatment. Response shapes cannot differ per client without replicating route configurations and transformation rules, which does not scale.

Frontend teams do not own it. The Gateway is typically owned by a platform or infrastructure team. A frontend team that needs a new field in a response shape, or a different error format, or a caching policy for a specific endpoint, must file a request and wait. This is not a process failure — it is the correct operational model for shared infrastructure. But it means the Gateway cannot provide the autonomy that makes BFF valuable.

The right use of API Gateway in a BFF architecture

API Gateway and BFF are not alternatives — they are layers. The Gateway handles what the Gateway is designed to handle: network-level concerns, security perimeter enforcement, traffic management. The BFF sits behind it and handles what the BFF is designed to handle: aggregation, shaping, and client-specific logic.

In the production system this series is based on, Azure API Management sits in front of the BFF service. APIM handles TLS termination, JWT validation at the network boundary, rate limiting, and request logging. The BFF handles everything downstream of that: Feide session management, upstream service aggregation, and Vue-specific response shaping. Neither layer does the other's job.

GraphQL

What it is designed to do

GraphQL is a query language and runtime that lets clients declare exactly what data they need in a single request. Rather than multiple endpoints returning fixed shapes, GraphQL exposes a single endpoint backed by a typed schema. The client sends a query document specifying which fields it needs; the server resolves the query by calling whatever data sources are necessary and returns exactly the requested fields.

In a microservices context, this typically means a GraphQL server (or federation layer) that stitches together schemas from multiple services and resolves queries by delegating to the appropriate service.

Where it wins

Client-driven data fetching. The defining advantage: the client gets exactly what it asks for, nothing more and nothing less. Overfetching and underfetching are structurally eliminated — or at least structurally addressable. A product team that iterates quickly on screens, changing which fields a component needs from sprint to sprint, does not need to modify a backend service or a BFF to change its data requirements. It changes the query.

Unified schema across services. A GraphQL federation layer provides a single, coherent graph that spans multiple backend services. From the client's perspective, there is one API. The fact that User comes from the identity service, Course comes from the course service, and Session comes from the scheduling service is invisible. This is genuinely powerful in systems with many services and complex cross-entity queries.

Introspection and tooling. GraphQL's introspection system means the schema is self-documenting and tooling (GraphiQL, Rover, generated TypeScript types via graphql-codegen) works out of the box. The development experience for querying data is hard to match.

Incremental adoption. A GraphQL schema can be introduced in front of existing REST services without replacing them. The GraphQL resolvers call the REST endpoints. This makes adoption less disruptive than a full architectural change.

Where it falls over

It does not eliminate the aggregation problem — it moves it. A GraphQL server still has to call multiple upstream services to resolve a query. The N+1 problem — where resolving a list of N items triggers N additional queries — is one of the most common production performance issues in GraphQL systems, and solving it requires the DataLoader pattern, batching strategies, and careful resolver design. This complexity is real and non-trivial.

Caching becomes harder. REST's GET semantics map naturally to HTTP caching. GraphQL queries are typically POST requests with variable query documents, which HTTP caches cannot cache at the network layer. Caching in GraphQL requires application-level cache implementations (persisted queries, response caching with cache hints, Apollo Cache), all of which add complexity. For systems where caching is a primary performance lever, this is a significant cost.

Security surface is wider and less obvious. A single endpoint that accepts arbitrary query documents is a different security model from discrete REST endpoints with defined inputs. Query depth limiting, query complexity analysis, and field-level authorisation all require explicit implementation. A naive GraphQL deployment is vulnerable to expensive query attacks that a REST API with fixed response shapes is not.

It is best owned by a team that knows it well. GraphQL federation, resolver design, DataLoader implementation, and schema governance are non-trivial specialisms. Teams adopting GraphQL without prior experience tend to underestimate the ongoing maintenance cost of schema evolution, breaking change management, and performance debugging. The tooling is excellent, but the learning curve is real.

Client-specified queries are a double-edged sword. The ability for clients to request arbitrary field combinations means the server cannot pre-optimise data fetching for known query patterns. A BFF, by contrast, knows exactly what every screen needs and can fetch exactly that — predictably, efficiently, with a query plan that never changes.

When GraphQL is the right choice over BFF

GraphQL genuinely outperforms BFF in two scenarios.

First, when the number of screens is large and they share overlapping data needs in complex, variable combinations. A content platform with hundreds of screen types, or a developer-facing API with many unknown consumers, benefits from GraphQL's flexibility in ways a BFF — designed for a finite set of known screens — does not.

Second, when product iteration velocity is high enough that the cost of updating a BFF endpoint for every UI change becomes a bottleneck. If engineers are changing which fields a component displays every sprint, and a BFF change is required for each change, the BFF is adding friction without adding enough stability to justify it. GraphQL's client-driven model removes that friction.

For the production education platform this series describes — a finite set of known screens, authenticated users with role-based data access, and specific caching requirements for institutional data — BFF was the right call. The screens were well-defined, the data relationships were consistent, and the security model (Feide token exchange, server-side sessions) required server-side ownership of the authentication boundary. GraphQL would have added schema complexity without providing flexibility the product needed.

Comparison at a glance

Coexistence: the architecture that actually works in production

The question "BFF vs API Gateway vs GraphQL" is framed as a choice. In practice, production systems at meaningful scale use more than one of these, because they solve different problems.

The most common and defensible combination is:

Client
  │
  ▼
API Gateway  ←── TLS, auth enforcement, rate limiting, logging
  │
  ▼
BFF Service  ←── Aggregation, shaping, session management
  │    │    │
  ▼    ▼    ▼
Upstream services

The Gateway provides network-level security and traffic management. The BFF provides client-specific API logic. Each layer does exactly one thing and does not bleed into the other's responsibilities.

Adding GraphQL into this picture is less common but not unusual, typically in one of two configurations:

GraphQL as the BFF's internal query mechanism. Rather than the BFF making REST calls to upstream services, it queries a GraphQL federation layer internally. The Vue application still talks REST to the BFF — it is shielded from GraphQL entirely. This gives the BFF the flexibility of GraphQL's data graph internally while maintaining a stable, cacheable REST contract externally. This configuration makes sense when upstream services are already federated under GraphQL and the BFF is being added in front of an existing system.

GraphQL exposed alongside the BFF for different consumers. The BFF serves the primary Vue web application. A separate GraphQL endpoint serves mobile applications or third-party developers who benefit from flexible querying. Both sit behind the same Gateway. This is the "one BFF per client surface" model applied to heterogeneous client types — web gets a BFF optimised for its screens, mobile and external consumers get GraphQL's flexibility.

What does not work is all three patterns collapsing into a single layer with no clear ownership boundaries. A GraphQL server that also enforces rate limits that also does session management is a system where no one understands why anything is configured the way it is, and where changes in one concern break another.

Making the call

The choice comes down to three questions, asked honestly:

Who owns the API layer? If the answer is "a platform team," Gateway-first is the natural model. If the answer is "the frontend team," BFF gives that team the autonomy its ownership implies. If the answer is "unclear," that ambiguity should be resolved before the architecture decision.

How well-defined are the client's data needs? Known screens with stable data requirements favour BFF — the predictability is a feature, not a limitation. Variable, exploratory, or numerous distinct query patterns favour GraphQL. Infrastructure-layer concerns with no client-specific logic favour Gateway only.

What is the team's operational capacity? GraphQL federation is not simple to operate. BFF adds a service to maintain. Gateway-only is the lowest operational floor. Be honest about what your team can sustain, and choose an architecture whose operational cost falls within that ceiling.

For the real production web app used as the model this series — a single Vue web application, authenticated via Feide, deployed to Azure, serving a defined set of screens for a specific user population — BFF behind an Azure API Management Gateway is the right architecture. The remaining articles build it out in full.

☰ Series navigation

The BFF contract — the API surface your application depends on — is the most consequential design decision in this architecture. Get it right and you have a clean, stable interface that lets the frontend move independently of upstream service changes. Get it wrong and you have a new layer that amplifies the coupling problems you were trying to solve, with the added pleasure of owning the infrastructure.

This article covers the four design concerns that determine which outcome you get: what aggregation actually means in practice, how to shape responses for the client rather than the domain, how to version the contract without recreating a backend team's problems, and where the boundary between BFF logic and upstream logic must be drawn and defended.

The examples and architecture decisions throughout are drawn from a production implementation built for a Norwegian enterprise in the education sector. Where the original system cannot be described in full, concepts have been generalised to meet NDA obligations — but the engineering trade-offs, the failure modes, and the decisions that shaped the final design are real. We use VueJS and .NET Core as the example frameworks since it's based on the real production project.

Aggregation is not just parallel fetching

The word "aggregation" in BFF descriptions usually conjures an image of parallel HTTP calls fanning out to multiple services and the results being merged before the response is returned. That is part of it. But treating aggregation as a mechanical fan-out pattern misses what makes it valuable — and what makes it dangerous.

Consider a dashboard screen in an education platform. The frontend needs: the authenticated user's profile and role, the list of courses they are enrolled in, the next three upcoming sessions, and a count of unread notifications. In a naïve aggregation implementation, the BFF fires four requests in parallel, waits for all four, and concatenates the results into a response object.

This works. It is also fragile in a way that becomes apparent under load.

A more considered design asks: what are the actual dependency relationships between these data sets? The course list depends on the user's organisation ID, which comes from the user profile. The session list is scoped to the course IDs returned by the course list. The notification count is independent. This is not a fan-out — it is a directed graph with two sequential phases:

Phase 1 (parallel):
  → GET /identity/users/{id}         → profile + orgId
  → GET /notifications/unread/count  → notificationCount

Phase 2 (parallel, depends on Phase 1):
  → GET /courses?orgId={orgId}       → courseIds
  
Phase 3 (depends on Phase 2):
  → GET /sessions?courseIds={...}&limit=3 → upcomingSessions

Treating this as a flat parallel fan-out would require either fetching all courses before knowing the org ID (not possible), or making the frontend responsible for the sequencing (which defeats the point). The BFF owns this orchestration — it understands the dependency graph and executes it efficiently, shielding the frontend from the fact that it exists.

This has a practical implication for implementation. In .NET Core, Task.WhenAll handles the parallel phases, and the sequential phases chain naturally:

// Phase 1: independent fetches in parallel
var (profile, notificationCount) = await (
    _userService.GetProfileAsync(userId),
    _notificationService.GetUnreadCountAsync(userId)
).WhenBoth();

// Phase 2: depends on profile
var courses = await _courseService.GetByOrgAsync(profile.OrgId);

// Phase 3: depends on courses
var courseIds = courses.Select(c => c.Id).ToArray();
var upcomingSessions = await _sessionService.GetUpcomingAsync(courseIds, limit: 3);

The aggregation logic lives in the BFF. The frontend makes one request and receives one coherent response. The dependency graph is invisible to the client.

When aggregation goes wrong

Two aggregation anti-patterns appear consistently in production BFFs.

The "God endpoint." A single endpoint that returns everything the application might ever need, used on multiple screens because it is convenient. The God endpoint inflates payload sizes, makes partial failure handling impossible, and couples unrelated features together. If a notification service outage should not take down the course list, they must not share an endpoint. Design endpoints around screen-level data contracts, not around service boundaries.

Cascading failure without isolation. If Phase 2 in the example above fails because the course service is down, a poorly designed BFF either returns a 500 (crashing the whole screen) or silently swallows the error (showing stale or empty data with no indication of the problem). The correct design is explicit partial failure handling: return what succeeded, mark what failed, and let the frontend decide how to render a degraded state.

public record DashboardResponse(
    UserProfile Profile,
    IReadOnlyList<Course> Courses,
    IReadOnlyList<Session> UpcomingSessions,
    int NotificationCount,
    IReadOnlyList<string> PartialFailures  // e.g. ["courses", "sessions"]
);

This is not error handling for its own sake. It is a deliberate contract: the BFF guarantees it will always return a structurally valid response, and the Vue component decides what to render when parts of it are empty.

Response shaping: the frontend owns the shape

The single most impactful thing a BFF does is decouple the response shape from the domain model. This is also where engineers most frequently make the wrong call.

The wrong call is to return the upstream service's response more or less as-is, perhaps with light field selection. This is understandable — it is the path of least resistance, it keeps the BFF thin, and it avoids the question of what the "right" shape is. But it is not response shaping. It is proxying, and a proxy does not justify the overhead of a dedicated service.

Response shaping means designing the response around the component tree that will consume it. The question is not "what did the upstream service return?" but "what does the Vue component need, and in what shape does it need it?"

Flatten, don't nest

Domain models are frequently deeply nested because they reflect real-world entity relationships. Frontend components rarely need that nesting — they need flat data they can bind to template properties without traversal logic in the component.

An upstream Course entity might look like this:

{
  "id": "c-1",
  "metadata": {
    "title": "Mathematics — Year 9",
    "code": "MATH-9",
    "curriculum": {
      "framework": "NOR-K20",
      "subject": "Mathematics",
      "level": { "grade": 9, "label": "Year 9" }
    }
  },
  "enrollment": {
    "capacity": 30,
    "enrolled": 24,
    "waitlist": 2
  },
  "status": { "code": "ACTIVE", "since": "2024-08-15T00:00:00Z" }
}

A course card component in Vue needs: a title, a code, the enrollment fraction, and a status label. The BFF shapes this into:

{
  "id": "c-1",
  "title": "Mathematics — Year 9",
  "code": "MATH-9",
  "enrollmentLabel": "24 / 30",
  "enrollmentPercent": 80,
  "status": "Active",
  "activeFrom": "2024-08-15"
}

The component receives exactly what it renders. No traversal logic, no null-guard chains, no formatting in the template. The formatting decisions — how to display the enrollment fraction, how to present the date — are made once, in the BFF, and are consistent across every component that uses this data.

Computed fields belong in the BFF

The enrollment label and enrollment percentage in the example above are computed fields — they do not exist in the upstream response and must be derived. They belong in the BFF, not in the component.

The underlying principle: any derivation that is deterministic, presentation-oriented, and would be repeated across multiple components is a BFF concern. This includes percentage calculations, label generation, date formatting, status code translation, and currency formatting with locale awareness.

What does not belong in the BFF: business logic that should live upstream, validation that changes application state, or calculations that depend on runtime user input. The BFF is a rendering layer for data that is already computed — it is not a domain service.

Naming conventions are a contract decision

The upstream service uses enrollmentCapacity and enrolledCount. The BFF exposes enrollmentLabel and enrollmentPercent. The Vue component uses enrollmentLabel and enrollmentPercent.

This means your BFF's property names are part of its contract with the frontend. Changing enrollmentLabel to enrollmentText is a breaking change, even if the value is identical. Name properties for their rendering purpose, not their origin, and treat them with the same stability you would expect from any API you consume.

In practice, this argues for establishing naming conventions before writing the first endpoint and enforcing them through code review. Consistency in the contract reduces cognitive load on both sides of it.

Versioning: the problem you are creating

A BFF contract is an API. APIs have versions, and versions accumulate. This is the most underspecified aspect of BFF design in most articles, because it is uncomfortable to discuss — you are creating a versioning problem in order to solve a coupling problem, and the question is whether the trade is favourable.

There are three approaches, each with a clear use case.

URL versioning for major breaking changes

GET /api/v1/dashboard
GET /api/v2/dashboard

URL versioning is the most visible, most explicit, and most operationally expensive approach. It is appropriate when a response shape change is so significant that the old and new shapes cannot coexist under one contract — for example, when a screen is redesigned and the data model changes completely.

The operational cost is that both versions must be maintained simultaneously during the migration period, and the migration period in practice extends far longer than anticipated. Budget for it.

Header versioning for incremental evolution

GET /api/dashboard
Accept: application/vnd.bff.dashboard+json; version=2

Header versioning keeps URLs stable and moves the version negotiation into headers. It is cleaner for incremental evolution — adding fields, changing response structure within a stable conceptual model — and it does not require duplicating route definitions. The cost is that it is less discoverable and requires slightly more discipline in the client to set the header correctly.

Additive-only evolution: the best versioning strategy

The most effective versioning strategy is one you do not need. If the BFF contract evolves additively — new fields are added, existing fields are never removed, semantics never change — versioning becomes a maintenance concern rather than a migration project.

This is achievable in practice with two rules:

Never remove a field. If a field is no longer needed by the frontend, mark it as deprecated in internal documentation and stop populating it (return null), but leave it in the response schema. Removal is a v2 concern.

Never change the semantics of an existing field. If status currently returns "Active" and you need it to return a structured object, that is a new field — statusDetail — not a change to status. The original field continues as-is.

Additive-only evolution is not infinitely sustainable — response shapes accumulate cruft over time — but it defers versioning costs to the natural cadence of major releases rather than introducing them with every sprint.

The boundary: what belongs in the BFF

This is the question that determines whether your BFF stays healthy or becomes the new monolith. The answer is a firm principle rather than a checklist: the BFF transforms and aggregates; it does not originate.

What this means in concrete terms:

BFF owns

• Response aggregation: combining data from multiple upstream services into a single response shaped for the Vue component

• Field selection and projection: choosing which upstream fields to include and which to omit

• Presentation-layer computation: formatting, label generation, percentage derivation, date localisation

• Authentication enforcement: validating the session, exchanging tokens, enforcing access before any upstream call is made

• Caching of presentation-layer data: caching aggregated, shaped responses where staleness is acceptable

• Error translation: converting upstream error codes into client-meaningful error shapes

Upstream services own

• Business rules: what constitutes a valid enrollment, whether a course is at capacity, eligibility logic

• Domain validation: ensuring data integrity constraints are enforced at the source of truth

• State mutation: creating, updating, and deleting domain entities

• Cross-entity consistency: ensuring that a session cannot reference a deleted course

The grey area: where teams disagree

The genuinely contested cases are usually one of two types:

Computed fields that require domain knowledge. Is isEnrollmentOpen — a boolean derived from enrollment capacity and a business rule about the waitlist threshold — a presentation concern or a domain concern? The answer: if the rule could change (and business rules do change), it belongs upstream. The BFF should receive a pre-computed enrollmentStatus from the course service, not derive it locally. A BFF that embeds business rules is a BFF that becomes inconsistent with the backend when those rules change.

Input validation on write endpoints. The BFF handles write operations too — course enrollments, session registrations. Validation that is purely structural (is this field present, is this ID a valid UUID format) is reasonable in the BFF as a fast-fail before the upstream call. Validation that is semantic (is this user eligible to enroll in this course) must happen upstream. Drawing the line here prevents a situation where the BFF and the upstream service have conflicting validation logic.

A practical heuristic: if a product manager could change the rule in a sprint, it belongs upstream. If it is structural and invariant (a user ID is always a UUID), it is acceptable in the BFF.

Designing for the Vue component tree

The most useful frame for BFF endpoint design is not "what data does this screen need?" but "what does the Vue component tree look like, and what does each component expect from its props?".

A screen is composed of components. Each component has a data contract — its props interface. The BFF response should map cleanly onto that props interface, ideally such that a single destructure in the composable produces the data each component needs without further transformation.

In practice this means walking the component tree before designing the endpoint:

DashboardView
├── UserProfileCard        → { displayName, role, avatarUrl }
├── CourseListPanel
│   └── CourseCard (×n)   → { id, title, code, enrollmentLabel, status }
├── UpcomingSessionsList
│   └── SessionItem (×n)  → { id, title, startsAt, courseTitle, locationLabel }
└── NotificationBadge      → { count }

The BFF endpoint for this screen returns an object that mirrors this structure:

{
  "user": {
    "displayName": "Ingrid Solberg",
    "role": "Teacher",
    "avatarUrl": "/avatars/i-solberg.jpg"
  },
  "courses": [
    { "id": "c-1", "title": "Mathematics — Year 9", "code": "MATH-9",
      "enrollmentLabel": "24 / 30", "status": "Active" }
  ],
  "upcomingSessions": [
    { "id": "s-1", "title": "Integration review", "startsAt": "2025-04-08T09:00:00",
      "courseTitle": "Mathematics — Year 9", "locationLabel": "Room 204" }
  ],
  "notifications": { "count": 3 }
}

The Vue composable for this screen receives this response and distributes it to components without further transformation:

const { data } = useDashboard()

// Each ref maps directly to a component's props
const user = computed(() => data.value?.user)
const courses = computed(() => data.value?.courses ?? [])
const upcomingSessions = computed(() => data.value?.upcomingSessions ?? [])
const notificationCount = computed(() => data.value?.notifications.count ?? 0)

No adapter logic. No field mapping. The BFF contract and the component props interface are aligned by design.

A note on OpenAPI and type safety

A BFF contract without a schema is a verbal agreement. It will drift. The response shape the BFF returns today will not match what the Vue components expect in three months, and you will discover the mismatch at runtime.

The mitigation is simple and should be non-negotiable: define the BFF contract with OpenAPI, generate TypeScript types from it, and import those types into the Vue application. Changes to the BFF response shape become compile-time errors in the frontend before they reach the browser.

In .NET Core, Swashbuckle generates an OpenAPI spec from controller or Minimal API route definitions automatically. In Vue 3, openapi-typescript or @hey-api/openapi-ts generates typed interfaces from that spec. The generation step belongs in the build pipeline, not as a manual step.

This is not optional complexity. A BFF that lacks type-safe contracts between its two surfaces — the upstream services and the Vue client — is a BFF that will break silently in production.

What comes next

This article has covered the design principles that govern a well-structured BFF contract. The next article steps back before the implementation begins to address the comparative question that should be answered before writing any code: how does BFF compare to API Gateway and GraphQL as architectural options, where does each pattern win, and where do they coexist?

☰ Series navigation

Your frontend has outgrown the API it was given.

At some point, most frontend teams hit the same wall. The backend exposes what it knows — resources, entities, service boundaries — and the frontend is left stitching four API calls into a single screen, massaging data shapes the UI never asked for, and writing adapter logic that has no good place to live. The Backend for Frontend pattern is the answer to that wall. But it comes with a cost: an additional service to build, deploy, and own. This series makes the case for that trade-off — and equally, for the cases where it is not worth making. The examples and architecture decisions throughout are drawn from a production implementation built for a Norwegian enterprise in the education sector. Where the original system cannot be described in full, concepts have been generalised to meet NDA obligations — but the engineering trade-offs, the failure modes, and the decisions that shaped the final design are real.

The problem, stated plainly

Before defining what a BFF is, it is worth being precise about what problem actually warrants one.

Imagine a dashboard screen in an education platform. It needs to render: the current user's profile and role, their organisation's enrolled courses, upcoming sessions for the current week, and unread notifications. In a system where services are organised around domain entities, that screen requires calls to at least four separate endpoints — likely across two or three different services. The responses come back in shapes optimised for storage and domain logic, not for what this particular screen needs.

The frontend handles it. It fires the requests, waits for them to resolve, merges the data, filters out the fields it does not need, transforms date formats, normalises inconsistent ID conventions between services, and then renders. This works. It is also a slow, fragile, and increasingly expensive pattern at scale.

Three specific failure modes appear consistently once systems grow:

Overfetching and underfetching. REST endpoints designed around domain entities return either too much or too little for any given screen. A GET /users/{id} response that includes billing history, audit logs, and security settings satisfies the account settings page — but it is wasteful when all the dashboard needs is a display name and an avatar URL. Conversely, a screen requiring data from three different resource types must make three round trips, each adding latency, each adding a potential failure point.

Adapter logic with no home. The gap between what upstream services return and what the frontend needs gets filled somewhere. In the absence of a dedicated layer, it lands in the frontend itself — in Vuex stores, in composables, in utility functions scattered across the codebase. This logic is hard to test in isolation, invisible to the backend teams who changed the API shape that broke it, and re-implemented separately for each client surface (web app, mobile app, third-party integration).

Security and session complexity pushed to the client. When the frontend talks directly to multiple APIs, it must manage tokens for each of them, handle token refresh across parallel requests, and decide what to expose in the browser. This is not where security boundaries should be drawn. The browser is not a trusted environment, and treating it as one creates problems that are difficult to retrofit away later.

None of these problems are fatal on their own, early in a product's life. The question is what you reach for when they compound — and BFF is one answer, not the only one.

What BFF actually is

The Backend for Frontend pattern, first articulated by Sam Newman in the context of microservices architecture, is straightforward in principle: create a dedicated backend service for each distinct frontend client, owned by the frontend team, whose sole responsibility is serving that client's specific needs.

The key words are dedicated and owned by the frontend team. A BFF is not a general-purpose API gateway. It is not a shared middleware layer. It is a service that knows exactly one consumer — your frontend — and is optimised entirely for that consumer's needs. It aggregates calls to upstream services, shapes responses into exactly what the UI requires, handles authentication at the boundary, and shields the frontend from the complexity and instability of the services behind it.

The Vue application has one API contract to reason about: the BFF. It does not know or care how many upstream services exist, how they are versioned, or what their response shapes look like. That complexity lives in the BFF, where it can be tested, versioned, and changed independently.

The BFF can do several things the frontend cannot do cleanly on its own: it can fire multiple upstream requests in parallel and merge the results before responding; it can cache aggressively for data that does not change per-request; it can enforce authentication and authorisation before a single upstream call is made; and it can translate between authentication contexts — for example, exchanging a session cookie for a service-to-service token without ever exposing a bearer token to the browser.

What BFF actually costs

This is where most introductory articles skip ahead too quickly. The BFF pattern is genuinely useful — but the version of it that works in production looks different from the version described in architecture blog posts, and the gap is filled with operational cost.

You are taking on a new service. This sounds obvious but its implications are underestimated. A new service means a new deployment pipeline, a new container to monitor, a new set of logs to aggregate, a new failure mode to handle, a new component in your runbook. If your team does not already own infrastructure or has not previously maintained a backend service, the operational learning curve is real. The BFF will go down. It will have bugs. It will need updating when upstream services change their contracts. These are not hypothetical costs — they are the routine maintenance costs of any production service, and they do not disappear because the service is thin.

The BFF becomes a coupling point. When your Vue application and your upstream services are decoupled by a BFF, the BFF is not free of coupling — it absorbs it. Every upstream API change that affects the frontend now requires a BFF change too. In a fast-moving system, this can mean the BFF becomes a bottleneck: a place where changes must land before they can reach the frontend. The team that owns the BFF becomes the team that must be unblocked first.

Latency is not free. A BFF adds one network hop between the browser and its data. For most production deployments — where the BFF and its upstream services are colocated in the same cloud region — this hop is in the single-digit milliseconds. But it exists, and for systems already operating close to latency budgets, it matters. The mitigation is co-deployment discipline and caching, both of which require deliberate effort.

The BFF can become a dumping ground. This is the failure mode no one talks about in architecture talks. A BFF that starts as a clean aggregation layer accumulates business logic over time. A validation rule here, a conditional transform there, a calculation that "just needs to live somewhere." Left unchecked, a BFF becomes a monolith with the word "frontend" in its name. The discipline to keep it thin — a translator and aggregator, not a domain engine — is cultural as much as technical, and it requires active enforcement.

When BFF is worth it

With that context established, the cases where BFF earns its overhead are clearer.

Multiple upstream services, single UI surface. If your frontend needs to aggregate data from three or more independent services for routine screens, the aggregation cost is already being paid somewhere. Paying it in the BFF — where it can be tested, cached, and monitored — is better than paying it in the client or across a distributed chain of sequential API calls.

Multiple client surfaces with diverging needs. A web application, a mobile app, and a third-party integration consume fundamentally different API shapes. A response payload appropriate for a desktop dashboard is wasteful over a mobile connection. A BFF per client surface means each client gets exactly what it needs, without the upstream services needing to know or care about client-specific requirements. This is the original use case Sam Newman described, and it remains the strongest one.

Security boundary clarity. If your system involves tokens that must never reach the browser, or authentication flows that require server-side session management — as is the case with Feide, the Norwegian government identity provider used in this series — a BFF gives you a clean place to draw the security perimeter. The BFF holds the session, manages token exchange, and the browser only ever receives a cookie. This is the Token Handler pattern, and it is substantially harder to implement correctly without a dedicated server-side layer.

Unstable upstream contracts. In a microservices environment where teams are moving fast and breaking things at the API layer, a BFF acts as a translation buffer. When an upstream service changes its response shape, you update the BFF. The Vue application is insulated. Without the BFF, that upstream change propagates directly into frontend code — often discovered at runtime rather than compile time.

Team ownership alignment. Perhaps the least technical but most practically important factor: if the frontend team has the capacity to own a backend service, a BFF gives them the autonomy to move at their own pace without being blocked on backend teams for API shape changes. This is an organisational argument as much as an architectural one, and it should be evaluated as such.

When BFF is not worth it

This section is the one most articles omit. The BFF pattern has a real overhead floor that you pay regardless of system complexity. Below a certain threshold, that floor is higher than the problems it solves.

Small teams moving fast on a single surface. If you have one frontend, one backend, and a team of three engineers, a BFF introduces a coordination overhead between your own people that does not exist if the frontend talks directly to the API. The aggregation and shaping problems are real, but they are solvable with thoughtful API design, GraphQL, or simply accepting a thin amount of adapter logic in the frontend until the system is large enough to justify more structure.

A well-designed monolithic API. If your backend already returns response shapes close to what the frontend needs — because the backend team works closely with the frontend team, or because the API was designed frontend-first — a BFF adds a layer without adding meaningful value. The problem a BFF solves is the impedance mismatch between backend domain models and frontend presentation needs. If that mismatch is small, the solution is disproportionate.

Early-stage products with unstable requirements. A BFF contract between the frontend and its upstream services is another API surface to maintain. In the early life of a product, when screen designs change weekly and domain models are still being discovered, the BFF becomes a change multiplier: every significant UI change requires a frontend change, a BFF change, and potentially an upstream change. The stability that makes a BFF valuable is the same stability that is absent in early-stage development.

Teams without infrastructure ownership. If your team has never maintained a deployed service — never dealt with container health checks, never written a deployment pipeline, never handled a 3am incident for something they own — adopting a BFF in production is learning two hard things simultaneously: the architecture and the operations. This is not a reason to avoid BFF permanently, but it is a reason to be honest about timing and capacity.

The decision framework

Rather than a checklist, use three questions. If the answer to fewer than two is "yes," the BFF overhead is likely not justified at this stage.

Does your frontend aggregate data from three or more independent services for routine operations? If most screens require only one or two API calls that already return the right shape, the aggregation value proposition is weak.

Do you have a meaningful security or session management requirement that cannot be cleanly handled in the client? If your authentication flow is stateless, token-based, and entirely client-managed, the security argument for BFF does not apply. If you are dealing with server-side sessions, token exchange, or an identity provider like Feide that requires server-side handling, it does.

Does your team have the capacity to own and operate a backend service independently? This means a deployment pipeline, monitoring, alerting, runbooks, and the willingness to be on-call for it. BFF without operational ownership is technical debt in a server rack.

What this series covers from here

The rest of this series assumes the answer is "yes, BFF is the right call." If it is not — if you read this article and concluded that your system is not there yet — the single most useful thing you can do is bookmark the decision framework above and revisit it in six months. Architecture decisions should trail system complexity, not lead it.

For those continuing: the next article addresses how to design the BFF contract itself — what belongs inside it, what must stay in upstream services, and how to version the API surface you are creating without recreating the problems you were trying to solve.

The implementation articles that follow use .NET Core Minimal APIs for the BFF service, Vue 3 composables for the client-side API layer, Feide for authentication, and Azure Container Instances for deployment. Each article is self-contained, but the architecture decisions made in the early articles carry forward — so reading in order is the path of least resistance.

☰ Series navigation

"Every frontend eventually outgrows the API it was given. The BFF pattern is not about adding a layer — it's about taking ownership of the interface between your product and its backend, on your terms. This series is for engineers who want to understand the trade-offs before they commit to the architecture."

Series Guideline

Part I: Foundations (Concepts and Architecture)

• Article 1: What Is BFF — and When Is It Actually Worth It?
  The problem it solves, the cost it introduces, and the honest answer on when not to use it.

• Article 2: Designing the BFF Contract: Request Aggregation & Client-Specific Shaping
  API design principles, response shaping, versioning strategy, and what belongs in the BFF vs upstream services.

• Article 3: BFF vs API Gateway vs GraphQL: Picking the Right Abstraction
  Comparative analysis with real trade-offs. Where each pattern wins, where it falls over, and how they can coexist.

Part II: Implementation (Code)

• Article 4: Building the BFF in .NET Core: Minimal APIs, Routing & Aggregation
  Standing up the BFF service, aggregating upstream calls, shaping responses, and handling errors with real code.

• Article 5: The Vue 3 API Layer: Composables, Error Boundaries & Type Safety
  Building a clean, typed client-BFF contract in Vue 3. useApi composables, error handling strategies, and OpenAPI codegen.

• Article 6: Auth at the Boundary: Integrating Feide Identity via the BFF
  Connecting the BFF to Feide — Norway's government-issued identity provider for educational organisations. OAuth 2.0 + OIDC flow, the Token Handler pattern, and why cookie-based sessions beat tokens in the browser.

• Article 7: Shipping to Azure: Docker Images, Artifact Publishing & Azure Container Instances
  Full IaaS deployment pipeline — building and tagging Docker images, publishing artifacts, and running the BFF on Azure Container Instances. Includes Azure Front Door routing and when API Management adds value vs noise.

Part III: Production & Operations (Ops)

• Article 8: Testing the BFF: Unit, Integration & Contract Tests
  A layered testing strategy for the BFF. WebApplicationFactory for integration tests, Pact for consumer-driven contract testing with Vue.

• Article 9: Observability: Structured Logging, Distributed Tracing & Azure Application Insights
  End-to-end traceability across Vue → BFF → upstream services using Azure Application Insights. Correlation IDs, structured logs with Serilog, custom telemetry, and Application Insights dashboards and alerts.

Supplementary articles

• Caching in the BFF: In-Memory, Redis & Response Caching
  Where caching belongs in a BFF architecture, how to avoid stale-data bugs, and cache invalidation patterns.

• Brownfield Migration: The Strangler Fig Approach to BFF Adoption
  Incrementally introducing a BFF in front of an existing monolith or REST API without a big-bang rewrite.

• Resilience Patterns: Circuit Breakers, Retries & Timeouts with Polly
  Making the BFF fault-tolerant using Polly. Handling partial upstream failures gracefully in aggregated responses.

☰ Series navigation

Browsers are not.

If you’ve implemented WebAuthn in a real PWA, you already know this:
The spec is clean. The user experience is not.

The uncomfortable truth is this:

Most authentication systems fail because of UX, not because of broken cryptography.

WebAuthn gives us origin binding, challenge–response, and public-key authentication. That’s beautiful. But what users actually interact with is:

• A browser modal.

• An OS biometric sheet.

• A permission dialog.

• A vague error message.

• A “NotAllowedError”.

And those surfaces shape behavior more than any algorithm ever will.

Let’s examine how browser and OS UX decisions constrain authentication design — and why UX discipline is often more important than cryptographic strength.

1. Browser and OS UX Constrain Your Architecture

When you call:

await navigator.credentials.get({
  publicKey: options
});

You are not in control anymore.

The browser:

• Decides how the prompt looks.

• Decides when it appears.

• Decides how cancellation behaves.

• Decides what error is returned.

• Delegates to the OS for biometric UI.

Your PWA is a spectator.

Example: Timing Assumptions

You might assume:

• The WebAuthn prompt appears immediately.

• The user understands what is happening.

• Cancellation is intentional.

In reality:

• On Chrome desktop, the modal may appear inline.

• On Safari (macOS), Touch ID sheet drops from the top.

• On iOS Safari, Face ID overlay obscures the entire screen.

• On Android Chrome, the prompt may feel like a system dialog unrelated to your app.

Your architecture must not depend on:

• Specific timing.

• Specific modal appearance.

• Immediate resolution.

This is not a cosmetic issue. It affects retry logic and fallback strategy.

2. The Same WebAuthn Flow Feels Different Everywhere

The WebAuthn API is standardized.

The UX is not.

Chrome (Desktop)

• Inline modal.

• Clear “Use another device” option.

• Relatively consistent error messaging.

Safari (macOS)

• OS-native Touch ID sheet.

• Less explicit fallback controls.

• Errors often appear as generic cancellation.

iOS Safari

• Full-screen Face ID overlay.

• Sometimes minimal explanation.

• Cancellation feels like app failure.

Android Chrome

• OS biometric dialog.

• Slightly different copy.

• Device PIN fallback flows vary by manufacturer.

Your code may be identical:

try {
  const assertion = await navigator.credentials.get({ publicKey: options });
} catch (err) {
  handleError(err);
}

But err.name and user interpretation differ.

Real Example: Cancellation Handling

Common error:

DOMException: NotAllowedError

This can mean:

• User cancelled.

• Timeout expired.

• Platform authenticator unavailable.

• Permission denied.

From your frontend perspective:

catch (err) {
  if (err.name === "NotAllowedError") {
    showRetry();
  }
}

But retry logic must consider:

• Did the user intentionally cancel?

• Did the biometric sensor fail?

• Is WebAuthn unsupported?

If you misinterpret cancellation as attack — you create lockouts.

If you misinterpret failure as benign — you create confusion.

UX interpretation is part of your threat model.

3. Permission Dialogs Shape Security Outcomes

Consider initial WebAuthn registration:

await navigator.credentials.create({
  publicKey: options
});

Browser may ask:

• “Allow this site to use your security key?”

• “Allow Touch ID for this site?”

If your UI does not clearly prepare the user:

• The permission dialog feels suspicious.

• The user cancels reflexively.

• They choose fallback instead.

Repeated friction trains users to:

• Prefer weaker flows.

• Avoid passwordless enrollment.

Strong crypto loses to confusing UX.

4. Retry Flows Influence Security Behavior

Imagine this frontend flow:

async function startWebAuthn(options) {
  try {
    const assertion = await navigator.credentials.get({ publicKey: options });
    await verify(assertion);
  } catch (err) {
    showRetry();
  }
}

If “Retry” automatically triggers WebAuthn again without context, users may:

• Rapidly cancel.

• Assume something is broken.

• Switch to fallback.

Instead, better UX:

if (err.name === "NotAllowedError") {
  showMessage("Authentication was cancelled. Try again or use Feide login.");
}

Explicit fallback messaging prevents:

• Panic.

• Repeated failure loops.

• Insecure workaround requests (“Can you disable this for me?”).

Retries are not neutral. They shape behavior.

5. Browser UX Affects Security Perception

Security systems rely on trust perception.

If the browser modal:

• Looks native and familiar → user trusts it.

• Looks alien or unexpected → user suspects phishing.

That’s why WebAuthn is powerful:

Origin binding ensures the browser only shows credentials for the correct site.

But the user doesn’t see origin binding.
They see a modal.

Your UI must:

• Clearly explain what is about to happen.

• Avoid surprising transitions.

• Avoid triggering WebAuthn automatically without context.

Example:

Instead of immediately calling WebAuthn:

<button @click="authenticate">
  Sign in with device
</button>

Make the user initiate the action.

User agency increases trust.

6. Why Good UX Prevents Insecure Workarounds

Users do not attack your system.

They bypass it.

If passwordless is confusing, they will:

• Ask support to disable it.

• Request email-based fallback.

• Demand “simpler login”.

If fallback is weak, security erodes.

Good UX reduces these pressures.

Example: Clear device management UI.

Instead of hiding credentials:

var devices = await _db.WebAuthnCredentials
    .Where(c => c.UserId == user.Id)
    .ToListAsync();

Expose:

• Device name

• Registration date

• Revoke button

Transparency builds confidence.

7. Browser Constraints Affect Architecture

You cannot:

• Customize biometric prompt text.

• Force specific fallback options.

• Guarantee consistent timing.

Therefore, architecture must:

• Avoid assuming prompt content.

• Avoid assuming immediate response.

• Support retry and fallback cleanly.

• Log error patterns per browser.

Operationally, track:

• WebAuthn failures by user agent.

• Cancellation frequency.

• Fallback usage rates.

UX metrics are security metrics.

8. Cryptography vs Behavior

WebAuthn’s cryptography is solid:

• Public key signatures.

• Origin binding.

• Replay protection.

• Counter tracking.

But if:

• Users disable it.

• Enrollment fails.

• Recovery is confusing.

• Fallback is hidden.

Then strong algorithms lose to weak experience.

The most secure system is the one users willingly use.

Final Reflection

Security engineers love to debate:

• Key lengths.

• Counter semantics.

• Attestation policies.

But in real deployments, the bigger questions are:

• Did the user understand what just happened?

• Did the retry flow make sense?

• Did cancellation feel safe?

• Did fallback feel legitimate?

• Did the browser modal align with user expectations?

Browser UX is not decoration layered on top of cryptography.

It is the environment in which cryptography lives.

WebAuthn’s design is brilliant.

But the success of a passwordless-first PWA depends less on elliptic curves — and more on how gracefully your system handles human uncertainty.

Stronger algorithms improve theoretical security.

Clearer UX improves actual security.

And in production systems, actual security is the only kind that matters.

☰ Series Navigation

Core Series

• Introduction

• Article 1 — Authentication is Not Login

• Article 2 — What “Passwordless” Actually Means

• Article 3 — WebAuthn & FIDO2, Explained Without the Spec

• Article 4 — OpenID Connect as the Glue

• Article 5 — Designing a Passwordless-First PWA Architecture

• Article 6 — UX and Failure Are Part of the Security Model

• Article 7 — A Real Passwordless PWA Flow (Architecture Walkthrough)

• Article 8 — Implementing WebAuthn in Practice

• Article 9 — Integrating OIDC (Feide) as Fallback and Recovery

• Article 10 — What Worked, What Didn’t, What I’d Change

Optional Extras

• Why Passwordless Alone Is Not an Identity Strategy

• → How Browser UX Shapes Security More Than Cryptography

• No passwords.

• No phishing.

• No credential stuffing.

• Biometric UX.

• Public-key cryptography.

It feels like the final answer.

But WebAuthn answers exactly one question:

Can this device prove control of a credential for this origin right now?

It does not answer:

• Who is this user across systems?

• What happens if the device is lost?

• How do we bootstrap identity?

• How do we link accounts?

• How do we recover?

• How do we federate across institutions?

Passwordless authentication solves proof of possession.

Identity strategy solves continuity over time.

Those are different problems.

The Illusion of “Pure Passwordless”

It’s tempting to imagine a system that:

• Only uses WebAuthn

• Has no identity provider

• Has no fallback

• Has no recovery flow

On paper, that sounds maximally secure.

In reality, it’s brittle.

Let’s walk through real scenarios.

Scenario 1 — Device Loss

User registers WebAuthn credential.

All good.

Then:

• Phone is lost.

• Laptop is replaced.

• Browser storage is cleared.

Now what?

Without fallback:

• The account is inaccessible.

• Support must intervene manually.

• Or recovery becomes weak (email-only reset).

If recovery is ad hoc, security erodes.

If recovery is absent, usability collapses.

This is why fallback is not compromise — it is necessity.

Fallback Is a Design Requirement

Fallback should not mean:

“Use a weaker method.”

It should mean:

“Use an alternate trust anchor.”

In your architecture, that trust anchor was Feide (OIDC).

WebAuthn provided:

• Device-bound possession proof.

Feide provided:

• Federated identity continuity.

That layering is deliberate.

Passwordless Without Federation Breaks at Scale

In a real system:

• Users change devices.

• Users move institutions.

• Accounts are deactivated upstream.

• Identity policies change.

Without federation:

• You must manage identity lifecycle yourself.

• You must build account verification logic.

• You must build secure recovery flows.

• You must handle identity merging.

That is significantly more complex than integrating an IdP.

Enrollment Is Identity Design

Enrollment is often treated as a one-time setup.

It is not.

Enrollment defines:

• Who is allowed to create a credential?

• How is that identity verified?

• What trust anchor validates the user at registration?

Example (ASP.NET Core + OIDC bootstrap):

var externalUserId = claims.FindFirst("sub")?.Value;

var user = await FindOrCreateUser(externalUserId);

if (!user.WebAuthnCredentials.Any())
{
    return Redirect("/enable-passwordless");
}

Notice what happened:

• OIDC verified identity.

• Only then did WebAuthn credential get registered.

WebAuthn did not create identity.

It attached to it.

That ordering matters.

Recovery Is Where Identity Strategy Is Tested

The real test of maturity is not login success.

It’s failure recovery.

Lost device flow:

1. User authenticates via OIDC.

2. System validates sub claim.

3. Existing WebAuthn credentials are revoked.

4. New device registers fresh credential.

Example revocation logic:

_db.WebAuthnCredentials.RemoveRange(user.WebAuthnCredentials);
await _db.SaveChangesAsync();

Then redirect to registration.

This is structured recovery.

Without OIDC, you would need:

• Email-only verification

• Manual admin override

• Or permanent account loss

None of those scale securely.

Device-Bound Authentication Is Not Portable Identity

WebAuthn credentials are bound to:

• Origin

• Device

• RP ID

They are intentionally non-transferable.

That’s why they’re secure.

But identity is portable.

Identity must:

• Survive device turnover

• Integrate with external systems

• Be recognized across services

That’s federation.

Federation Is Not the Enemy of Passwordless

There’s a misconception:

“If I use OIDC fallback, I weaken passwordless.”

That only happens when fallback bypasses verification.

In your architecture:

• OIDC never created a session automatically.

• Backend validated ID token.

• Internal user mapping occurred.

• HTTP-only cookie issued by your system.

OIDC proved identity.

WebAuthn proved possession.

The trust boundaries remained intact.

Architectural Maturity Means Layering

Let’s describe the trust model clearly.

Layer 1: Federation (Feide)

• Asserts institutional identity

• Manages upstream lifecycle

• Provides recovery

Layer 2: Passwordless (WebAuthn)

• Proves device possession

• Phishing-resistant

• Per-origin authentication

Layer 3: Session (HTTP-only cookie)

• Server-controlled

• Revocable

• Protected from JS

Layer 4: Authorization

• Application-level access control

• Role management

Each layer solves a different problem.

No single layer replaces the others.

The Real Question

When designing authentication, the mature question is not:

“How do we eliminate passwords?”

It is:

“How do we design identity continuity over time?”

Passwordless improves authentication strength.

Federation ensures identity stability.

Together, they create resilience.

What Happens If You Ignore This

If passwordless stands alone:

• Enrollment becomes fragile.

• Recovery becomes weak.

• Identity merging becomes manual.

• Device loss becomes support nightmare.

• Organizational integration becomes impossible.

The system becomes secure in theory, brittle in reality.

The Strategic Insight

Passwordless is a mechanism.

Identity strategy is a lifecycle.

Mechanisms can be secure.

Lifecycles must be resilient.

Your architecture works because:

• It does not idolize passwordless.

• It positions WebAuthn as primary.

• It retains OIDC as structured fallback.

• It treats recovery as planned, not emergency.

• It separates identity from possession.

That separation is the mark of architectural maturity.

Final Reflection

Passwordless alone is not enough.

Not because it’s weak.

But because identity is larger than authentication.

A secure system must answer:

• Who are you?

• Can you prove it now?

• What happens if you lose your device?

• How do we recognize you tomorrow?

• How do we integrate with your organization?

WebAuthn answers one of those questions exceptionally well.

Federation answers the rest.

Designing both — intentionally — is what turns passwordless from a feature into an identity strategy.

☰ Series Navigation

Core Series

• Introduction

• Article 1 — Authentication is Not Login

• Article 2 — What “Passwordless” Actually Means

• Article 3 — WebAuthn & FIDO2, Explained Without the Spec

• Article 4 — OpenID Connect as the Glue

• Article 5 — Designing a Passwordless-First PWA Architecture

• Article 6 — UX and Failure Are Part of the Security Model

• Article 7 — A Real Passwordless PWA Flow (Architecture Walkthrough)

• Article 8 — Implementing WebAuthn in Practice

• Article 9 — Integrating OIDC (Feide) as Fallback and Recovery

• Article 10 — What Worked, What Didn’t, What I’d Change

Optional Extras

• → Why Passwordless Alone Is Not an Identity Strategy

• How Browser UX Shapes Security More Than Cryptography

In production, elegance collides with:

• Browser inconsistencies

• Institutional identity constraints

• Support tickets

• Device lifecycle chaos

• Monitoring blind spots

Let’s break it down honestly.

What Worked

1️⃣ WebAuthn as Primary Authentication

This worked better than expected.

Users quickly adapted to:

• Fingerprint

• Face recognition

• Device PIN

Support requests about “forgot password” dropped to zero — because passwords were gone.

The combination of:

var result = await _fido2.MakeAssertionAsync(...)

and:

HttpContext.SignInAsync("Cookies", principal);

proved stable and predictable once encoding and session handling were correct.

The strongest success signal:

No phishing-related login issues after deployment.

That is not common.

2️⃣ HTTP-only Cookie Sessions

Avoiding JWT-in-localStorage was absolutely the right call.

options.Cookie.HttpOnly = true;
options.Cookie.SecurePolicy = CookieSecurePolicy.Always;

Benefits:

• XSS impact minimized

• Simpler revocation model

• Clear session lifetime control

Operationally, this reduced attack surface significantly.

3️⃣ Clear Decision Tree

My initial flowchart saved me.

Because when things broke, I always knew which branch was responsible:

• WebAuthn failure?

• OIDC fallback?

• Session misconfiguration?

• Credential lifecycle issue?

That clarity matters more than people realize.

Trade-offs I Accepted Knowingly

1️⃣ No Attestation Verification

AttestationConveyancePreference.None

Trade-off:

• No hardware manufacturer validation

• No enforcement of hardware-backed keys

Why I accepted it:

• Lower operational complexity

• Better privacy posture

• Reduced metadata dependency

In institutional context, identity assurance was already upstream via Feide.

2️⃣ Preferred Instead of Required User Verification

UserVerificationRequirement.Preferred

Trade-off:

• Allows authenticators without biometric enforcement

• Slightly lower strictness

Why:

• Broader device compatibility

• Fewer user lockouts

• Reduced friction in older hardware environments

Security posture was balanced against accessibility.

3️⃣ No Offline Authentication

PWA expectation:
“It’s installed. It should work offline.”

Reality:
WebAuthn requires server challenge.

I chose not to simulate offline authentication using cached tokens beyond session lifetime.

Trade-off:

• Some UX friction

• Stronger trust model

Security > illusion of offline login.

What Looked Good on Paper But Failed in Reality

1️⃣ “Users Will Immediately Register Passwordless”

They didn’t.

Even after OIDC login, many skipped enabling passwordless.

The elegant flow:

if (!user.Credentials.Any())
    return Redirect("/enable-passwordless");

In reality:
Users ignored prompts.

Lesson:
Make passwordless enrollment prominent and incentivized.

2️⃣ Counter Strictness

Initially:

if (result.Counter <= storedCounter)
    throw new SecurityException("Possible cloned authenticator");

This caused false positives.

Some authenticators:

• Always returned 0

• Didn’t increment reliably

Lesson:
Spec compliance is messier than the spec implies.

Relaxed logic to handle zero counters more intelligently.

3️⃣ Browser Error Consistency

I assumed:

“All browsers implement WebAuthn uniformly.”

Reality:

• Different error messages

• Different cancellation behaviors

• Slight timing differences

VueJS error handling needed refinement:

catch (err) {
  if (err.name === "NotAllowedError") {
    showRetry();
  } else {
    showFallbackOption();
  }
}

UX required careful branching.

Operational Lessons

1️⃣ Logging Matters More Than Crypto

You need logs for:

• Challenge generation

• Assertion verification result

• Counter updates

• OIDC callback mapping

• Session creation

Example structured logging:

_logger.LogInformation("WebAuthn assertion verified for user {UserId}, counter updated to {Counter}",
    user.Id, result.Counter);

Without this, debugging failures becomes guesswork.

2️⃣ Monitoring Authentication Metrics

Track:

• WebAuthn success rate

• WebAuthn failure rate

• OIDC fallback frequency

• Credential registrations per day

• Counter mismatch events

These reveal patterns:

• Device compatibility issues

• Misconfiguration

• User confusion

Authentication is not “set and forget.”

3️⃣ Support Edge Cases

Real tickets included:

• “My fingerprint stopped working after OS update.”

• “I cleared my browser data and now can’t log in.”

• “I logged in via Feide but it says no account.”

Each required:

• Clear recovery path

• Transparent error messaging

• Internal documentation

Edge cases are not rare. They are normal.

4️⃣ Account Linking Confusion

Some users had:

• Multiple institutional identities

• Email changes

• Duplicate accounts

Relying solely on email would have been disastrous.

Using sub claim for linking was critical:

var externalUserId = claims.FindFirst("sub")?.Value;

Stable identifiers are everything.

What I Would Change

1️⃣ Stronger Enrollment Enforcement

Instead of optional passwordless enablement:

I would require it after first successful OIDC login.

Security adoption improves when it’s default, not optional.

2️⃣ Better Device Management UI

Users should see:

• List of registered devices

• Last used timestamp

• Revoke option

Backend model already supports it:

SELECT * FROM WebAuthnCredentials WHERE UserId = @UserId

But UX should surface it more clearly.

3️⃣ Structured Monitoring Dashboard

Real-time visibility into:

• Assertion failures

• Counter mismatches

• OIDC errors

Would reduce reactive debugging.

4️⃣ Automated Credential Health Checks

Periodic validation:

• Detect stale counters

• Detect inactive credentials

• Flag suspicious behavior

WebAuthn gives strong primitives. Monitoring must match.

The Big Lesson

The hardest part of passwordless authentication is not cryptography.

It is lifecycle management.

WebAuthn works.

OIDC works.

HTTP-only cookies work.

But the real challenge is designing:

• Failure handling

• Device transitions

• Recovery paths

• Operational visibility

Security architecture is not proven at deployment.

It is proven over time.

Final Reflection

If I rebuilt this system:

• I would keep passwordless-first.

• I would keep Feide federation.

• I would keep server-controlled sessions.

• I would invest earlier in monitoring and enrollment enforcement.

What surprised me most?

How much calmer authentication became once passwords were gone.

No resets.
No reuse.
No phishing alerts.

Just possession proof + federated identity continuity.

That combination feels less like a feature and more like an upgrade to the trust model of the application itself.

And that, ultimately, was the goal of the entire series. This concludes the series, but you can still check out my next optional extras articles next.

☰ Series Navigation

Core Series

• Introduction

• Article 1 — Authentication is Not Login

• Article 2 — What “Passwordless” Actually Means

• Article 3 — WebAuthn & FIDO2, Explained Without the Spec

• Article 4 — OpenID Connect as the Glue

• Article 5 — Designing a Passwordless-First PWA Architecture

• Article 6 — UX and Failure Are Part of the Security Model

• Article 7 — A Real Passwordless PWA Flow (Architecture Walkthrough)

• Article 8 — Implementing WebAuthn in Practice

• Article 9 — Integrating OIDC (Feide) as Fallback and Recovery

• → Article 10 — What Worked, What Didn’t, What I’d Change

Optional Extras

• Why Passwordless Alone Is Not an Identity Strategy

• How Browser UX Shapes Security More Than Cryptography

That’s where OIDC (Feide) enters — not as a competitor to passwordless, but as structural support.

This article walks through my real implementation:

• Frontend: VueJS PWA

• Backend: ASP.NET Core

• Database: SQL Server

• Passwordless: fido2-net-lib

• Federation: OpenID Connect (Feide)

• Session: HTTP-only cookie

And we’ll focus on four things:

1. What can Feide bring to the table

2. How OIDC fits without undermining WebAuthn

3. Security boundaries between IdP and my system

4. Account linking in practice

Disclaimer

This article describes architectural patterns and technical approaches based on a real-world implementation. All examples, code snippets, and flow descriptions have been generalized and simplified for educational purposes. No proprietary business logic, confidential configurations, credentials, or organization-specific details are disclosed. The focus is strictly on publicly documented standards (WebAuthn, OIDC) and implementation patterns within a standard VueJS + ASP.NET Core + SQL Server stack.

What can Feide bring to the table

Feide is widely used in Norwegian education and research sectors. That matters for three reasons:

1️⃣ Institutional Identity Already Exists

Users already have:

• A managed identity

• Centralized credential lifecycle

• Organizational trust

Recreating identity inside my PWA would be redundant and weaker.

2️⃣ Compliance & Governance

Institutional IdPs typically enforce:

• MFA policies

• Password strength

• Account revocation

• Auditing

By integrating Feide, my system inherits that upstream assurance without storing passwords.

3️⃣ Recovery and Bootstrap

WebAuthn is device-bound.

Feide provides:

• Cross-device identity continuity

• Secure account recovery

• Bootstrap trust for new devices

How OIDC Fits Without Undermining Passwordless

The common fear:

“If I add OIDC fallback, doesn’t that weaken passwordless?”

Only if fallback is careless.

My architecture enforces this model:

• WebAuthn = primary authentication

• Feide OIDC = bootstrap + recovery

• HTTP-only cookie = session integrity

• SQL Server = credential persistence

Feide does not authenticate users inside my system directly.

Feide asserts identity.

WebAuthn proves device possession.

Those are different trust layers.

Real OIDC Integration (ASP.NET Core)

My implemented Authorization Code flow with PKCE.

OIDC Configuration

services.AddAuthentication(options =>
{
    options.DefaultScheme = "Cookies";
    options.DefaultChallengeScheme = "oidc";
})
.AddCookie("Cookies", options =>
{
    options.Cookie.HttpOnly = true;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    options.Cookie.SameSite = SameSiteMode.Lax;
})
.AddOpenIdConnect("oidc", options =>
{
    options.Authority = "https://auth.feide.no";
    options.ClientId = Configuration["Feide:ClientId"];
    options.ClientSecret = Configuration["Feide:ClientSecret"];
    options.ResponseType = "code";
    options.SaveTokens = false;
    options.GetClaimsFromUserInfoEndpoint = true;

    options.Scope.Add("openid");
    options.Scope.Add("profile");
    options.Scope.Add("email");

    options.TokenValidationParameters.NameClaimType = "name";
});

Important detail:

options.SaveTokens = false;

You do not store IdP tokens in the browser.

You convert identity into a server-controlled session.

OIDC Callback Flow

[HttpGet("callback")]
public async Task<IActionResult> Callback()
{
    var authenticateResult = await HttpContext.AuthenticateAsync("oidc");

    if (!authenticateResult.Succeeded)
        return Unauthorized();

    var externalUserId = authenticateResult.Principal.FindFirst("sub")?.Value;

    var user = await FindOrCreateUser(externalUserId);

    SignInUser(user.Id);

    if (!user.WebAuthnCredentials.Any())
        return Redirect("/enable-passwordless");

    return Redirect("/dashboard");
}

This is critical:

• Feide proves identity.

• The system maps that identity to internal user record.

• The system issues session cookie.

The IdP does not create sessions in my system.

Security Boundaries Between OIDC and My System

Understanding boundaries prevents architectural confusion.

What OIDC Is Responsible For

• Authenticating the user upstream

• Issuing ID tokens

• Managing institutional identity lifecycle

• Enforcing upstream MFA policies

What My System Is Responsible For

• Mapping external identity (sub) to internal user

• Managing WebAuthn credentials

• Verifying FIDO2 assertions

• Issuing and invalidating session cookies

• Authorization within my application

OIDC is not trusted to:

• Authorize application actions

• Manage WebAuthn devices

• Maintain the session integrity

Trust is layered, not delegated.

Account Linking Considerations

This is where real complexity lives.

OIDC provides:

{
  "sub": "abcd1234",
  "email": "user@example.edu"
}

But what if:

• Email changes?

• User logs in with different institutional account?

• Duplicate local account exists?

You must choose a stable linking strategy.

Recommended Linking Model

Use sub as the primary external identifier.

Database model:

CREATE TABLE ExternalLogins (
    Id UNIQUEIDENTIFIER PRIMARY KEY,
    UserId UNIQUEIDENTIFIER NOT NULL,
    Provider NVARCHAR(50) NOT NULL,
    ExternalSubject NVARCHAR(255) NOT NULL
);

Mapping logic:

var externalLogin = await _db.ExternalLogins
    .FirstOrDefaultAsync(x =>
        x.Provider == "Feide" &&
        x.ExternalSubject == externalUserId);

if (externalLogin == null)
{
    // First login → create link
    var user = CreateNewUser();
    _db.ExternalLogins.Add(new ExternalLogin {
        UserId = user.Id,
        Provider = "Feide",
        ExternalSubject = externalUserId
    });
}

Never rely solely on email for linking.

Emails change. sub should not.

Recovery Flow Using Feide

Lost device scenario:

1. User clicks “Login with Feide”

2. OIDC completes

3. Identity verified

4. System invalidates old WebAuthn credentials

5. User registers new credential

Example revocation:

_db.WebAuthnCredentials.RemoveRange(user.WebAuthnCredentials);
await _db.SaveChangesAsync();

Then redirect to registration.

Recovery is structured. Not improvised.

Why This Does Not Undermine Passwordless

Weak fallback undermines security when:

• It bypasses verification

• It skips policy

• It exists only as emergency shortcut

My implementation ensures:

• OIDC must complete successfully

• Session is server-issued

• WebAuthn remains primary method

• Registration after OIDC is explicit

This maintains assurance.

VueJS PWA Integration

From frontend:

function loginWithFeide() {
  window.location.href = "/api/auth/feide-login";
}

No tokens stored client-side.
No JWT in localStorage.
No client-managed identity state.

The PWA only reacts to session cookie.

This keeps attack surface small.

What This Architecture Achieves

By combining:

• WebAuthn (device-bound proof)

• Feide OIDC (identity continuity)

• SQL Server (credential persistence)

• HTTP-only cookies (session security)

You achieve:

• Phishing resistance

• Device lifecycle resilience

• Institutional identity integration

• Controlled fallback

• Clear trust boundaries

Most importantly:

You avoid false dichotomy.

This is not:

“Passwordless vs Federation.”

It is:

“Passwordless for authentication. Federation for identity continuity.”

Final Reflection

Integrating OIDC did not weaken the system.

It completed it.

WebAuthn without federation is brittle.
Federation without WebAuthn is phishable.

Together, they form a layered trust architecture.

In the next article, we’ll examine operational lessons learned after deploying this combined system — including monitoring, auditing, and real-world behavioral patterns that only surface after production traffic begins.

Because authentication design doesn’t end at implementation.

It evolves under pressure.

☰ Series Navigation

Core Series

• Introduction

• Article 1 — Authentication is Not Login

• Article 2 — What “Passwordless” Actually Means

• Article 3 — WebAuthn & FIDO2, Explained Without the Spec

• Article 4 — OpenID Connect as the Glue

• Article 5 — Designing a Passwordless-First PWA Architecture

• Article 6 — UX and Failure Are Part of the Security Model

• Article 7 — A Real Passwordless PWA Flow (Architecture Walkthrough)

• Article 8 — Implementing WebAuthn in Practice

• → Article 9 — Integrating OIDC (Feide) as Fallback and Recovery

• Article 10 — What Worked, What Didn’t, What I’d Change

Optional Extras

• Why Passwordless Alone Is Not an Identity Strategy

• How Browser UX Shapes Security More Than Cryptography

• Generate challenge

• Call browser API

• Verify signature

• Done

In practice, it is not that simple.

WebAuthn is cryptographically elegant but operationally unforgiving.
Small mistakes create subtle security gaps or inexplicable failures.

This article walks through:

• The tooling used

• The data model design

• Real code from ASP.NET Core + VueJS

• Common pitfalls

• And what surprised me during implementation

Disclaimer

This article describes architectural patterns and technical approaches based on a real-world implementation. All examples, code snippets, and flow descriptions have been generalized and simplified for educational purposes. No proprietary business logic, confidential configurations, credentials, or organization-specific details are disclosed. The focus is strictly on publicly documented standards (WebAuthn, OIDC) and implementation patterns within a standard VueJS + ASP.NET Core + SQL Server stack.

Tooling Used

Backend: fido2-net-lib

For .NET Core, fido2-net-lib is one of the most mature and spec-compliant WebAuthn libraries available.

It handles:

• Challenge generation

• Attestation verification

• Assertion verification

• Counter validation

• Origin validation

• Credential parsing

Initialization:

var fido2 = new Fido2(new Fido2Configuration
{
    ServerDomain = "yourdomain.com",
    ServerName = "Your App",
    Origin = "https://yourdomain.com"
});

The important realization:

The library handles cryptography —
You must handle state.

Frontend: Native WebAuthn API

In VueJS, no heavy library was required.
The browser already implements WebAuthn.

Registration:

const credential = await navigator.credentials.create({
  publicKey: options
});

Authentication:

const assertion = await navigator.credentials.get({
  publicKey: options
});

However:

You must convert Base64URL fields correctly between server and client.

This is one of the first places things break.

Data Model Design (SQL Server)

This is where real decisions matter.

A WebAuthn credential is not just an ID.

Here’s the simplified SQL model:

CREATE TABLE WebAuthnCredentials (
    Id UNIQUEIDENTIFIER PRIMARY KEY,
    UserId UNIQUEIDENTIFIER NOT NULL,
    CredentialId VARBINARY(MAX) NOT NULL,
    PublicKey VARBINARY(MAX) NOT NULL,
    SignatureCounter BIGINT NOT NULL,
    CreatedAt DATETIME2 NOT NULL DEFAULT SYSUTCDATETIME()
);

Why VARBINARY?

Because:

• Credential IDs are binary.

• Public keys are binary (COSE format).

• Storing them as strings introduces encoding risk.

Why store SignatureCounter?

The counter protects against cloned authenticators.

If the new counter ≤ stored counter, something is wrong.

WebAuthn security is incomplete without counter tracking.

Registration Flow (Real Implementation)

Step 1: Generate Options

[HttpPost("register-options")]
public IActionResult RegisterOptions()
{
    var user = GetCurrentUser();

    var options = _fido2.RequestNewCredential(
        new Fido2User
        {
            Id = Encoding.UTF8.GetBytes(user.Id.ToString()),
            Name = user.Email,
            DisplayName = user.Email
        },
        new List<PublicKeyCredentialDescriptor>(),
        AuthenticatorSelection.Default,
        AttestationConveyancePreference.None
    );

    HttpContext.Session.SetString("fido2.attestationChallenge", options.Challenge);

    return Ok(options);
}

Notice:

• Challenge is stored server-side.

• Attestation preference set to None (privacy-friendly).

• No credentials excluded in this example.

Step 2: Verify Attestation

[HttpPost("verify-registration")]
public async Task<IActionResult> VerifyRegistration([FromBody] AuthenticatorAttestationRawResponse attestation)
{
    var challenge = HttpContext.Session.GetString("fido2.attestationChallenge");

    var result = await _fido2.MakeNewCredentialAsync(
        attestation,
        new List<PublicKeyCredentialDescriptor>(),
        (args) => args.Challenge == challenge
    );

    var credential = new WebAuthnCredential
    {
        UserId = GetCurrentUserId(),
        CredentialId = result.Result.CredentialId,
        PublicKey = result.Result.PublicKey,
        SignatureCounter = result.Result.Counter
    };

    _db.WebAuthnCredentials.Add(credential);
    await _db.SaveChangesAsync();

    return Ok();
}

Key insight:

The challenge validator delegate must explicitly check equality.

Do not assume the library does that for you.

Authentication Flow (Assertion)

Generate Assertion Options

var options = _fido2.GetAssertionOptions(
    storedCredentials,
    UserVerificationRequirement.Preferred
);

HttpContext.Session.SetString("fido2.challenge", options.Challenge);

Verify Assertion

var result = await _fido2.MakeAssertionAsync(
    clientResponse,
    storedCredential.PublicKey,
    storedCredential.SignatureCounter,
    args => args.Challenge == challenge
);

storedCredential.SignatureCounter = result.Counter;
await _db.SaveChangesAsync();

The counter update is not optional.

It is part of replay protection.

Common Implementation Pitfalls

1. Base64URL encoding mismatches

Browser returns ArrayBuffers.
ASP.NET expects byte arrays.

If encoding conversion is inconsistent, verification fails silently.

Solution: Use consistent Base64URL encoding utilities.

Example

const assertion = await navigator.credentials.get({ publicKey: options });

await fetch("/api/auth/verify-webauthn", {
  method: "POST",
  body: JSON.stringify(assertion)
});

Problem: assertion.rawId is an ArrayBuffer — not Base64URL.

Explicit conversion helpers:

function bufferToBase64Url(buffer) {
  return btoa(String.fromCharCode(...new Uint8Array(buffer)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

2. Forgetting challenge persistence

If the challenge:

• is not stored,

• or stored per user incorrectly,

• or overwritten in concurrent requests,

verification fails.

Challenge must be:

• short-lived,

• per session,

• non-reusable.

Example

HttpContext.Session.SetString("challenge", options.Challenge);

Then later:

var challenge = HttpContext.Session.GetString("fido2.challenge");

By using 2 different keys would introduce this bug:

Fido2VerificationException: Challenge mismatch

Or:

Fido2VerificationException: Invalid challenge.

3. Not validating origin

Origin mismatch is a common deployment issue.

If your production URL differs from development configuration, authentication breaks.

Example:

Your production:

https://app.yourdomain.com

But config says:

Origin = "https://yourdomain.com"

Subdomain mismatch would lead to this error:

Fido2VerificationException: Invalid origin

Or:

Origin https://app.yourdomain.com does not match expected https://yourdomain.com

4. Counter mishandling

Some authenticators:

• return 0 initially.

• do not increment as expected.

Your logic must handle legitimate zero counters.

Rejecting zero blindly causes user lockout.

Example

Authenticator returns:

counter = 0

Stored counter also:

0

Your logic:

if (result.Counter <= storedCounter)
{
    throw new SecurityException("Possible cloned authenticator");
}

Immediate lockout and return error:

Fido2VerificationException: Signature counter did not increase.

Or your own thrown exception:

Possible cloned authenticator detected.

Correct logic: Only enforce monotonicity when counter > 0.

5. Misunderstanding attestation

Attestation verifies device manufacturer.

Most applications do not need this.

Setting AttestationConveyancePreference.None:

• avoids privacy concerns,

• reduces complexity,

• avoids metadata verification headaches.

Example:

You enable:

AttestationConveyancePreference.Direct

Now browser returns full attestation.

But you don’t validate metadata, which would returns:

Fido2VerificationException: Attestation format not supported

Or:

Fido2VerificationException: No metadata service configured

Bonus: Browser-Side Errors

User Cancels

DOMException: The operation was aborted.

Not Allowed

DOMException: The user aborted a request.

Unsupported Platform

NotSupportedError: The operation is not supported.

These are not backend problems — but your UX must handle them gracefully.

What Surprised Me During Implementation

1. How much state management matters

The cryptography is handled by the library.

The complexity lives in:

• challenge storage,

• session lifecycle,

• device registration state,

• error branching.

WebAuthn is less about math and more about disciplined state handling.

2. Browser inconsistencies

Different browsers:

• format errors differently,

• handle cancellation differently,

• vary in UI timing.

Your retry UX must account for that.

3. The importance of fallback

The first time a device:

• failed biometric recognition,

• or returned unexpected counter values,

I realized:

Passwordless-only systems are fragile.

Fallback is not optional.

4. Offline expectations vs reality

Because this is a PWA, users assume:

“It’s installed. It should just work.”

But WebAuthn requires:

• live challenge from server,

• real-time verification.

Offline login is not true authentication.

Designing expectations around that was essential.

5. The psychological difference

Once implemented properly:

Users stopped typing passwords.

They trusted the system more.

That was not because of UI polish.

It was because:

• no secrets were transmitted,

• no reset emails were needed,

• no password rules existed.

Security felt natural.

That is rare.

Final Reflection

Implementing WebAuthn is not:

• copying code from documentation,

• adding biometric login,

• or flipping a feature flag.

It is:

• modeling credentials correctly,

• handling state carefully,

• validating challenges strictly,

• updating counters reliably,

• integrating session management securely.

It is architecture expressed through code.

In the next article, we’ll examine the integration of Feide OIDC in more depth — including account linking, token validation, and how federated identity interacts with my passwordless credential lifecycle.

Because WebAuthn proves possession.

Federation proves identity continuity.

Both are required for resilient systems.

☰ Series Navigation

Core Series

• Introduction

• Article 1 — Authentication is Not Login

• Article 2 — What “Passwordless” Actually Means

• Article 3 — WebAuthn & FIDO2, Explained Without the Spec

• Article 4 — OpenID Connect as the Glue

• Article 5 — Designing a Passwordless-First PWA Architecture

• Article 6 — UX and Failure Are Part of the Security Model

• Article 7 — A Real Passwordless PWA Flow (Architecture Walkthrough)

• → Article 8 — Implementing WebAuthn in Practice

• Article 9 — Integrating OIDC (Feide) as Fallback and Recovery

• Article 10 — What Worked, What Didn’t, What I’d Change

Optional Extras

• Why Passwordless Alone Is Not an Identity Strategy

• How Browser UX Shapes Security More Than Cryptography

Real systems are not.

My architecture intentionally combines:

• WebAuthn (FIDO2) for phishing-resistant authentication

• Feide (OIDC) for federated identity, recovery, and bootstrap

• SQL Server for credential persistence

• HTTP-only cookies for secure session handling

• VueJS PWA as the user-facing layer

At the center of the system is one key decision:

Does this user already have passwordless enabled?

Everything branches from there.

Disclaimer

This article describes architectural patterns and technical approaches based on a real-world implementation. All examples, code snippets, and flow descriptions have been generalized and simplified for educational purposes. No proprietary business logic, confidential configurations, credentials, or organization-specific details are disclosed. The focus is strictly on publicly documented standards (WebAuthn, OIDC) and implementation patterns within a standard VueJS + ASP.NET Core + SQL Server stack.

The Real Flowchart: The System as a Decision Tree

My initial flowchart expresses the core logic clearly:

1. User requests authentication.

2. System checks: Has passwordless been enabled?

3. If yes → Attempt WebAuthn authentication.

4. If no → Redirect to Feide OIDC.

5. If WebAuthn fails → Allow retry.

6. If retries exhausted → End or fallback.

7. After successful OIDC → Offer passwordless registration.

This is not UX decoration.

This is an explicit trust state machine.

Let’s walk through it step by step with real code.

Step 1 — VueJS PWA: Begin Authentication

The PWA does not guess the strategy.

It asks the backend.

// VueJS (Composition API)
async function beginLogin(email) {
  const response = await fetch("/api/auth/begin", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email })
  });

  const result = await response.json();

  if (result.strategy === "webauthn") {
    await startWebAuthn(result.options);
  } else if (result.strategy === "oidc") {
    window.location.href = result.redirectUrl;
  }
}

The browser is a mediator.
It does not decide trust.

Step 2 — ASP.NET Core: Decide the Strategy

My backend controls the trust graph.

[HttpPost("begin")]
public async Task<IActionResult> Begin([FromBody] LoginRequest request)
{
    var user = await _db.Users
        .Include(u => u.Credentials)
        .FirstOrDefaultAsync(u => u.Email == request.Email);

    if (user == null || !user.Credentials.Any())
    {
        return Ok(new {
            strategy = "oidc",
            redirectUrl = BuildFeideRedirect()
        });
    }

    var fido2 = new Fido2(new Fido2Configuration
    {
        ServerDomain = "yourdomain.com",
        ServerName = "Your App",
        Origin = "https://yourdomain.com"
    });

    var options = fido2.GetAssertionOptions(
        user.Credentials.Select(c => new PublicKeyCredentialDescriptor(c.CredentialId)).ToList(),
        UserVerificationRequirement.Preferred
    );

    HttpContext.Session.SetString("fido2.challenge", options.Challenge);

    return Ok(new {
        strategy = "webauthn",
        options
    });
}

Why this branch exists:

• WebAuthn only works if credentials exist.

• Backend must know account state.

• Trust decisions cannot be client-side.

Step 3 — WebAuthn Authentication (VueJS + Browser API)

async function startWebAuthn(options) {
  try {
    const assertion = await navigator.credentials.get({
      publicKey: options
    });

    const res = await fetch("/api/auth/verify-webauthn", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(assertion)
    });

    if (res.ok) {
      window.location.href = "/dashboard";
    } else {
      showRetryOption();
    }
  } catch (err) {
    showRetryOption();
  }
}

The browser enforces:

• Origin binding

• Authenticator interaction

• User presence / verification

It does not verify the signature.

That’s backend responsibility.

Step 4 — Backend Verification with fido2-net-lib

[HttpPost("verify-webauthn")]
public async Task<IActionResult> Verify([FromBody] AuthenticatorAssertionRawResponse clientResponse)
{
    var challenge = HttpContext.Session.GetString("fido2.challenge");

    var storedCredential = await _db.Credentials
        .FirstOrDefaultAsync(c => c.CredentialId == clientResponse.Id);

    if (storedCredential == null)
        return Unauthorized();

    var fido2 = new Fido2(_config);

    var result = await fido2.MakeAssertionAsync(
        clientResponse,
        storedCredential.PublicKey,
        storedCredential.SignatureCounter,
        args => args.Challenge == challenge
    );

    storedCredential.SignatureCounter = result.Counter;
    await _db.SaveChangesAsync();

    SignInUser(storedCredential.UserId);

    return Ok();
}

This branch exists because:

• Only the server verifies cryptographic proof.

• Counters detect cloned authenticators.

• Session issuance must be server-controlled.

Session Handling — HTTP-Only Cookie

private void SignInUser(Guid userId)
{
    var claims = new List<Claim>
    {
        new Claim(ClaimTypes.NameIdentifier, userId.ToString())
    };

    var identity = new ClaimsIdentity(claims, "Cookies");
    var principal = new ClaimsPrincipal(identity);

    HttpContext.SignInAsync("Cookies", principal, new AuthenticationProperties
    {
        IsPersistent = true,
        ExpiresUtc = DateTime.UtcNow.AddHours(8)
    });
}

Configured in Startup.cs:

services.AddAuthentication("Cookies")
    .AddCookie("Cookies", options =>
    {
        options.Cookie.HttpOnly = true;
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        options.Cookie.SameSite = SameSiteMode.Lax;
    });

Why HTTP-only cookie?

• Protects against XSS token theft.

• Avoids storing JWT in localStorage.

• Keeps session server-controlled.

OIDC Fallback — Feide Integration

If passwordless is not enabled, redirect to Feide.

private string BuildFeideRedirect()
{
    return $"{_config["Feide:Authority"]}/authorize" +
           $"?response_type=code" +
           $"&client_id={_config["Feide:ClientId"]}" +
           $"&redirect_uri={_config["Feide:RedirectUri"]}" +
           $"&scope=openid profile email" +
           $"&code_challenge={GeneratePKCEChallenge()}" +
           $"&code_challenge_method=S256";
}

Callback endpoint:

[HttpGet("callback")]
public async Task<IActionResult> Callback(string code)
{
    var token = await ExchangeCodeForToken(code);

    var idToken = ValidateIdToken(token.IdToken);

    var user = await FindOrCreateUser(idToken.Sub);

    SignInUser(user.Id);

    if (!user.Credentials.Any())
        return Redirect("/enable-passwordless");

    return Redirect("/dashboard");
}

This branch exists because:

• Devices are lost.

• Users switch devices.

• Federation provides lifecycle continuity.

• OIDC provides bootstrap trust.

WebAuthn Registration After OIDC

When enabling passwordless:

[HttpPost("register-options")]
public IActionResult RegisterOptions()
{
    var user = GetCurrentUser();

    var options = _fido2.RequestNewCredential(
        new Fido2User
        {
            DisplayName = user.Email,
            Id = Encoding.UTF8.GetBytes(user.Id.ToString()),
            Name = user.Email
        },
        new List<PublicKeyCredentialDescriptor>(),
        AuthenticatorSelection.Default,
        AttestationConveyancePreference.None
    );

    HttpContext.Session.SetString("fido2.attestationChallenge", options.Challenge);

    return Ok(options);
}

Client registers via navigator.credentials.create.

Server verifies and stores:

_db.Credentials.Add(new Credential {
    UserId = user.Id,
    CredentialId = result.Result.CredentialId,
    PublicKey = result.Result.PublicKey,
    SignatureCounter = result.Result.Counter
});

Why this branch exists:

• Passwordless-first upgrades users.

• Registration is explicit.

• Device lifecycle is managed.

Role Breakdown

Browser (VueJS PWA)

• Initiates flows

• Calls WebAuthn API

• Handles redirects

• Does not store session tokens

Authenticator

• Stores private key

• Verifies biometric locally

• Signs challenges

• Never exposes key

Backend (.NET Core)

• Controls strategy

• Generates challenges

• Verifies assertions

• Tracks counters

• Integrates OIDC

• Issues session cookie

• Persists credentials in SQL Server

Trust is centralized.
Proof is decentralized.

Why Each Branch Exists

None of these branches are decorative.

Each corresponds to a failure mode in reality.

Final Architectural Insight

This system is not:

“Biometric login.”

It is:

• Identity bootstrap via federation.

• Device-bound authentication via FIDO2.

• Session integrity via secure cookies.

• Lifecycle management via SQL persistence.

• Explicit failure handling.

• Clear decision tree.

Passwordless-first is not about removing complexity.

It is about relocating trust:

• Away from shared secrets.

• Toward cryptographic proof.

• While preserving federated continuity.

And when drawn as a flowchart, the system looks clean.

When implemented in VueJS + ASP.NET Core + SQL Server + Feide + fido2-net-lib, it becomes real.

And real systems are where architecture proves itself.

Next article, we’ll explore what broke, what surprised us, and what we learned when this passwordless-first architecture moved from diagram to production.

☰ Series Navigation

Core Series

• Introduction

• Article 1 — Authentication is Not Login

• Article 2 — What “Passwordless” Actually Means

• Article 3 — WebAuthn & FIDO2, Explained Without the Spec

• Article 4 — OpenID Connect as the Glue

• Article 5 — Designing a Passwordless-First PWA Architecture

• Article 6 — UX and Failure Are Part of the Security Model

• → Article 7 — A Real Passwordless PWA Flow (Architecture Walkthrough)

• Article 8 — Implementing WebAuthn in Practice

• Article 9 — Integrating OIDC (Feide) as Fallback and Recovery

• Article 10 — What Worked, What Didn’t, What I’d Change

Optional Extras

• Why Passwordless Alone Is Not an Identity Strategy

• How Browser UX Shapes Security More Than Cryptography

Humans are not.

The strongest authentication protocol in the world can be undone by:

• a confusing error message,

• an unclear retry flow,

• a missing recovery path,

• or a user who simply wants to get their work done.

If your authentication design does not account for failure as a first-class scenario, it is not secure — it is brittle.

Passwordless systems amplify this truth.

When WebAuthn works, it feels effortless.
When it fails, it reveals whether your architecture was designed for real life or for a demo.

UX is not decoration layered on top of security.
UX is how security expresses itself.

Retry flows are part of the threat model

Consider a simple scenario:

A user attempts WebAuthn authentication.
They cancel the prompt.

What does that mean?

• They changed their mind?

• The biometric failed?

• The authenticator was unavailable?

• A malicious script attempted background authentication?

• They clicked too quickly?

Your system must interpret failure deliberately.

Immediate retry?

Too many automatic retries can:

• confuse users,

• create loops,

• mask real issues.

Manual retry?

Clear, explicit retry buttons give users control — and reduce panic.

Escalation to fallback?

At what point does the system say:
“Let’s use your identity provider instead”?

Retry logic is not UX polish.
It is part of the attack surface.

An attacker probing authentication flows will:

• trigger errors,

• observe timing differences,

• test fallback conditions.

Your retry model must:

• avoid leaking information,

• avoid enabling brute force,

• avoid trapping legitimate users.

Lockouts: protection or punishment?

Lockouts are traditionally used to prevent brute-force attacks.

But in passwordless systems:

• there is no password to brute force,

• biometric verification happens locally,

• challenge–response is resistant to replay.

So what are we locking out?

If:

• a signature counter mismatch occurs,

• an authenticator appears cloned,

• repeated failures happen,

a lockout might be justified.

But lockouts must be:

• transparent,

• recoverable,

• tied to real risk signals.

Otherwise, they punish legitimate users for:

• device glitches,

• browser inconsistencies,

• OS updates,

• or simply aging hardware.

A mature system distinguishes between:

• suspicious activity,

• normal friction.

Graceful degradation is more secure than aggressive rejection.

Multi-device reality

Real users do not live on a single device.

They:

• switch between phone and laptop,

• replace hardware every few years,

• clear browsers,

• use shared or managed devices.

A passwordless-first system must assume:

• multiple credentials per account,

• multiple authenticators per user,

• credentials that appear and disappear over time.

This changes UX expectations.

When a user logs in from a new device, the system should:

• not imply something is wrong,

• guide them through identity verification,

• allow secure credential registration.

Multi-device support is not optional.
It is the default human condition.

Lost device scenarios are inevitable

The most dangerous authentication system is one that assumes users will never lose access to their authenticators.

Phones are lost.
Laptops are stolen.
Security keys are misplaced.

If your system has no structured recovery path, users will demand one — and you will implement it under pressure.

Good recovery design includes:

1. A trusted bootstrap identity method (e.g., OIDC).

2. Clear verification steps.

3. Revocation of lost credentials.

4. Controlled registration of new credentials.

5. Audit visibility for the user.

Recovery must be:

• secure,

• observable,

• friction-aware.

Security questions are not recovery.
Email-only resets are not recovery.
Administrative override is not recovery.

Federated identity exists partly to solve this lifecycle problem.

Why fallback is not a weakness

There is a persistent misconception:

“If the system falls back to another method, it weakens security.”

This is only true if fallback is poorly designed.

Fallback becomes dangerous when it:

• bypasses primary controls,

• uses weaker authentication without policy,

• exists only as an emergency hack.

Fallback becomes strong when it:

• is part of the architecture,

• requires equivalent assurance,

• is auditable,

• is rate-limited,

• and does not undermine the trust model.

In passwordless-first systems:

WebAuthn provides:

• phishing-resistant, device-bound authentication.

OIDC provides:

• identity portability,

• lifecycle continuity,

• bootstrap trust.

They are not substitutes.
They are complementary trust anchors.

The presence of fallback does not weaken security.
Unplanned fallback does.

Graceful degradation is a security feature

Graceful degradation means:

If the optimal path fails,
the system degrades to a slightly less optimal but still secure path —
without chaos.

For example:

• WebAuthn unavailable → redirect to OIDC.

• OIDC temporarily down → delay login with clear messaging.

• Authenticator counter mismatch → require identity re-verification.

The goal is not uninterrupted access at any cost.
The goal is continuity of trust.

Users interpret friction differently depending on clarity.

An unexplained failure feels insecure.
A clearly communicated alternative feels safe.

UX decisions shape security outcomes

A confusing biometric prompt can cause:

• users to disable security features,

• users to choose weaker alternatives,

• users to distrust the system.

An unclear fallback path can cause:

• support overload,

• ad hoc account resets,

• insecure manual overrides.

Every prompt, error message, and redirect is part of the security boundary.

When designing authentication UX, ask:

• Does this flow reduce ambiguity?

• Does this error explain next steps?

• Does this retry loop prevent confusion?

• Does this fallback preserve assurance?

Security is not just cryptographic strength.
It is user confidence combined with protocol integrity.

Designing for failure makes systems stronger

Authentication is not about proving success.
It is about handling failure safely.

Passwordless-first systems that ignore failure scenarios:

• look elegant in diagrams,

• collapse under edge cases,

• generate emergency workarounds.

Passwordless-first systems that embrace failure:

• define fallback clearly,

• support multi-device reality,

• structure recovery intentionally,

• treat UX as part of the threat model.

That is the difference between a feature and an architecture.

In the next phase of this series, we move from theory to a real implementation — walking through a complete PWA authentication flow that combines WebAuthn and OpenID Connect in production.

Because architecture only proves itself when it survives the unpredictable behavior of actual users.

☰ Series Navigation

Core Series

• Introduction

• Article 1 — Authentication is Not Login

• Article 2 — What “Passwordless” Actually Means

• Article 3 — WebAuthn & FIDO2, Explained Without the Spec

• Article 4 — OpenID Connect as the Glue

• Article 5 — Designing a Passwordless-First PWA Architecture

• → Article 6 — UX and Failure Are Part of the Security Model

• Article 7 — A Real Passwordless PWA Flow (Architecture Walkthrough)

• Article 8 — Implementing WebAuthn in Practice

• Article 9 — Integrating OIDC (Feide) as Fallback and Recovery

• Article 10 — What Worked, What Didn’t, What I’d Change

Optional Extras

• Why Passwordless Alone Is Not an Identity Strategy

• How Browser UX Shapes Security More Than Cryptography