sdk/python

네트워크 호출 없는 JWT 검증, 요청 인증, webhook 서명 검증을 지원하는 비동기 Python 서버 SDK.

상태

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

설치

pip install xid

빠른 시작

시작 시 XidClient를 하나 생성하여 재사용하세요. 클라이언트는 JWKS를 내부적으로 캐시합니다.

from xid import XidClient

client = XidClient(
    issuer="https://xid.dev",
    audience="https://api.yourapp.com",  # optional
)

# Verify a token
claims = await client.verify_token("eyJ...")
print(claims.sub, claims.email, claims.scope)

# Authenticate a request
status = await client.authenticate_request(
    headers=dict(request.headers),
    cookies=dict(request.cookies),
)
if not status.authenticated:
    raise Unauthorized()
user_id = status.claims.sub

webhook 검증

from xid import WebhookVerificationError

try:
    webhook = client.verify_webhook(
        payload=request.body,
        headers=dict(request.headers),
        secret="whsec_xxx",
    )
    import json
    event = json.loads(webhook.body)
except WebhookVerificationError as exc:
    raise BadRequest(str(exc))

FastAPI 통합

from fastapi import FastAPI, Depends, HTTPException, Request
from xid import XidClient, TokenClaims

app = FastAPI()
xid = XidClient(issuer="https://xid.dev")

@app.on_event("shutdown")
async def shutdown():
    await xid.aclose()

async def require_auth(request: Request) -> TokenClaims:
    status = await xid.authenticate_request(dict(request.headers))
    if not status.authenticated:
        raise HTTPException(status_code=401)
    return status.claims

@app.get("/me")
async def me(claims: TokenClaims = Depends(require_auth)):
    return {"sub": claims.sub, "email": claims.email}

XidClient 옵션

파라미터	기본값	설명
`issuer`	필수	XID 발급자 URL
`audience`	`None`	예상 aud 클레임; None이면 검증을 건너뜁니다
`jwks_ttl`	`3600`	초 단위 JWKS 인메모리 캐시 TTL
`http_timeout`	`10.0`	초 단위 JWKS 가져오기 타임아웃
`cookie_name`	`__session`	세션 토큰 추출을 위한 cookie 키
`leeway`	`0`	초 단위 클럭 편차 허용 범위

핵심 API

방법	설명
`await client.verify_token(token)`	JWT 문자열을 검증합니다. 실패 시 `TokenVerificationError`를 발생시킵니다.
`await client.authenticate_request(headers, cookies)`	헤더/cookie에서 토큰을 추출하고 검증합니다. `AuthStatus`를 반환하며 예외를 발생시키지 않습니다.
`client.verify_webhook(payload, headers, secret)`	동기식. svix HMAC-SHA256 + 5분 재사용 방지 윈도우를 검증합니다. 실패 시 `WebhookVerificationError`를 발생시킵니다.
`await client.aclose()`	기반 HTTP 클라이언트 리소스를 해제합니다.

플랫폼 참고 사항

비동기 우선 방식입니다. 동기 호출자(Django/Flask)는 asyncio.run()으로 감쌀 수 있습니다.
pyjwt[crypto] >=2.8과 httpx >=0.27에 의존합니다. Python 3.10 이상이 필요합니다.
다중 worker 배포에서는 프로세스 간 JWKS 캐시를 공유하지 않습니다. 공유 캐시(Redis)는 향후 개선 계획에 있습니다.