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 redireccionamiento. Para el desarrollo local, puede utilizar http://localhost.
• 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.

Los scopes que seleccione para su aplicación en Aplicaciones registradas son el máximo que puede solicitar. No se otorgan automáticamente cada vez que un usuario inicia sesión.

Cada solicitud de autorización puede pedir algunos o todos esos scopes. La pantalla de consentimiento muestra al usuario solo los scopes de esa solicitud, y el token de acceso que recibe está limitado a ellos.

Si una solicitud incluye un scope que no está seleccionado para su aplicación, la autorización falla con un error invalid_scope.

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

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": 2592000,
  "token_type": "Bearer"
}

expires_in es la duración del token en segundos. La respuesta no incluye un token de actualización; consulte Duración y renovación del token.

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"

Duración y renovación del token

Todos los tokens de acceso vencen. Lea su duración en segundos desde expires_in en la respuesta del token y, luego, almacene la hora de vencimiento (la hora en que recibió el token más expires_in) junto con el token. No codifique una duración fija, ya que puede cambiar.

Para obtener un nuevo token de acceso, envíe al usuario nuevamente a través del flujo de autorización (Authorization Code + PKCE) desde el paso 1 cuando:

• El número de segundos indicado en expires_in ha transcurrido
• Una llamada a la API devuelve 401

Si un nuevo token de acceso también recibe un 401, no inicie el flujo de nuevo. En su lugar, revise el Authorization encabezado y el endpoint.

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
• El flujo de autorización se ejecuta de nuevo cuando el token vence o una llamada devuelve 401, pero no cuando un nuevo token de acceso también recibe un 401

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)