sdk/windows

C#/.NET-SDK für WinUI-3-Anwendungen mit WebView2 für die Autorisierung,PKCE S256 und DPAPI-geschütztem IsolatedStorage zur Token-Persistenz.

Zustand

Paketstatus: Implementiert · lokal verifiziert. dotnet test besteht19 Fälle (net8.0 plattformübergreifendes Build und net10.0).Windows-spezifische APIs (WebView2, DPAPI, WinUI 3) erfordern eineWindows-Build-Umgebung zur Verifizierung. Der echte IdP-Round-Trip stehtmanuell aus. Diese Seite dokumentiert implementiertes Verhalten und stelltkeinen Produktionsbereitschaftsnachweis dar.

Anforderungen

.NET 8 und Windows App SDK 1.6+
WebView2-Runtime (Evergreen — vorinstalliert mit Microsoft Edge)
Die Anwendung muss <UseWinUI>true</UseWinUI> in der Projektdatei setzen

Installation

Fügen Sie Ihrer Anwendungsprojektdatei eine PackageReference hinzu:

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

Schnellstart

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();

Callback für benutzerdefiniertes URI-Schema (optional)

Wenn anstelle des eingebetteten WebView2-Fensters eine Weiterleitung überein benutzerdefiniertes URI-Schema verwendet wird, leiten Sie denProtokollaktivierungs-URI an HandleRedirectAsync weiter:

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

Kern-API

Methode	Beschreibung
`Configure(XidConfiguration)`	SDK initialisieren. Einmalig beim Anwendungsstart aufrufen.
`SignInAsync(options?, ct)`	Ein eingebettetes WebView2-Autorisierungsfenster mit PKCE S256 öffnen.Gibt XidSession nach Abschluss zurück.
`HandleRedirectAsync(Uri, ct)`	Einen Custom-URI-Schema-Callback verarbeiten und den Autorisierungscodeeintauschen.
`GetSession(ct)`	Die aktuelle Sitzung zurückgeben, bei nahendem Ablauf automatischerneuern.
`GetAccessToken(options?, ct)`	Einen gültigen Access-Token-String zurückgeben, bei Bedarf Erneuerungauslösen.
`SignOut(ct)`	Lokale Sitzungs-Tokens aus dem DPAPI-geschützten IsolatedStorage löschen.
`SetTokenStorage(ITokenStorage)`	Den Standard-DpapiTokenStorage durch eine benutzerdefinierteITokenStorage-Implementierung ersetzen.

Speicher-Adapter

Der Standard-Speicher verschlüsselt Tokens mit DPAPI (CurrentUser-Bereich)und persistiert sie in IsolatedStorage. Implementieren SieITokenStorage, um Windows Hello oder denAnmeldeinformations-Manager zu verwenden:

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());

Abhängigkeiten

Paket	Version	Zweck
`Microsoft.WindowsAppSDK`	1.6.250228002	WinUI-3-Host und WebView2-Einbettung
`Microsoft.Web.WebView2`	1.0.3065.39	Chromium-basiertes eingebettetes Autorisierungsfenster
`System.Security.Cryptography.ProtectedData`	8.0.0	DPAPI-Token-Verschlüsselung im Ruhezustand

Sicherheit

Öffentlicher Client — kein Client-Secret gespeichert oder übertragen.
Nur PKCE S256. Der Server lehnt die Plain-Challenge-Methode ab.
Tokens mit DPAPI (CurrentUser-Bereich) verschlüsselt und inIsolatedStorage gespeichert. Für andere Windows-Benutzerkonten nichtzugänglich.
OAuth-State wird pro Anfrage generiert; bei der Weiterleitung zurCSRF-Prävention validiert.

Bekannte Einschränkungen

WebView2-Runtime muss vorhanden sein.WebAuthenticationBroker-Unterstützung als Fallback ist geplant, aber nochnicht implementiert.
JWKS-gestützte ID-Token-Prüfung und end_session-Abmeldung sind implementiert und lokal getestet. Für L4 sind noch echte Windows-WebView2-, DPAPI- und IdP-Tests erforderlich.
DpapiTokenStorage läuft nicht auf Nicht-Windows-Plattformen. Verwenden Siebeim Cross-Compiling eine andere ITokenStorage-Implementierung.