jsConnectAspNetCoreMvc 7.0.0

Vanilla Forums jsConnect for ASP.NET Core

Vanilla Forums' jsConnect v3 for ASP.NET Core. Implements the modern JWT-based SSO flow that works under third-party cookie blocking.

What's in the package

The single NuGet jsConnectAspNetCoreMvc ships three assemblies:

Quick start

1. Install the package:

dotnet add package jsConnectAspNetCoreMvc

2. Register and map the endpoint:

using jsConnect.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddJsConnect(opts =>
{
    opts.ClientId = builder.Configuration["Vanilla:ClientId"]!;
    opts.Secret   = builder.Configuration["Vanilla:Secret"]!;
});

// Or bind from configuration directly:
// builder.Services.AddJsConnect(builder.Configuration.GetSection("Vanilla"));

var app = builder.Build();

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

app.MapJsConnect("/jsconnect");  // pick any route you like

app.Run();

3. Configure your secret (≥ 32 bytes for HS256 — the default):

{
  "Vanilla": {
    "ClientId": "your-client-id",
    "Secret":   "your-shared-secret-32-bytes-or-more",
    "Algorithm": "HS256",
    "ResponseLifetime": "00:10:00"
  }
}

4. Make sure HttpContext.User carries the claims the default resolver expects:

5. In Vanilla's dashboard, set the Authentication URL to https://yourapp/jsconnect.

Customizing user resolution

If your user info doesn't live in claims, implement IJsConnectUserResolver:

public class MyUserResolver : IJsConnectUserResolver
{
    public Task<JsConnectUser?> ResolveAsync(HttpContext context, CancellationToken ct)
    {
        return Task.FromResult<JsConnectUser?>(new JsConnectUser
        {
            UniqueId = "...",
            Name     = "...",
            Email    = "...",
            PhotoUrl = "...",
            Roles    = new[] { "admin" },
            CustomFields = new Dictionary<string, object?> { ["department"] = "eng" },
        });
    }
}

builder.Services.AddSingleton<IJsConnectUserResolver, MyUserResolver>();

Return null to emit a guest response.

Adjusting the default claims mapping

builder.Services.Configure<ClaimsJsConnectUserResolverOptions>(opts =>
{
    opts.UniqueIdClaimType = "sub";
    opts.NameClaimType     = "preferred_username";
    opts.PhotoUrlClaimType = "picture";
});

Using the protocol primitives directly

JsConnectV3 is framework-agnostic. Use it from a controller, a worker, or anywhere else:

var jsc = new JsConnectV3(new JsConnectOptions
{
    ClientId = "...",
    Secret   = "...",
});

string redirectUrl = await jsc.GenerateResponseLocationAsync(requestJwt, user);

Opt-in: Vanilla REST API client

The jsConnect.Vanilla namespace provides a small client for the legacy /api/v1/users endpoint, plus UsernameSanitizer for stripping whitespace and accents. These are not part of the jsConnect protocol — Vanilla v3 reconciles users via the id field — but you may want them if you're populating new usernames yourself.

builder.Services.AddHttpClient<VanillaApiClient>(c =>
    c.BaseAddress = new Uri("https://forums.example.com/"));

// ...
var unique = await client.GetUniqueUsernameAsync(
    UsernameSanitizer.Sanitize("Petr Švihlík"));  // -> "PetrSvihlik" or "PetrSvihlik1"

Migrating from 1.x (v2 protocol)

This is a major release. The v2 JSONP+SHA flow has been removed entirely:

In Vanilla's dashboard you must also re-issue your jsConnect client as v3 and update the endpoint URL.

Target framework

.NET 10 (LTS).