---
title: "sdk/java"
description: "ネットワークレス JWT 検証、HTTP リクエスト認証、webhook 署名検証用の Java 17+ サーバー SDK。"
locale: "ja"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/ja/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` を 1 つ作成し、シングルトンとして使用します。

```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 発行者。トークンの iss と完全に一致する必要があります |
| `.audience(String)` | `null` | expected 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/ja/sdks/java/index.mdx