sdk/dotnet

.NET 8 서버 SDK — 네트워크 호출 없는 JWT 검증, ASP.NET Core 요청 인증, webhook 서명 검증을 지원합니다.

상태

로컬에서 구현 및 검증되었습니다. 실제 IdP 왕복 검증(JWKS 가져오기, 실제 XID 인스턴스에 대한 토큰 서명/검증)은 아직 수행되지 않았으며 프로덕션 사용 전에 완료되어야 합니다.

설치

.NET 8 이상이 필요합니다.

<PackageReference Include="Xid" Version="0.1.0" />

ASP.NET Core 설정(권장)

// Program.cs
using Xid;

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

요청 인증

// 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,
            cookies: Request.Cookies.ToDictionary(c => c.Key, c => c.Value));

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

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

토큰을 직접 검증합니다

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}");
}

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

속성	기본값	설명
`Issuer`	필수	XID 발급자 URL
`Audience`	`null`	예상 aud 클레임; null이면 검증을 건너뜁니다
`JwksTtl`	1시간	JWKS 인메모리 캐시 TTL
`SessionCookieName`	`__session`	토큰 추출을 위한 폴백 cookie 이름
`ClockSkew`	5분	JWT exp/nbf 클럭 편차 허용 범위
`WebhookToleranceWindow`	5분	Webhook 재사용 방지 윈도우

XidClient API

방법	설명
`VerifyTokenAsync(token, ct)`	JWT 문자열을 검증합니다. 실패 시 `TokenVerificationException`을 발생시킵니다.
`AuthenticateRequestAsync(authHeader, cookies, ct)`	토큰을 추출하고 검증합니다; `AuthStatus`를 반환하며 예외를 발생시키지 않습니다.
`VerifyWebhook(payload, headers, secret)`	webhook 서명을 검증합니다. 실패 시 `WebhookVerificationException`을 발생시킵니다. 동기식.

플랫폼 참고 사항

Microsoft.IdentityModel.Tokens와 System.IdentityModel.Tokens.Jwt 8.x를 사용합니다. ES256이 기본이며 RS256과 PS256이 지원됩니다.
AddXid()는 XidClient를 싱글턴으로 등록하고 JWKS 가져오기를 위해 IHttpClientFactory를 연결합니다.
예외 계층 구조: XidException -> JwksException, TokenVerificationException, WebhookVerificationException.