---
title: "sdk/go"
description: "ネットワークレス JWT 検証、リクエスト認証、webhook 署名検証用の Go サーバー 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/go

## 状態

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

## インストール

```shell
go get github.com/StringKe/xid/sdk/go
```

## クイックスタート

アプリケーション起動時に `Client` を 1 つ作成してリクエスト間で再利用します。クライアントは設定可能な TTL で内部的に JWKS をキャッシュします。

```go
import "github.com/StringKe/xid/sdk/go/xid"

client, err := xid.NewClient(xid.ClientOptions{
Issuer:        "https://xid.dev",
Audience:      "your-client-id",
WebhookSecret: "whs_...",
})
if err != nil {
log.Fatal(err)
}

// HTTP middleware (recommended)
http.Handle("/api/", client.Middleware(apiHandler, func(w http.ResponseWriter, r *http.Request) {
http.Error(w, `{"error":"unauthorized"}`, http.StatusUnauthorized)
}))

// Inside a protected handler
func apiHandler(w http.ResponseWriter, r *http.Request) {
claims := xid.ClaimsFromContext(r.Context())
fmt.Fprintf(w, "hello %s", claims.Subject)
}
```

## トークンを直接検証します

```go
claims, err := client.VerifyAccessToken(ctx, tokenString)
if err != nil {
// handle verification failure
}
fmt.Println(claims.Subject, claims.OrgID)
```

## webhook を検証

```go
func webhookHandler(w http.ResponseWriter, r *http.Request) {
event, err := client.VerifyWebhook(r)
if err != nil {
    http.Error(w, "invalid signature", http.StatusBadRequest)
    return
}
// event.Body: raw JSON body
// event.ID:   svix-id for idempotency
w.WriteHeader(http.StatusNoContent)
}
```

## コア API

| シンボル | 説明 |
| --- | --- |
| `NewClient(opts)` | クライアントを構築します。`Issuer` は必須で、他のフィールドはオプションです。 |
| `(*Client).VerifyAccessToken(ctx, token)` | JWT 文字列を検証し、`*Claims` またはエラーを返します。 |
| `(*Client).AuthenticateRequest(ctx, r)` | HTTP リクエストからトークンを取得して検証します。常に `AuthState` を返し、パニックしません。 |
| `(*Client).Middleware(next, onUnauthorized)` | 標準 `net/http` ミドルウェア。成功時にコンテキストへ `*Claims` を注入します。 |
| `ClaimsFromContext(ctx)` | ミドルウェアが注入したクレームを取得します。 |
| `(*Client).VerifyWebhook(r)` | webhook リクエストの署名を検証します。成功時は生のボディを含む `*WebhookEvent` を返します。 |

## ClientOptions

| フィールド | デフォルト | 説明 |
| --- | --- | --- |
| `Issuer` | 必須 | XID 発行者 URL |
| `Audience` | （スキップ） | expected JWT aud クレーム |
| `WebhookSecret` | （空） | webhook HMAC 署名シークレット |
| `JWKSCacheTTL` | `1h` | JWKS ローカルキャッシュ TTL |
| `HTTPClient` | 10 秒タイムアウト（デフォルト） | JWKS 取得用 HTTP クライアント |

## プラットフォームの注意事項

- ES256 が主要アルゴリズムです。RS256 は互換性のためにサポートされています。ES384 と ES512 はまだ実装されていません。
- JWKS は `{issuer}/jwks` から取得されます。OIDC Discovery の自動検出は計画中の改善です。
- `Claims` は `jwt.RegisteredClaims` を埋め込み、`ClientID`、`Scope`、`AMR`、`ACR`、`OrgID`、`OrgSlug` を追加します。

Source: https://xid.dev/ja/sdks/go/index.mdx