---
title: "sdk/java"
description: "네트워크 호출 없는 JWT 검증, HTTP 요청 인증, webhook 서명 검증을 위한 Java 17+ 서버 SDK."
locale: "ko"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/ko/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/java

## 상태

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

## 설치

Java 17 이상과 Maven이 필요합니다.

```xml
<dependency>
  <groupId>dev.xid</groupId>
  <artifactId>xid-sdk-java</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>
```

## 빠른 시작

애플리케이션 시작 시 `XidClient`를 하나 생성하여 싱글턴으로 사용하세요.

```java
import dev.xid.sdk.XidClient;
import dev.xid.sdk.XidClientOptions;
import dev.xid.sdk.XidClaims;
import dev.xid.sdk.XidTokenException;
import dev.xid.sdk.XidJwksException;

XidClient xid = XidClient.create(
XidClientOptions.builder()
    .issuer("https://xid.dev")
    .audience("your-client-id")
    .webhookSecret("whsec_xxx")
    .build()
);

try {
XidClaims claims = xid.verifyToken(accessToken);
String userId = claims.getSub();
String scope  = claims.getScope();
} catch (XidTokenException e) {
response.sendError(401, "Unauthorized: " + e.getReason());
} catch (XidJwksException e) {
response.sendError(503, "Service unavailable");
}
```

## HTTP 요청 인증

```java
import dev.xid.sdk.AuthResult;

// Option A: pass Authorization header value directly
AuthResult result = xid.authenticateRequest(authHeader, null);

// Option B: pass a headers Map (Spring MVC example)
Map<String, String> headers = Collections.list(request.getHeaderNames())
.stream()
.collect(Collectors.toMap(h -> h, request::getHeader));
AuthResult result = xid.authenticateRequest(headers);

if (result.isAuthenticated()) {
String userId = result.getClaims().get().getSub();
} else {
response.sendError(401);
}
```

## webhook 검증

```java
import dev.xid.sdk.XidWebhookException;

byte[] rawBody = request.getInputStream().readAllBytes();
Map<String, String> headers = Map.of(
"svix-id",        request.getHeader("svix-id"),
"svix-timestamp", request.getHeader("svix-timestamp"),
"svix-signature", request.getHeader("svix-signature")
);

try {
xid.verifyWebhook(headers, rawBody);
} catch (XidWebhookException e) {
response.sendError(400, "Invalid webhook: " + e.getReason());
}
```

## XidClientOptions

| 방법 | 기본값 | 설명 |
| --- | --- | --- |
| `.issuer(String)` | 필수 | OIDC issuer; 토큰의 iss와 정확히 일치해야 합니다 |
| `.audience(String)` | `null` | 예상 aud; null이면 검증을 건너뜁니다 |
| `.webhookSecret(String)` | `null` | Webhook 시크릿(`whsec_` 접두사 또는 일반 base64) |
| `.jwksCacheDuration(Duration)` | 1시간 | JWKS 인메모리 캐시 TTL |
| `.clockSkewTolerance(Duration)` | 30초 | exp/nbf 클럭 편차 허용 범위 |
| `.connectTimeout(Duration)` | 5초 | JWKS 가져오기용 HTTP 연결 타임아웃 |
| `.readTimeout(Duration)` | 10초 | JWKS 가져오기용 HTTP 읽기 타임아웃 |

## 플랫폼 참고 사항

- JWT/JWKS 파싱에 `nimbus-jose-jwt`를 사용합니다. ES256이 기본이며 RS256과 PS256이 지원됩니다.
- 모든 공개 API는 동기식이며 스레드 안전합니다.
- SLF4J 퍼사드를 통한 로깅; 구현체(Logback, Log4j2)를 직접 가져오세요.
- 예외 계층 구조: `XidException` -&gt; `XidTokenException`, `XidJwksException`, `XidWebhookException`.

Source: https://xid.dev/ko/sdks/java/index.mdx