---
title: "sdk/go"
description: "SDK serveur Go pour la vérification JWT sans réseau, l'authentificationdes requêtes et la validation des signatures webhook."
locale: "fr"
---

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

# sdk/go

## Statut

Implémenté et vérifié localement. La vérification aller-retour avec unvrai IdP (récupération JWKS, signature/vérification de jeton contre uneinstance Vonvon active) n'a pas encore été effectuée et doit être complétéeavant toute utilisation en production.

Statut du registre : UNPUBLISHED. Installez ce SDK uniquement depuis un checkout du code source du dépôt ; n'utilisez pas de registre de paquets externe.

L'authentification des requêtes accepte uniquement Bearer par défaut. Un cookie JWT détenu par l'application n'est lu que lorsque son nom exact est configuré. Le cookie Core opaque \_\_Host-vonvon.rt.\* n'est jamais recherché ni vérifié localement ; échangez-le en transférant le header Cookie complet vers le POST /v1/sessions/token de même origine exacte, avec les redirections désactivées, et n'acceptez qu'une réponse contenant uniquement le champ token.

## Installer

```shell
go get github.com/StringKe/vonvon/sdk/go@main
```

## Démarrage rapide

Créez un seul `Client` au démarrage de l'application et réutilisez-lepour toutes les requêtes. Le client met le JWKS en cache en interne avecun TTL configurable.

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

client, err := vonvon.NewClient(vonvon.ClientOptions{
Issuer:        "https://vonvon.id",
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 := vonvon.ClaimsFromContext(r.Context())
fmt.Fprintf(w, "hello %s", claims.Subject)
}
```

## Vérifier le jeton directement

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

// Explicit same-origin Core session -> JWT exchange
token, err := client.ExchangeSessionToken(
ctx,
"https://app.example.com/account",
request.Header.Get("Cookie"),
"/v1/sessions/token",
)
```

## Vérifier le 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 principale

| Symbole | Description |
| --- | --- |
| `NewClient(opts)` | Construire le client. `Issuer` est requis ; les autres champs sontoptionnels. |
| `(*Client).VerifyAccessToken(ctx, token)` | Vérifier une chaîne JWT, retourner `*Claims` ou une erreur. |
| `(*Client).AuthenticateRequest(ctx, r)` | Extraire et vérifier le jeton d'une requête HTTP. Retourne toujours`AuthState`, ne panique pas. |
| `(*Client).Middleware(next, onUnauthorized)` | Middleware `net/http` standard. Injecte `*Claims` dans lecontexte en cas de succès. |
| `ClaimsFromContext(ctx)` | Extraire les revendications injectées par le Middleware. |
| `(*Client).VerifyWebhook(r)` | Vérifier la signature de la requête webhook. Retourne `*WebhookEvent`avec le corps brut en cas de succès. |

## ClientOptions

| Champ | Défaut | Description |
| --- | --- | --- |
| `Issuer` | requis | URL d'émetteur Vonvon |
| `Audience` | vide (ignorer) | Revendication aud JWT attendue |
| `WebhookSecret` | vide | Secret de signature HMAC pour webhook |
| `JWKSCacheTTL` | `1h` | TTL du cache JWKS local |
| `HTTPClient` | Délai d'attente par défaut de 10s | Client HTTP pour la récupération JWKS |

## Notes de plateforme

- ES256 est l'algorithme principal ; RS256 est pris en charge pour lacompatibilité. ES384 et ES512 ne sont pas encore implémentés.
- Le JWKS est récupéré depuis `{issuer}/jwks`. La détection automatiqueOIDC Discovery est une amélioration prévue.
- `Claims` intègre `jwt.RegisteredClaims` et ajoute`ClientID`, `Scope`, `AMR`, `ACR`, `OrgID`,`OrgSlug`.

Source: https://vonvon.id/fr/sdks/go/index.mdx