Forem: Albert Starreveld

Custom Sign-In Redirects in BFF Architectures: A Guide Using OidcProxy.Net

Albert Starreveld — Wed, 24 Jan 2024 15:17:08 +0000

Implementing authentication in ASP.NET Core is usually straightforward in most cases. Installing a couple of NuGet packages and configuring them typically does the trick, unless there are complex requirements. In such cases, implementing authentication can be quite daunting.

Consider the following scenario: it isn't uncommon for web applications to have an admin console. Both administrators and end-users use the same login page to authenticate. However, after signing in, the admin sees the admin page, while the end-user does not.

Assume the following requirements:

Admins see the /admin.aspx page after signing in.
Users see the /welcome.aspx page after signing in.
Users see the /birthday.aspx page after signing in on their birthday.

This article covers:

How to bootstrap an Angular Spa + BFF project
How to implement custom sign-in requirements using OidcProxy.Net
Security considerations when implementing custom-redirection

Context

The Backend For Frontend architectural pattern has been widely adopted. However, it is advisable to move the authentication process out of Single-Page applications that run in the browser, to the server-side.

In a .NET 8 ecosystem, this is easily accomplished by installing a package called OidcProxy.Net. By installing this package in a solution, the web application becomes an Identity-Aware proxy. It is meant to receive requests from a front-end and forward it to downstream services. This is illustrated in the following context diagram:

Creating the Single-Page Application and the BFF.

Adhering to the latest best-practices in web-authentication, token-exchange takes place at the server side. This requires hosing the Single-Page Application and the BFF on the same domain.

Implementing that requires runtime on the server-side and wwwroot to serve the dist folder of the Single-Page Application. To implement that, scaffold an Angular App + BFF using the OidcProxy.Net Template-Pack:

# Download and install the template pack first
dotnet new install OidcProxy.Net.Templates

# Scaffold the proxy
dotnet new OidcProxy.Net.Angular --backend "https://backend-1.myapp.com"
    --idp "https://idp.myapp.com"
    --clientId xyz
    --clientSecret abc

# Run it
dotnet run

This will generate the following project:

Sidenote: This boilerplate project is only compatible with OpenID Connect implementations that are fully compliant such as IdentityServer or KeyCloak, for example. For products that deviate from the OpenID Connect specification, like Auth0, install the OidcProxy.Net.Auth0 package. For Microsoft Entra Id, install the OidcProxy.Net.EntraId package.

Run the project by typing dotnet run or by clicking the play button in Visual Studio. This action will launch the website, which features a sign-in button in the upper left corner. You can use this button to test the sign-in functionality. When clicked, it will navigate the user to the /.auth/login endpoint. Subsequently, it will redirect the user to the identity provider for signing in, and eventually bring them back to the website.

Configuring the default landing-page

The scaffolded project contains an appsettings.json file, which includes a section named OidcProxy. In this section, the configuration for the identity provider's address (idp), client_id, and client_secret is specified.

Configuring the destination after a user signs in is also a matter of configuration, with a setting called OidcProxy__Landingpage:

{
   # ...
   "OidcProxy": {
      # Your other settings..
      #...
      "LandingPage": "/welcome.aspx"
      # ...
   }
}

Configuring this would be sufficient for most cases. However, in light of the requirements outlined in the first part of the article, this doesn't address the need for the administrator to land on the /admin endpoint, and users aren't redirected to the birthday.aspx page on their birthday.

Specifying a landing-page on the fly

Most websites have fewer admins than customers who sign in. And usually, websites have a special link for admins to sign in.

With OidcProxy.Net it is possible to specify the landingpage an end-user should be redirected to after signing in. Assume administrators need to be redirect to /admin.aspxafter signing in, use the following link: /.auth/login?landingpage=/admin.aspx

For security reasons, this link will not work out of the box. You need to whitelist the landing pages that may be specified in the ?landingpage= query string parameter in the config. To enable this functionality, add the following configuration:

{
   ...
   "LandingPage": "/welcome.aspx",    
   "AllowedLandingPages": [
      "/admin.aspx"
    ],
   ...
}

Implementing complex business-rules to determine the landing-page

Then there's still the issue of the birthday celebrants. They need to be redirected to /birthday.aspx on their birthday. To tackle complex scenario's you'll need to write some custom middleware.

The OidcProxy.Net processes every sign-in using a class called DefaultAuthenticationCallbackHandler. This class is extendable, which allows implementing the following code:

public class BirthdayAuthenticationCallbackHandler : DefaultAuthenticationCallbackHandler
{
    public BirthdayAuthenticationCallbackHandler(ILogger<DefaultAuthenticationCallbackHandler> logger) : base(logger)
    {
    }

    public override Task<IResult> OnAuthenticated(HttpContext context, 
        JwtPayload? payload,
        string defaultLandingPage, 
        string? userPreferredLandingPage)
    {
        var birthday = payload
            .Where(claim => claim.Key == "birthday")
            .Select(value =>
            {
                DateTime.TryParse(value.ToString(), out var birthday);
                return birthday;
            })
            .FirstOrDefault();

        IResult landingPage;
        if (birthday.Day == DateTime.Now.Day && birthday.Month == DateTime.Now.Month)
        {
            landingPage = Results.Redirect("birthday.aspx");
        }
        else
        {
            landingPage = Results.Redirect("welcome.aspx");
        }

        return Task.FromResult(landingPage);
    }
}

The BirthdayAuthenticationCallbackHandler can be configured by adding the following code program.cs:

builder.Services.AddOidcProxy(config, o =>
{
     o.AddAuthenticationCallbackHandler<BirthdayAuthenticationCallbackHandler>();
});

Implementing all of the above fulfills the requirements mentioned earlier in the article.

Why landing-page != redirect_uri

OidcProxy.Net makes a distinct difference between the concept redirect_url and their landingpage-concept. That's because they serve a different purpose.

The landingpage is used to redirect a user to a page after signing in successfully.
The redirect_url is used for token exchange and is an explicit part of the OAuth2 protocol.

OidcProxy.Net uses a special endpoint, the /.auth/login/callback endpoint to receive information from the Identity Provider. This endpoint needs to be whitelisted on the Identity Provider.

Landingpages should not be whitelisted on the Identity Provider.

Summary

Adhering to the latest OAuth-best-practices means token-exchange should take place on the server-side. However, this poses challenges in case of complex post-authentication logic.
These challenges can be overcome by utilising a NuGet package called OidcProxy.Net in your ASP.NET Core webapp. It has three main features which make complex redirection possible:

The landingpage setting inappsettings.json
Specifying the landingpage when invoking the login endpoint (/.auth/login?landingpage=/admin.aspx)
Configuring a custom implementation of the DefaultAuthenticationCallbackHandler class.

A guide to building a simple ASP.NET Core BFF with a React APP

Albert Starreveld — Wed, 21 Jun 2023 13:09:34 +0000

Implementing authentication in a BFF with a React app is deemed to be complicated. Especially because proper documentation or examples are hard to find.

Implementing authentication a BFF with a react app is actually pretty straight forward. Read this article and learn how to build a BFF that hosts a React APP with ASP.NET Core.

Understanding the BFF Pattern

The purpose of the BFF (Backend for Frontend) pattern is to minimize the number of HTTP calls made by the front-end to the underlying microservices. Because, as the term "micro" suggests, there might be quite a few.

The BFF runs on the server-side, and the front-end interacts with it through its API. The BFF invokes multiple downstream APIs, it consolidates the responses from these APIs into a single response, allowing the front-end to retrieve all the required data in a single request.

From an infrastructure perspective, this is a representation of the BFF pattern:

If authentication is necessary, this pattern presents certain difficulties. Recently, the development community discourages using tokens in the front-end because that is not deemed safe enough anymore.

Instead, tokens are to be used server-side only. This means anything with tokens should move to the BFF. This means:

The site and the BFF must be on the same domain
The BFF must manage the users' session

The following steps describe how to implement this:

Implementing the BFF Security Pattern

As I stated earlier, fortunately, implementing the BFF pattern with ASP.NET Core isn't hard. A lot of boilerplate projects are available out of the box. To set up an ASP.NET Core project that hosts a React app, just type the following command in your CMD or Terminal:

dotnet new react

This will scaffold an ASP.NET Core App with a react app:

The pre-built application includes an API that generates weather forecasts. However, when it comes to a BFF implementation, the server-side should refrain from performing any calculations and instead focus on forwarding all requests to downstream services. So, the first thing to do is to remove the controllers in the projects.

Implementing the Authentication Gateway

Implementing an authentication gateway is as easy as creating an ASP.NET Core app that hosts a React App.

Just add the following package to connect to any OpenId Connect compliant Identity Provider:

dotnet add package GoCloudNative.Bff.Authentication.OpenIdConnect

using GoCloudNative.Bff.Authentication.ModuleInitializers;
using GoCloudNative.Bff.Authentication.OpenIdConnect;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

// !! Register the authentication gateway here
builder.Services.AddSecurityBff(o =>
{
    o.ConfigureOpenIdConnect(builder.Configuration.GetSection("OIDC"));
    o.LoadYarpFromConfig(builder.Configuration.GetSection("ReverseProxy"));
});
// !!

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

// !! Register the authentication gateway here too
app.UseSecurityBff();

// And remove this
// app.MapControllerRoute(
//     name: "default",
//     pattern: "{controller}/{action=Index}/{id?}");

app.MapFallbackToFile("index.html");

app.Run();

And, assuming you are using two microservices (as illustrated in the diagram in the beginning of the article), use the following appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Oidc": {
    "ClientId": "{yourClientId}",
    "ClientSecret": "{yourClientSecret}",
    "Authority": "https://{yourAuthority}",
    "Scopes": [
      "openid", "profile", "offline_access"
    ]
  },
  "AllowedHosts": "*",
  "ReverseProxy": {
    "Routes": {
      "api1": {
        "ClusterId": "api1",
        "Match": {
          "Path": "/api/{*any}"
        }
      },
      "api2": {
        "ClusterId": "api2",
        "Match": {
          "Path": "/api/bar/{*any}"
        }
      }
    },
    "Clusters": {
      "api1": {
        "Destinations": {
          "api1": {
            "Address": "http://localhost:8081/"
          }
        }
      },
      "api2": {
        "Destinations": {
          "api2": {
            "Address": "http://localhost:8082/"
          }
        }
      }
    }
  }
}

This code modifies the default ASP.NET Core React project:

By adding the SecurityBff and configuring OpenId Connect, users can now authenticate.
By loading the reverse-proxy config, all requests to endpoints that start with /api are forwarded to downstream services. The forwarded requests are enriched with the bearer token that was issued by the Identity Provider when the user has logged in.

Nontheless, by default, all requests are handled by the React app. To get the BFF to work, all requests to "/api" and to "/account" need to be handled by the ASP.NET Core app. Therefor, we need to modify the setupProxy.js file that is located in ClientApp/src. Register the api- and the account endpoints there:

const { createProxyMiddleware } = require('http-proxy-middleware');
const { env } = require('process');

const target = env.ASPNETCORE_HTTPS_PORT ? `https://localhost:${env.ASPNETCORE_HTTPS_PORT}` :
  env.ASPNETCORE_URLS ? env.ASPNETCORE_URLS.split(';')[0] : 'http://localhost:51710';

const context = [
      "/api",
      "/account"
];

const onError = (err, req, resp, target) => {
    console.error(`${err.message}`);
}

module.exports = function (app) {
  const appProxy = createProxyMiddleware(context, {
    target: target,
    onError: onError,
    secure: false,
    headers: {
      Connection: 'Keep-Alive'
    }
  });

  app.use(appProxy);
};

And that's it. Check out the code here: https://github.com/appie2go/dotnet-spa-and-bff-react

Logging in

Those are all the steps you need to do to create a BFF that hosts a React App. When you start the app, by default, users are not authenticated. To authenticate, navigate the user to /account/login. To see who's logged in, execute a GET request to the /account/me endpoint. To sign-out, navigate the user to /account/end-session.

Sources

https://bff.gocloudnative.org/integration-manuals/quickstarts/identityserver4/quickstart/