---
title: "sdk/go"
description: "네트워크 호출 없는 JWT 검증, 요청 인증, webhook 서명 검증을 위한 Go 서버 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/go

## 상태

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

## 설치

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

## 빠른 시작

애플리케이션 시작 시 `Client`를 하나 생성하여 요청 전반에 재사용하세요. 클라이언트는 구성 가능한 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 요청 서명을 검증합니다. 성공 시 원시 body가 포함된 `*WebhookEvent`를 반환합니다. |

## ClientOptions

| 필드 | 기본값 | 설명 |
| --- | --- | --- |
| `Issuer` | 필수 | XID 발급자 URL |
| `Audience` | 비어 있음(건너뜀) | 예상 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/ko/sdks/go/index.mdx