sdk/windows

C# / .NET SDK for WinUI 3 applications using WebView2 for authorization, PKCE S256, and DPAPI-protected IsolatedStorage for token persistence.

Status

Package status is Implemented · verified locally. dotnet test passes 19 cases (net8.0 cross-platform build and net10.0). Windows-specific APIs (WebView2, DPAPI, WinUI 3) require a Windows build environment to verify. Real IdP round-trip is pending manual verification. This page documents implemented behavior; it is not a production-readiness claim.

Requirements

.NET 8 and Windows App SDK 1.6+
WebView2 Runtime (Evergreen — pre-installed with Microsoft Edge)
Application must set <UseWinUI>true</UseWinUI> in the project file

Installation

Add a PackageReference to your application project file:

<ItemGroup>
  <PackageReference Include="Xid.Windows" Version="0.1.0" />
</ItemGroup>

Quick start

using Xid.Windows;

// 1. Configure in App.xaml.cs OnLaunched
XidClient.Shared.Configure(new XidConfiguration
{
    Issuer      = new Uri("https://xid.dev"),
    ClientId    = "your_client_id",
    RedirectUri = "com.example.myapp://auth/callback",
    // Scopes default: openid profile email offline_access
});

// 2. Sign in (opens embedded WebView2 window)
XidSession session = await XidClient.Shared.SignInAsync();
Console.WriteLine($"Signed in: {session.User.Email}");

// 3. Get a valid access token (auto-refresh)
string? token = await XidClient.Shared.GetAccessToken();

// 4. Get current session
XidSession? current = await XidClient.Shared.GetSession();

// 5. Sign out
await XidClient.Shared.SignOut();

Custom URI scheme callback (optional)

If using a custom URI scheme redirect rather than the WebView2 embedded window, forward the protocol activation URI to HandleRedirectAsync:

// App.xaml.cs
protected override void OnActivated(IActivatedEventArgs args)
{
    if (args.Kind == ActivationKind.Protocol)
    {
        var protocolArgs = (ProtocolActivatedEventArgs)args;
        await XidClient.Shared.HandleRedirectAsync(protocolArgs.Uri);
    }
}

Core API

Method	Description
`Configure(XidConfiguration)`	Initialize SDK. Call once at application startup.
`SignInAsync(options?, ct)`	Open an embedded WebView2 authorization window with PKCE S256. Returns XidSession on completion.
`HandleRedirectAsync(Uri, ct)`	Process a custom URI scheme callback and exchange the authorization code.
`GetSession(ct)`	Return the current session, refreshing automatically if near expiry.
`GetAccessToken(options?, ct)`	Return a valid access token string, triggering refresh if needed.
`SignOut(ct)`	Clear local session tokens from DPAPI-protected IsolatedStorage.
`SetTokenStorage(ITokenStorage)`	Replace the default DpapiTokenStorage with a custom ITokenStorage implementation.

Storage adapter

The default storage encrypts tokens with DPAPI (CurrentUser scope) and persists them in IsolatedStorage. Implement ITokenStorage to use Windows Hello or Credential Manager:

public sealed class MyCustomStorage : ITokenStorage
{
    public Task SaveAsync(StoredTokenSet tokens, CancellationToken ct = default) { ... }
    public Task<StoredTokenSet?> LoadAsync(CancellationToken ct = default) { ... }
    public Task ClearAsync(CancellationToken ct = default) { ... }
}
XidClient.Shared.SetTokenStorage(new MyCustomStorage());

Dependencies

Package	Version	Purpose
`Microsoft.WindowsAppSDK`	1.6.250228002	WinUI 3 host and WebView2 embedding
`Microsoft.Web.WebView2`	1.0.3065.39	Chromium-based embedded authorization window
`System.Security.Cryptography.ProtectedData`	8.0.0	DPAPI token encryption at rest

Security

Public client — no client secret stored or transmitted.
PKCE S256 only. Server rejects plain challenge method.
Tokens encrypted with DPAPI (CurrentUser scope) and stored in IsolatedStorage. Not accessible to other Windows user accounts.
OAuth state generated per request; validated on redirect to prevent CSRF.

Known limitations

WebView2 Runtime must be present. WebAuthenticationBroker support as a fallback is planned but not yet implemented.
JWKS-backed ID token verification and end_session sign-out are implemented and locally tested. Real Windows WebView2, DPAPI, and IdP round-trip validation is still required before L4 support.
DpapiTokenStorage does not run on non-Windows platforms. Use a different ITokenStorage implementation when cross-compiling.