OAuth 2.0

Una guía completa para implementar Inicio de Sesión y Registro usando el flujo de Código de Autorización OAuth 2.0 de Deriv con PKCE.

Cómo funciona el flujo

1. Genere PKCE — Cree un code_verifier (cadena aleatoria) y derive code_challenge = BASE64URL(SHA256(code_verifier)). También genere un state aleatorio para protección CSRF.
2. Redirigir a Deriv — Envíe al usuario a la URL de autorización de Deriv con todos los parámetros requeridos.
3. El usuario se autentica — Deriv muestra el formulario de inicio de sesión o registro. Todas las pantallas de inicio de sesión y consentimiento son administradas por el proveedor de OAuth.
4. Redirigir de vuelta — Deriv redirige al usuario a su redirect_uri con un código de autorización y state.
5. Verifique el estado — Confirme que el state devuelto coincide con lo que almacenó. Esto previene ataques CSRF.
6. Intercambiar código por token — Su backend envía el código + code_verifier al endpoint de token de Deriv y recibe un access_token.
7. Use el token — Realice llamadas API autenticadas usando el token Bearer.

Antes de comenzar

Necesita:

• Un cliente OAuth2 registrado de Deriv con un client_id y un redirect_uri pre-registrado.
• HTTPS habilitado en su URL de redirección.
• Su aplicación debe manejar redirecciones, leer el código de autorización e intercambiarlo por tokens.

Paso 1: Generar parámetros PKCE

Generando PKCE en JavaScript

// 1. Generate a random code_verifier
const array = crypto.getRandomValues(new Uint8Array(64));
const codeVerifier = Array.from(array)
  .map(v => 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~'[v % 66])
  .join('');

// 2. Derive the code_challenge
const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier));
const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(hash)))
  .replace(/\+/g, '-')
  .replace(/\//g, '_')
  .replace(/=+$/, '');

// 3. Generate a random state for CSRF protection
const state = crypto.getRandomValues(new Uint8Array(16))
  .reduce((s, b) => s + b.toString(16).padStart(2, '0'), '');

// 4. Store code_verifier and state before redirecting
sessionStorage.setItem('pkce_code_verifier', codeVerifier);
sessionStorage.setItem('oauth_state', state);

Parámetros de solicitud de autorización obligatorios:

• response_type=code
• client_id
• redirect_uri
• scope
• state
• code_challenge + code_challenge_method=S256 (PKCE)

Paso 2: Redirija al usuario al endpoint de autorización

Envíe a los usuarios al endpoint de autorización OAuth 2.0 de Deriv:

https://auth.deriv.com/oauth2/auth

Iniciar sesión

El inicio de sesión usa los parámetros estándar OAuth2 + PKCE sin adiciones.

Parámetros

Alcances de OAuth

El parámetro de alcance es una lista separada por espacios de los permisos que solicita su aplicación. Solicite únicamente los alcances que su aplicación necesita.

URL de inicio de sesión

https://auth.deriv.com/oauth2/auth?
  response_type=code
  &client_id={YOUR_CLIENT_ID}          # e.g. app12345
  &redirect_uri={YOUR_REDIRECT_URI}    # e.g. https://yourapp.com/callback
  &scope=trade+account_manage
  &state={RANDOM_STATE}                # e.g. abc123random
  &code_challenge={PKCE_CHALLENGE}     # e.g. E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

URL de inicio de sesión con soporte de aplicación heredada

https://auth.deriv.com/oauth2/auth?
  response_type=code
  &client_id={YOUR_CLIENT_ID}
  &redirect_uri={YOUR_REDIRECT_URI}
  &scope=trade+account_manage
  &state={RANDOM_STATE}
  &code_challenge={PKCE_CHALLENGE}
  &code_challenge_method=S256
  &app_id={YOUR_LEGACY_APP_ID}      # V1 app ID from legacy-api.deriv.com

Crear cuenta

El registro usa la misma URL base y parámetros que el inicio de sesión, más un parámetro obligatorio adicional:

Parámetro de registro requerido

Parámetros opcionales de atribución de socios

Los siguientes parámetros son todos opcionales y se gestionan en el panel de Socios. Inclúyalos para atribuir registros a su cuenta de socio. El parámetro de token de seguimiento tiene cuatro nombres equivalentes (t, affiliate_token, sidi, ca) — use el que aparezca en su enlace de referido o en el panel de Socios.

URL de Crear Cuenta

https://auth.deriv.com/oauth2/auth?
  response_type=code
  &client_id={YOUR_CLIENT_ID}          # e.g. app12345
  &redirect_uri={YOUR_REDIRECT_URI}    # e.g. https://yourapp.com/callback
  &scope=trade+account_manage
  &state={RANDOM_STATE}                # e.g. abc123random
  &code_challenge={PKCE_CHALLENGE}     # e.g. E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &prompt=registration
  &t={YOUR_TRACKING_TOKEN}             # or: affiliate_token | sidi | ca — use the name from your referral link
  &utm_campaign={YOUR_CAMPAIGN}        # e.g. dynamicworks
  &utm_medium=affiliate
  &utm_source={YOUR_AFFILIATE_ID}      # e.g. CU303219

Paso 3: Maneje el callback

Ya sea que el usuario haya iniciado sesión o se haya registrado, el callback funciona exactamente de la misma manera. Después de la autenticación, Deriv redirige a su redirect_uri:

https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE

Si algo salió mal:

https://yourapp.com/callback?error=access_denied&error_description=User+cancelled

Su aplicación debe:

1. Verifique el estado — compare el state de la URL con el valor que almacenó antes de la redirección. Si no coinciden, aborte — puede ser un ataque CSRF.
2. Extraiga el código — lea el parámetro de consulta code.

Paso 4: Intercambiar código por tokens

Realice una solicitud POST desde su backend al endpoint de token. Nunca realice el intercambio de token desde el navegador.

POST https://auth.deriv.com/oauth2/token

Cuerpo de solicitud (codificado en formulario)

grant_type=authorization_code
client_id=YOUR_CLIENT_ID
code=AUTH_CODE_FROM_CALLBACK
code_verifier=YOUR_ORIGINAL_CODE_VERIFIER
redirect_uri=https://your-app.com/callback

ejemplo cURL

curl -X POST https://auth.deriv.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code=AUTH_CODE" \
  -d "code_verifier=YOUR_CODE_VERIFIER" \
  -d "redirect_uri=https://your-app.com/callback"

Respuesta de token

{
  "access_token": "ory_at_...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Paso 5: Use el token de acceso en llamadas API

Incluya el token de acceso como un token Bearer en el encabezado Authorization para todas las llamadas API:

Authorization: Bearer YOUR_ACCESS_TOKEN

Ejemplo

curl -X GET "https://api.derivws.com/trading/v1/options/accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Referencia rápida

Solución de problemas

Lista de verificación de implementación

Iniciar sesión

• response_type es code
• client_id y redirect_uri están registrados con Deriv
• code_challenge y state se generan nuevos para cada solicitud
• code_verifier se almacena en sessionStorage antes de redirigir
• El callback verifica state antes de intercambiar el código
• El intercambio de token ocurre del lado del servidor (no en el navegador)
• code_verifier se borra del almacenamiento después del uso
• Si mantiene una aplicación heredada, app_id se establece en su ID de aplicación Legacy (opcional)

Registro (adicional)

• prompt está establecido en registration (obligatorio)
• Token de seguimiento (uno de t, affiliate_token, sidi, ca) utm_source, utm_campaign y utm_medium se establecen si es necesario; use el nombre del parámetro que se muestra en su enlace de referencia o en el panel de Partners (opcional)