sdk/php | XID

네트워크 호출 없는 JWT 검증, PSR-7 요청 인증, webhook 서명 검증을 위한 PHP 8.1+ 서버 SDK.

상태

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

설치

PHP 8.1 이상이 필요합니다. 핵심 의존성은 Composer가 자동으로 가져옵니다.

composer require xid/xid

빠른 시작

use Xid\XidClient;
use Xid\Exception\TokenException;
use Xid\Exception\JwksException;

$xid = new XidClient([
    'issuer'   => 'https://xid.dev',
    'audience' => 'your-client-id',
    'cache'    => $psrSimpleCacheImpl, // PSR-16; null disables JWKS cache
]);

try {
    $claims = $xid->verifyToken($jwtString);
    echo $claims->sub();    // user ID
    echo $claims->scope();  // "openid profile email"
    echo implode(',', $claims->amr()); // "phr" / "otp"
} catch (TokenException $e) {
    http_response_code(401);
} catch (JwksException $e) {
    http_response_code(503);
}

PSR-7 요청 인증

$result = $xid->authenticateRequest($psrRequest);

if ($result->isAuthenticated()) {
    $userId = $result->claims()->sub();
} else {
    // $result->reason() for server-side logs only
    http_response_code(401);
}

webhook 검증

use Xid\Exception\WebhookException;

try {
    $payload = $xid->verifyWebhook($psrRequest, 'whsec_...');
    $type = $payload->type();  // "user.created"
    $data = $payload->data();
} catch (WebhookException $e) {
    http_response_code(400);
}

XidClient 옵션

키	기본값	설명
`issuer`	필수	XID 발급자 URI
`audience`	`null`	예상 audience; null이면 검증을 건너뜁니다
`cache`	`null`	JWKS 캐싱을 위한 PSR-16 CacheInterface
`jwks_ttl`	`3600`	초 단위 JWKS 캐시 TTL
`clock_leeway`	`0`	초 단위 JWT 클럭 편차 허용 범위
`cookie_name`	`__xid_session`	토큰 추출을 위한 세션 cookie 키

XidClient 메서드

방법	반환값	설명
`verifyToken(string $token)`	`Claims`	JWT 문자열을 검증합니다. 실패 시 예외를 발생시킵니다
`authenticateRequest(ServerRequestInterface $request)`	`AuthResult`	PSR-7 요청 인증; 예외를 발생시키지 않습니다
`verifyWebhook(ServerRequestInterface $request, string $secret)`	`WebhookPayload`	webhook 서명을 검증합니다. 실패 시 예외를 발생시킵니다
`refreshJwks()`	`void`	JWKS 캐시 강제 갱신

플랫폼 참고 사항

ES256/RS256 검증에 firebase/php-jwt를 사용합니다. HS256과 none 알고리즘은 거부됩니다.
authenticateRequest와 verifyWebhook에는 PSR-7 요청 객체가 필요합니다. 필요한 경우 PSR-7 브리지를 사용하여 프레임워크 네이티브 요청을 변환하세요.
예외 계층 구조: XidException -> TokenException, JwksException, WebhookException.