sdk/dotnet

SDK serveur .NET 8 pour la vérification JWT sans réseau,l'authentification des requêtes ASP.NET Core et la validation dessignatures webhook.

Statut

Implémenté et vérifié localement. La vérification aller-retour avec unvrai IdP (récupération JWKS, signature/vérification de jeton contre uneinstance XID active) n’a pas encore été effectuée et doit être complétéeavant toute utilisation en production.

Statut du registre : UNPUBLISHED. Installez ce SDK uniquement depuis un checkout du code source du dépôt ; n’utilisez pas de registre de paquets externe.

L’authentification des requêtes accepte uniquement Bearer par défaut. Un cookie JWT détenu par l’application n’est lu que lorsque son nom exact est configuré. Le cookie Core opaque __Host-xid.rt.* n’est jamais recherché ni vérifié localement ; échangez-le en transférant le header Cookie complet vers le POST /v1/sessions/token de même origine exacte, avec les redirections désactivées, et n’acceptez qu’une réponse contenant uniquement le champ token.

Installer

.NET 8 requis comme cible.

<ItemGroup>
  <ProjectReference Include="../xid/sdk/dotnet/Xid.csproj" />
</ItemGroup>

Configuration ASP.NET Core (recommandée)

// Program.cs
using Xid;

builder.Services.AddXid(options =>
{
    options.Issuer   = "https://xid.dev";
    options.Audience = "your-client-id"; // optional
});

Authentifier une requête

// Controller / Minimal API
public class MyController(XidClient xid) : ControllerBase
{
    [HttpGet("/me")]
    public async Task<IActionResult> GetMe()
    {
        var auth = await xid.AuthenticateRequestAsync(
            authorizationHeader: Request.Headers.Authorization);

        if (!auth.Authenticated)
            return Unauthorized(auth.Reason);

        return Ok(new { sub = auth.Claims!.Sub, email = auth.Claims.Email });
    }

    private Task<string> ExchangeSessionAsync() => xid.ExchangeSessionTokenAsync(
        $"{Request.Scheme}://{Request.Host}{Request.Path}",
        Request.Headers.Cookie.ToString());
}

Vérifier le jeton directement

using Xid;

var client = new XidClient(new XidOptions { Issuer = "https://xid.dev" });

try
{
    var claims = await client.VerifyTokenAsync("eyJ...");
    Console.WriteLine($"sub={claims.Sub} email={claims.Email}");
}
catch (TokenVerificationException ex)
{
    Console.WriteLine($"Invalid token: {ex.Message}");
}

Vérifier le webhook

app.MapPost("/webhooks/xid", async (HttpRequest req, XidClient xid) =>
{
    using var ms = new MemoryStream();
    await req.Body.CopyToAsync(ms);
    var body = ms.ToArray();

    var headers = new Dictionary<string, string>
    {
        ["svix-id"]        = req.Headers["svix-id"].ToString(),
        ["svix-timestamp"] = req.Headers["svix-timestamp"].ToString(),
        ["svix-signature"] = req.Headers["svix-signature"].ToString(),
    };

    var webhookSecret = Environment.GetEnvironmentVariable("XID_WEBHOOK_SECRET")
        ?? throw new InvalidOperationException("XID_WEBHOOK_SECRET is required");

    try
    {
        var webhook = xid.VerifyWebhook(body, headers, secret: webhookSecret);
        return Results.Ok();
    }
    catch (WebhookVerificationException ex)
    {
        return Results.BadRequest(ex.Message);
    }
});

XidOptions

Propriété	Défaut	Description
`Issuer`	requis	URL d’émetteur XID
`Audience`	`null`	Revendication aud attendue ; null ignore la validation
`JwksTtl`	1 heure	TTL du cache JWKS en mémoire
`SessionCookieName`	`disabled`	Nom du cookie JWT détenu par l’application ; désactivé sauf configuration explicite
`ClockSkew`	5 minutes	Tolérance au décalage d’horloge JWT pour exp/nbf
`WebhookToleranceWindow`	5 minutes	Fenêtre de prévention des relectures de webhook

API XidClient

Méthode	Description
`VerifyTokenAsync(token, ct)`	Vérifier la chaîne JWT ; lève `TokenVerificationException` en casd’échec.
`AuthenticateRequestAsync(authHeader, cookies, ct)`	Extraire et vérifier le jeton ; retourne `AuthStatus` ; ne lève pasd’exception.
`VerifyWebhook(payload, headers, secret)`	Valider la signature webhook ; lève `WebhookVerificationException` encas d’échec. Synchrone.

Notes de plateforme

Utilise Microsoft.IdentityModel.Tokens etSystem.IdentityModel.Tokens.Jwt 8.x. ES256 est principal ; RS256 etPS256 sont pris en charge.
AddXid() enregistre XidClient en tant que singleton et câbleIHttpClientFactory pour la récupération JWKS.
Hiérarchie d’exceptions : XidException -> JwksException,TokenVerificationException, WebhookVerificationException.