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

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/ja/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/java

## 状態

ローカルで実装および検証済み。実際の IdP ラウンドトリップ検証（JWKS 取得、実稼働 Vonvon インスタンスに対するトークン署名/検証）はまだ実行されておらず、本番利用前に完了する必要があります。

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

リクエスト認証はデフォルトで Bearer のみを受け付けます。アプリケーション所有の JWT cookie は、その正確な名前を設定した場合にのみ読み取られます。不透明な \_\_Host-vonvon.rt.\* Core cookie はスキャンもローカル検証も行いません。完全な Cookie header を exact same-origin の POST /v1/sessions/token に redirect 無効で転送して交換し、token フィールドだけを含むレスポンスのみ受け入れてください。

## インストール

Java 17+ と Maven が必要です。

```xml
<!-- First install the source checkout: cd sdk/java && mvn install -->
<dependency>
  <groupId>dev.vonvon</groupId>
  <artifactId>vonvon-sdk-java</artifactId>
  <version>0.1.0-alpha.0</version>
</dependency>
```

## クイックスタート

アプリケーション起動時に `VonvonClient` を 1 つ作成し、シングルトンとして使用します。

```java
import dev.vonvon.sdk.VonvonClient;
import dev.vonvon.sdk.VonvonClientOptions;
import dev.vonvon.sdk.VonvonClaims;
import dev.vonvon.sdk.VonvonTokenException;
import dev.vonvon.sdk.VonvonJwksException;

VonvonClient vonvon = VonvonClient.create(
VonvonClientOptions.builder()
    .issuer("https://vonvon.id")
    .audience("your-client-id")
    .webhookSecret("whsec_xxx")
    .build()
);

try {
VonvonClaims claims = vonvon.verifyToken(accessToken);
String userId = claims.getSub();
String scope  = claims.getScope();
} catch (VonvonTokenException e) {
response.sendError(401, "Unauthorized: " + e.getReason());
} catch (VonvonJwksException e) {
response.sendError(503, "Service unavailable");
}
```

## HTTP リクエストを認証します

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

// Bearer-only by default
AuthResult result = vonvon.authenticateRequest(request.getHeader("Authorization"), null);

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

String token = vonvon.exchangeSessionToken(
request.getRequestURL().toString(),
request.getHeader("Cookie"),
"/v1/sessions/token"
);
```

## webhook を検証

```java
import dev.vonvon.sdk.VonvonWebhookException;

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 {
vonvon.verifyWebhook(headers, rawBody);
} catch (VonvonWebhookException e) {
response.sendError(400, "Invalid webhook: " + e.getReason());
}
```

## VonvonClientOptions

| 方式 | デフォルト | 説明 |
| --- | --- | --- |
| `.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）。
- 例外階層：`VonvonException` -&gt; `VonvonTokenException`、`VonvonJwksException`、`VonvonWebhookException`。

Source: https://vonvon.id/ja/sdks/java/index.mdx