---
title: "sdk/ruby"
description: "SDK de servidor Ruby para verificación JWT sin llamadas de red, autenticación de solicitudes Rack/Rails y validación de firma de webhook."
locale: "es"
---

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

# sdk/ruby

## Estado

Implementado y verificado localmente. La verificación de ida y vuelta contra un IdP real (obtención de JWKS, firma/verificación de tokens contra una instancia Vonvon en producción) aún no se ha realizado y debe completarse antes del uso en producción.

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

La autenticación de solicitudes acepta solo Bearer de forma predeterminada. Una cookie JWT propiedad de la aplicación solo se lee cuando se configura su nombre exacto. La cookie opaca de Core \_\_Host-vonvon.rt.\* nunca se busca ni se verifica localmente; intercámbiala reenviando el header Cookie completo al POST /v1/sessions/token del mismo origen exacto, con las redirecciones desactivadas, y acepta solo una respuesta que contenga únicamente el campo token.

## Instalación

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

bundle install
```

## Inicio rápido

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

## Autenticar una solicitud 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")
)
```

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

## Configuración multi-emisor

```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)
```

## Opciones de configuración

| Clave | Por defecto | Descripción |
| --- | --- | --- |
| `issuer` | `https://vonvon.id` | URL del emisor OIDC |
| `audience` | `nil` | Claim aud esperado; nil omite la validación |
| `jwks_ttl` | `3600` | TTL del caché local de JWKS en segundos |
| `leeway` | `60` | Tolerancia de desfase de reloj JWT en segundos |
| `webhook_secret` | `nil` | Secreto de firma del webhook con prefijo `whsec_` |
| `webhook_tolerance` | `300` | Ventana de repetición del webhook en segundos |
| `cookie_name` | `disabled` | Nombre de cookie JWT propiedad de la aplicación; desactivado salvo configuración explícita |

## Notas de plataforma

- Requiere la gema `jwt` (soporte ES256/RS256). Se necesita Ruby 3.1+.
- `Vonvon.authenticate_request` acepta tanto un hash de entorno Rack como un objeto `Request` de Rack.
- Jerarquía de excepciones: `Vonvon::Error` -> `ConfigurationError`, `JwksError`, `TokenVerificationError`, `WebhookVerificationError`.

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