Extrode.NativeWeb.SignIn 0.1.1

dotnet add package Extrode.NativeWeb.SignIn --version 0.1.1
                    
NuGet\Install-Package Extrode.NativeWeb.SignIn -Version 0.1.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Extrode.NativeWeb.SignIn" Version="0.1.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Extrode.NativeWeb.SignIn" Version="0.1.1" />
                    
Directory.Packages.props
<PackageReference Include="Extrode.NativeWeb.SignIn" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Extrode.NativeWeb.SignIn --version 0.1.1
                    
#r "nuget: Extrode.NativeWeb.SignIn, 0.1.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Extrode.NativeWeb.SignIn@0.1.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Extrode.NativeWeb.SignIn&version=0.1.1
                    
Install as a Cake Addin
#tool nuget:?package=Extrode.NativeWeb.SignIn&version=0.1.1
                    
Install as a Cake Tool

nativeweb.signin

OAuth 2.1 / OIDC relying party for NativeWeb: the authorization-code grant with PKCE, an opaque server-side session behind a __Host- cookie, token refresh, sign-out, and a bearer introspection filter for API endpoints.

NativeWeb is the client, never the server. There is no token issuer here, no consent screen, no realm resolution, no client registry and no identity schema. The provider is whatever conforming issuer the configuration names — one is as good as another, and none of them is named anywhere in this library's source.

<ProjectReference Include="..\..\libs\nativeweb.signin\nativeweb.signin.csproj" />

Published as Extrode.NativeWeb.SignIn for consumers building against packages. The skeleton carries both forms; tools/new-product.ps1 stamps a product with the section already wired.

The whole wiring

builder.Services.AddSignIn(builder.Configuration.GetSection("MyProduct:SignIn"));

app.UseNativeWebPipeline(Locales.All, auth =>
{
    auth.UseAuthentication();
    auth.UseAuthorization();
});

app.MapSignIn();

Three lines and a protected route works:

app.MapGet("/account", (HttpContext http) => http.User.FindFirst(ClaimTypes.NameIdentifier)?.Value)
   .RequireAuthorization();

AddSignIn registers a real authentication scheme, which is what RequireAuthorization needs. Without it a protected route answers a bare 401 to everybody, with no way to sign in. A challenge redirects to LoginPath carrying ?returnTo= for where the visitor was going.

NameIdentifier is the only claim on the principal, and it carries whatever OnSignedIn returned — the provider's subject when no resolver is registered. User.Identity.Name is null: the library mints no name claim, because a display name is the product's to fetch and store, not something to take on the provider's word on every request.

Authentication goes in the pipeline's own slot

auth => { … } is not decoration: UseAuthentication has to run before antiforgery, because the antiforgery check compares a token against the user as it stands when the check runs. Wire it later and a signed-in visitor is anonymous to antiforgery, and the sign-out form is refused with a 400 that says nothing about ordering. UseNativeWebPipeline gives the slot so a product cannot get the order wrong by hand.

Configuration

Every key is a string in one section. AddSignIn(IConfiguration) reads them one at a time — there is no Bind(), no configuration-binder source generator and no reflecting extension, because a reflecting binder is the one dependency that would stop this library publishing AOT-clean. A key that will not parse throws at startup naming its own full path, not at the first request.

Key Required Default What it is
AuthorizationEndpoint yes — Where the browser is sent. From the provider's discovery document.
TokenEndpoint yes — Where the code is exchanged.
UserInfoEndpoint yes — Where the subject is read after exchange.
IntrospectionEndpoint for RequireBearerToken — Where an API's bearer token is checked.
ClientId yes — This product's registration at the provider.
ClientSecret for a confidential client — Environment variable or user-secrets. Never appsettings.json.
RedirectUri yes — Absolute, and registered at the provider. Must resolve to CallbackPath.
Scopes no openid profile email An array. Replaces the defaults wholesale rather than adding to them.
ClientAuthentication no ClientSecretBasic ClientSecretBasic, ClientSecretPost or None for a public client. Under ClientSecretBasic both halves are percent-encoded before the base64, per RFC 6749 2.3.1 — switch to ClientSecretPost for a provider that does not decode.
CookieName no __Host-signin Must keep the __Host- prefix; startup refuses one that does not.
LoginPath no /signin
CallbackPath no /signin/callback
LogoutPath no /signout POST only, antiforgery-checked.
SignedOutPath no / Where sign-out lands.
DefaultReturnPath no / Where a sign-in with no returnTo lands.
FailurePath no / Where a FAILED sign-in lands, carrying ?error=. Cannot be LoginPath or CallbackPath; startup refuses either.
FlowLifetimeSeconds no 1800 How long an in-flight sign-in may take.
SessionLifetimeSeconds no 1209600 Fourteen days.
RefreshSkewSeconds no 120 How early an access token is refreshed.
IntrospectionCacheLifetimeSeconds no 30 Short on purpose: a revoked token stays live for this long.
StoreEncryptionKey see below — Base64 of 32 random bytes.
RetainTokens no true False discards the provider's tokens after userinfo, for a product that reads the subject once and never calls the provider again. Nothing to refresh, and nothing to leak.
AllowEphemeralStoreEncryptionKey no false Development only.

An empty string counts as absent, so a stamped appsettings.json full of "" changes nothing. The same options are settable in code — AddSignIn(options => { … }) — which is what the sample does, because its endpoints are only known once the process knows what port it bound.

The store encryption key

The provider's tokens sit in the session store, and this key is what protects them at rest. Supply 32 random bytes, base64, the same way the client secret is supplied:

Convert.ToBase64String(RandomNumberGenerator.GetBytes(32))

Rotating it signs every session out. Startup refuses a key that is a single repeated byte, because that is a placeholder somebody meant to replace. AllowEphemeralStoreEncryptionKey mints one per process instead — which means sessions do not survive a restart, and it is for a demo.

What the endpoints do

MapSignIn() maps three, at the configured paths:

Method Path What it does
GET LoginPath Mints state and a PKCE verifier, records them, redirects to the provider.
GET CallbackPath Checks state at-most-once, exchanges the code, reads the subject, mints the session, redirects to returnTo.
POST LogoutPath Antiforgery-checked. Drops the session and the cookie, redirects to SignedOutPath.

LoginPath is a GET and carries no antiforgery token, which is not an oversight: it takes no action on the user's behalf and reads no session, so the worst a forced navigation achieves is a login prompt the visitor can decline. state is what defends the callback, which is the request that acts. A GET to LoginPath also ends any sign-in the browser had in progress (the newest flow wins), so a forced navigation can cancel an in-progress sign-in, which the old cookie overwrite already did.

?returnTo= on LoginPath is where the visitor lands afterwards. It is sanitised to a local path — an absolute URL, a scheme-relative one and a backslash-smuggled one all fall back to DefaultReturnPath, so the endpoint is not an open redirect.

A failed sign-in lands at FailurePath as ?error=<code>, one of callback_incomplete, state_used, state_expired, state_unknown, state_mismatch, signin_failed, provider_unavailable, refused (SignInFailureCode). The in-memory store reports a replayed callback as state_unknown, not state_used. No provider-supplied string is ever rendered: the provider's own error and error_description are upstream text, and a page that echoes them is a page that renders whatever the provider felt like sending. Render your own copy per code.

FailurePath cannot be LoginPath, and startup refuses the pairing. GET LoginPath is the flow trigger this library owns; it never reads ?error=, so a failure delivered there starts the flow over. Anything that fails the same way every time — an unconfigured provider, a SignInPolicy that refuses, a SignInResolver returning null — then bounces the browser until it gives up with ERR_TOO_MANY_REDIRECTS, and the code reaches nothing that reads it.

The default is /, which never loops but is also unlikely to explain anything. Point it at a page you render and read the code there.

API endpoints: bearer introspection

app.MapGet("/api/things", () => Things()).RequireBearerToken();

Reads the Authorization: Bearer header, introspects it at IntrospectionEndpoint, caches the verdict for IntrospectionCacheLifetimeSeconds and answers 401 when it is not active. Use RequireBearerToken() and not AddEndpointFilter<BearerIntrospectionFilter>() — the latter activates the filter by type from the container, and everything the filter needs is registered keyed on the scheme name, so it fails at the first request with a message naming OAuthClient rather than the missing scheme.

Calling the provider on the visitor's behalf

With RetainTokens on the library keeps the provider's tokens and refreshes them. ISessionTokens is how a product reads the one in hand:

app.MapGet("/things", async (HttpContext http, ISessionTokens tokens, CancellationToken ct) =>
{
    if (http.User.Identity?.IsAuthenticated != true)
    {
        return Results.Challenge();
    }

    string? token = await tokens.GetAccessTokenAsync(http, ct);
    return token is null ? Results.StatusCode(503) : await ThingsAsync(token, ct);
});

It refreshes first when the token is inside RefreshSkew, through the same gated path the authentication handler uses, so two requests on one session call the provider once between them. Do not read the store and decrypt the row yourself: a second rotation path against a provider that revokes a reused refresh token is how a whole token family dies.

Null is the answer to every case you handle the same way — no cookie, an unknown one, an expired session, a provider that issued no token, and a token that has expired with no refresh token behind it. In all of them the move is not to call the provider.

Null is not "sign in again", which is why the example challenges on User and not on the token. A signed-in visitor gets null while the provider is unreachable and the token in hand has already expired; challenging on that redirects into the provider that is down, comes back, and asks again. Calling it with RetainTokens off does not return null either — it throws, because a scheme that keeps no tokens would otherwise answer null for every visitor forever.

Two things it does that read like side effects because they are. A refresh the provider refuses ends the session: the row goes, the cookie is expired, and HttpContext.User is reset to anonymous for the rest of that request. Expiring a cookie writes a header, so a refusal after the response has started throws — call it before you start streaming. And each call reads the session store: ask once per request and pass the token down. Nothing is cached on the HttpContext, deliberately — a plaintext token in HttpContext.Items is readable by every component that runs after it, and the context itself is pooled and reset when the response completes, so a background task holding one presents the next visitor's cookie. Capture the token, never the context.

It is registered keyed on the scheme name like everything else, and unkeyed as well by the first AddSignIn call. The unkeyed one resolves the host's default authentication scheme at request time, not the scheme that registered it, so it cannot drift from HttpContext.User when a product sets a default of its own. A default scheme that no AddSignIn registered throws, naming it. With two schemes, resolve the one you mean: sp.GetRequiredKeyedService<ISessionTokens>(scheme).

The seams

AddSignIn returns a builder. Every seam on it is optional, and a product that takes none gets in-memory stores, the provider's subject as the session subject, and no policy — a working sign-in for a single-instance product, and the shape the sample runs.

Seam Take it when
.WithFlowStore<T>() More than one process. The in-memory default cannot see a flow another instance started, so a callback landing on the wrong instance is refused. ILoginFlowStore is StartAsync, TakeAsync and SweepAsync, and the take must be at-most-once.
.WithSessionStore<T>() More than one process, or sessions that outlive a restart. ISessionStore is CreateAsync, GetAsync, ReplaceIfMatchAsync, RemoveAsync.
.OnSignedIn(resolver) You keep a local user table. Returns the local key, or null to refuse — in which case no session is minted.
.WithSignInPolicy(policy) You want to refuse some visitors before troubling the provider. Fails closed: a throwing policy refuses. Called concurrently, so hold no per-request state.

OnSignedIn and the only safe key

.OnSignedIn(async (http, subject, contact, ct) => await FindOrCreateAsync(subject.Value, ct));

The two payload parameters are named for what they are, and the naming is the guard. Key on VerifiedSubject. Never on UnverifiedContactInfo.Email — a find-or-create keyed on the address lets anyone who registers at the provider with a victim's address take over the local account. The address is contact information and nothing else.

A subject is unique within one provider only, and with a pairwise provider within one client only. A product configuring two schemes has to store which scheme a subject came from alongside it, or two providers' users collide on one key. This is the failure that looks like nothing until the second provider is added.

Two schemes in one app

AddSignIn(scheme, …) registers everything keyed on the scheme name, so two calls configure two independent providers rather than the second overwriting the first. A session minted under one is a value the other's store has never heard of.

What the library cannot supply is which scheme answers a request that named neither — that is the product's decision, and getting it wrong breaks antiforgery first and least obviously. Choose with a policy scheme:

builder.Services
    .AddAuthentication(o => o.DefaultScheme = "either")
    .AddPolicyScheme("either", "session when there is one, cookie otherwise",
        policy => policy.ForwardDefaultSelector = http =>
            http.Request.Cookies.ContainsKey("__Host-signin")
                ? SessionAuthenticationHandler.SchemeName
                : CookieAuthenticationDefaults.AuthenticationScheme);

apps/sample runs this beside its own cookie demo; apps/sample/DemoSignIn.cs is the worked example, including a whole authorization server in-process so dotnet run completes a real round trip with no external service.

What a product must supply

  • ClientId, and a ClientSecret unless the client is public.
  • The four endpoint URLs, from the provider's discovery document.
  • A RedirectUri registered at the provider, resolving to CallbackPath.
  • A StoreEncryptionKey, as an environment variable or user-secrets.
  • A login page rendering your own copy for each SignInFailureCode.
  • A sign-out form, POSTing to LogoutPath with an antiforgery token. Not a link.
  • .WithFlowStore<T>() and .WithSessionStore<T>() if it runs more than one instance.
  • A policy scheme, if it has a second authentication scheme.
  • The order in the pipeline, which UseNativeWebPipeline(…, auth => …) gives it.

Testing your stores

libs/nativeweb.signin.testing carries the conformance suites. Derive from SessionStoreConformance or LoginFlowStoreConformance, hand it your implementation, and it asserts the contract the library relies on — the at-most-once take in particular, which is the one an obvious implementation gets wrong under concurrency.

NativeAOT

The library publishes with no IL2xxx/IL3xxx warnings, and tests/nativeweb.signin.tests.aot is the gate: it publishes a probe host referencing nothing else and fails on any analyser warning. Two rules keep it that way, and both are about the consumer's publish rather than this one:

  • Route handlers are static lambdas written at the call site. A route built in a loop, or handed a Delegate variable, falls back to the reflection overload and fails the consumer's publish gate with IL2026/IL3050.
  • No serializer over an anonymous or reflected type. Fixed-shape payloads are written out.
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Extrode.NativeWeb.SignIn:

Package Downloads
Extrode.NativeWeb.SignIn.Testing

Test-only fixtures for NativeWeb.SignIn: conformance suites for ILoginFlowStore and ISessionStore, and TestSession for minting sessions in a consumer's integration tests.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.1 108 11/3/2026
0.1.0 112 11/3/2026