---
title: "sdk/ruby"
description: "SDK serveur Ruby pour la vérification JWT sans réseau, l'authentificationdes requêtes Rack/Rails 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/ruby

## 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

```ruby
# Gemfile
gem "vonvon", path: "../vonvon/sdk/ruby"

bundle install
```

## Démarrage rapide

```ruby
require "vonvon"

Vonvon.configure do |c|
  c.issuer         = "https://vonvon.id"
  c.audience       = "your_client_id"
  c.webhook_secret = "whsec_AbCdEf..."
end

# Verify a token
begin
  claims = Vonvon.verify_token(raw_token)
  puts claims.sub    # => "usr_abc123"
  puts claims.scope  # => "openid profile email"
rescue Vonvon::TokenVerificationError => e
  puts "Token invalid: #{e.message}"
end
```

## Authentifier une requête Rack/Rails

```ruby
# Sinatra before-filter
before do
  auth = Vonvon.authenticate_request(request)
  halt 401, "Unauthorized" unless auth.signed_in?
  @current_user_id = auth.claims.sub
end

# Explicit same-origin Core session -> JWT exchange
token = Vonvon.exchange_session_token(
  incoming_request_url: request.url,
  cookie_header: request.get_header("HTTP_COOKIE")
)
```

## Vérifier le webhook

```ruby
# Rails controller action
def receive
  raw_body = request.raw_post
  payload = Vonvon.verify_webhook(request.headers.to_h, raw_body)
  handle_event(payload["type"], payload["data"])
  head :ok
rescue Vonvon::WebhookVerificationError
  head :bad_request
end
```

## Configuration multi-émetteur

```ruby
config_a = Vonvon::Configuration.new
config_a.issuer   = "https://tenant-a.vonvon.id"
config_a.audience = "client_a"
client_a = Vonvon::Client.new(config_a)
claims = client_a.verify_token(token)
```

## Options de configuration

| Clé | Défaut | Description |
| --- | --- | --- |
| `issuer` | `https://vonvon.id` | URL d'émetteur OIDC |
| `audience` | `nil` | Revendication aud attendue ; nil ignore la validation |
| `jwks_ttl` | `3600` | TTL du cache JWKS local en secondes |
| `leeway` | `60` | Tolérance au décalage d'horloge JWT en secondes |
| `webhook_secret` | `nil` | Secret de signature webhook avec le préfixe `whsec_` |
| `webhook_tolerance` | `300` | Fenêtre de relecture des webhooks en secondes |
| `cookie_name` | `disabled` | Nom du cookie JWT détenu par l'application ; désactivé sauf configuration explicite |

## Notes de plateforme

- Dépend du gem `jwt` (support ES256/RS256). Ruby 3.1+ requis.
- `Vonvon.authenticate_request` accepte à la fois un hash env Rack et unobjet `Request` Rack.
- Hiérarchie d'exceptions : `Vonvon::Error` -> `ConfigurationError`,`JwksError`, `TokenVerificationError`,`WebhookVerificationError`.

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