This release is a major change from the previous release. The biggest improvement here is multi-frontend support.

The extensibility approach has been drastically changed. To reduce the public API surface, and improve our ability to evolve the library, we no longer make every class in the system public with virtual methods. Implementation logic now is internal.

Changes and improvements

• Support for login prompts, such as prompt = create => #1701
• Deprecated silent login endpoint in favor of prompt=none
• Allow anti forgery check to be disabled via a delegate => #1932
• Multi-frontend support => #2032
• Duende.AccessTokenManagement V4 => #2032
• Open Telemetry support => #1945

Changes since preview 2:

• BffBuilder type (returned from services.AddBff()) is now an interface called IBffServicesBuilder. This is used as the basis for extension methods.

• IBffServicesBuilder.WithDefaultCookieOptions is now called IBffServicesBuilder.ConfigureCookies()

• IBffServicesBuilder.WithDefaultOpenIdConnectOptions is now called IBffServicesBuilder.ConfigureOpenIdConnect()

• To support split host login scenarios', you can use a referer header in the Silent Login, coupled with BffOptions.AllowedSilentLoginReferers to create a list of allowed referers.

• IFrontendCollection no longer exposes a GetAll method, but now implements IEnumerable.

• ReturnUrlValidator.IsValidAsync now only accepts a uri

• User sessions are now partitioned per frontend. IUserSessionStore has been updated to reflect this change. Note, you will have to run a migration to rename the column "ApplicationName" to "PartitionKey", including corresponding interfaces. Note, the migrations project has been updated to reflect this change.

• When you add EntityFramework based sessions to your system, it no longer automatically enables session cleanup. The property BffOptions.EnableSessionCleanup is removed. You now have to call AddSessionCleanupBackgroundProcess() to enable session migration.

Changes since preview 1:

• Removed custom signin url => #2056
• Fixed server side sessions & sliding cookie configuration => #2041
• Fixed logout => #2060

Upgrade guide

This release introduces many breaking changes. Some small, some large. We'll do our best to document how to upgrade here. Should you run into an upgrade issue that's not documented, please reach out to our discussion forum and we'll do our best to help.

Remote APIs

The syntax for configuring remote APIs has changed slightly:

// Use a client credentials token
app.MapRemoteBffApiEndpoint("/api/client-token", "https://localhost:5010")
-    .RequireAccessToken(TokenType.Client);
+    .WithAccessToken(RequiredTokenType.Client);      

// Use the client token only if the user is logged in
app.MapRemoteBffApiEndpoint("/api/optional-user-token", "https://localhost:5010")
-    .WithOptionalUserAccessToken();
+    .WithAccessToken(RequiredTokenType.UserOrNone);            

• The enum TokenType has been renamed to RequiredTokenType.
• The method to require the token type is renamed to WithAccessToken()
• Requesting an optional access token should not be done with the method WithOptionalUserAccessToken() but with RequiredTokenType.UserOrNone

Configuring Token Types In YARP

The required token type configuration in yarp has also changed slightly. It uses the enum values from RequiredTokenType.

Extending The BFF

Simplified Wireup Without Explicit Authentication Setup

The V3 style of wireup still works, but BFF V4 comes with a newer style of wireup:

services.AddBff()
    .WithDefaultOpenIdConnectOptions(options =>
    {
        options.Authority = "your authority";
        options.ClientId = "your client id";
        options.ClientSecret = "secret";
        // ... other OpenID Connect options. 
    }
    .WithDefaultCookieOptions(options => {
        // The cookie options are automatically configured with recommended practices.
        // However, you can change the config here. 
    };

Adding this will automatically configure a Cookie and OpenID Connect flow.

Adding Multiple Frontends

You can statically add a list of frontends by calling the AddFrontends method.

.AddFrontends(
    new BffFrontend(BffFrontendName.Parse("default-frontend"))
        .WithIndexHtmlUrl(new Uri("https://localhost:5005/static/index.html")),

    new BffFrontend(BffFrontendName.Parse("with-path"))
        .WithOpenIdConnectOptions(opt =>
        {
            opt.ClientId = "bff.multi-frontend.with-path";
            opt.ClientSecret = "secret";
        })
        .WithIndexHtmlUrl(new Uri("https://localhost:5005/static/index.html"))
        .MappedToPath(LocalPath.Parse("/with-path")),

    new BffFrontend(BffFrontendName.Parse("with-domain"))
        .WithOpenIdConnectOptions(opt =>
        {
            opt.ClientId = "bff.multi-frontend.with-domain";
            opt.ClientSecret = "secret";
        })
        .WithIndexHtmlUrl(new Uri("https://localhost:5005/static/index.html"))
        .MappedToOrigin(Origin.Parse("https://app1.localhost:5005"))
        .WithRemoteApis(
            new RemoteApi(LocalPath.Parse("/api/user-token"), new Uri("https://localhost:5010")),
            new RemoteApi(LocalPath.Parse("/api/client-token"), new Uri("https://localhost:5010"))
)

Loading Configuration From IConfiguration

Loading configuration, including openid connect configuration from an IConfiguration is now supported:

services.AddBff().LoadConfiguration(bffConfig);

Using this, you can configure your openid connect options, including secrets and configure the list of frontends. This also adds a file watcher, to automatically add / remove frontends from the config file.

See the type BffConfiguration to see what settings can be configured.

Index HTML Retrieval

It's fairly common to deploy your application in such a way to have the BFF be the first entrypoint for your application. It should serve an index.html that will bootstrap your frontend. However, your static content should be loaded from a CDN.

If you publish your frontend code to a cdn with absolute paths (for example by specifying a base path in your vite config), then all static content is loaded directly from the CDN.

You can configure the location of your Index HTML by specifying:

.WithIndexHtmlUrl(new Uri("https://localhost:5005/static/index.html"))

Running migrations to usersession db.

A partition key has been added to the usersession db, to support the multi-frontend feature. If you're using the entity framework UserSessionDb provider, you'll need to run the migrations.

cd .\bff\migrations\UserSessionDb
dotnet tool install --global dotnet-ef
dotnet ef database update

Alternatively, here's the script to update the migrations for SqlLocalDB. It may have to be slightly adjusted to match your database of choice.

BEGIN TRANSACTION;

ALTER TABLE "UserSessions" RENAME COLUMN "ApplicationName" TO "PartitionKey";

DROP INDEX "IX_UserSessions_ApplicationName_SubjectId_SessionId";

CREATE UNIQUE INDEX "IX_UserSessions_PartitionKey_SubjectId_SessionId" ON "UserSessions" ("PartitionKey", "SubjectId", "SessionId");

DROP INDEX "IX_UserSessions_ApplicationName_SessionId";

CREATE UNIQUE INDEX "IX_UserSessions_PartitionKey_SessionId" ON "UserSessions" ("PartitionKey", "SessionId");

DROP INDEX "IX_UserSessions_ApplicationName_Key";

CREATE UNIQUE INDEX "IX_UserSessions_PartitionKey_Key" ON "UserSessions" ("PartitionKey", "Key");

INSERT INTO "__EFMigrationsHistory" ("MigrationId", "ProductVersion")
VALUES ('20250701130814_PartitionKey', '8.0.11');

COMMIT;