OAuth 2.0

Un guide complet pour implémenter la connexion et l'inscription en utilisant le flux OAuth 2.0 Authorization Code de Deriv avec PKCE.

Comment le flux fonctionne

1. Générer PKCE — Créez un code_verifier (chaîne aléatoire) et dérivez code_challenge = BASE64URL(SHA256(code_verifier)). Générez également un state aléatoire pour la protection CSRF.
2. Rediriger vers Deriv — Envoyez l'utilisateur à l'URL d'autorisation de Deriv avec tous les paramètres requis.
3. Authentification de l'utilisateur — Deriv affiche soit le formulaire de connexion, soit le formulaire d'inscription. Tous les écrans de connexion et de consentement sont gérés par le fournisseur OAuth.
4. Redirection retour — Deriv redirige l'utilisateur vers votre redirect_uri avec un code d'autorisation et un state.
5. Vérifier l'état — Confirmez que le state renvoyé correspond à ce que vous avez stocké. Cela empêche les attaques CSRF.
6. Échanger le code contre un token — Votre backend envoie le code + code_verifier au point de terminaison de token de Deriv et reçoit un access_token.
7. Utiliser le token — Effectuez des appels API authentifiés à l'aide du token Bearer.

Avant de commencer

Vous avez besoin de :

• Un client OAuth2 enregistré auprès de Deriv avec un client_id et un redirect_uri pré-enregistré.
• HTTPS activé sur votre URL de redirection. Pour le développement local, vous pouvez utiliser http://localhost.
• Votre application doit gérer les redirections, lire le code d'autorisation et l'échanger contre des tokens.

Étape 1 : Générer les paramètres PKCE

Génération de 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);

Paramètres de demande d'autorisation requis :

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

Étape 2 : Rediriger l'utilisateur vers le point de terminaison d'autorisation

Envoyer les utilisateurs au point de terminaison d'autorisation OAuth 2.0 de Deriv :

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

Connexion

La connexion utilise les paramètres OAuth2 + PKCE standard sans ajouts.

Paramètres

Portées OAuth

Le paramètre scope est une liste de permissions séparées par des espaces que votre application demande. Ne demandez que les portées dont votre application a besoin.

Les périmètres que vous sélectionnez pour votre application dans Applications enregistrées correspondent au maximum qu’elle peut demander. Ils ne sont pas automatiquement accordés à chaque connexion d’un utilisateur.

Chaque demande d’autorisation peut demander une partie ou l’ensemble de ces périmètres. L’écran de consentement n’affiche à l’utilisateur que les périmètres de cette demande, et le jeton d’accès que vous recevez y est limité.

Si une demande inclut un périmètre qui n’est pas sélectionné pour votre application, l’autorisation échoue avec une erreur invalid_scope.

URL de connexion

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

S'inscrire

L'inscription utilise la même URL de base et les mêmes paramètres que la connexion, plus un paramètre obligatoire supplémentaire :

Paramètre d'inscription requis

Paramètres d'attribution de partenaire facultatifs

Les paramètres suivants sont tous facultatifs et gérés dans le tableau de bord des Partenaires. Incluez-les pour attribuer les inscriptions à votre compte partenaire. Le paramètre de token de suivi a quatre noms équivalents (t, affiliate_token, sidi, ca) — utilisez celui qui apparaît dans votre lien de parrainage ou dans le tableau de bord des Partenaires.

URL d'inscription

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

Étape 3 : Gérer le callback

Que l'utilisateur se soit connecté ou inscrit, le callback fonctionne exactement de la même manière. Après authentification, Deriv redirige vers votre redirect_uri :

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

Si quelque chose s'est mal passé :

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

Votre application doit :

1. Vérifiez l'état — comparez le state de l'URL avec la valeur que vous avez stockée avant la redirection. S'ils ne correspondent pas, interrompez — il peut s'agir d'une attaque CSRF.
2. Extraire le code — lisez le paramètre de requête code.

Étape 4 : Échanger le code contre des tokens

Effectuez une demande POST depuis votre backend vers le point de terminaison de token. N'effectuez jamais l'échange de token depuis le navigateur.

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

Corps de la demande (form-encoded)

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

Exemple 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"

Réponse de token

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

expires_in correspond à la durée de vie du jeton en secondes. La réponse n'inclut pas de jeton d'actualisation — consultez Durée de vie et renouvellement des jetons.

Étape 5 : Utilisez le token d'accès dans les appels API

Incluez le token d'accès en tant que token Bearer dans l'en-tête Authorization pour tous les appels API :

Authorization: Bearer YOUR_ACCESS_TOKEN

Exemple

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

Durée de validité et renouvellement des tokens

Chaque jeton d’accès expire. Consultez sa durée de validité en secondes dans expires_in dans la réponse de jeton, puis enregistrez l’heure d’expiration (l’heure à laquelle vous avez reçu le jeton plus expires_in) avec le jeton. Ne codez pas une durée de validité en dur : elle peut changer.

Pour obtenir un nouveau jeton d’accès, faites à nouveau passer l’utilisateur par le flux d’autorisation (Authorization Code + PKCE) à partir de l’étape 1 lorsque :

• Le nombre de secondes indiqué dans expires_in s’est écoulé
• Un appel API renvoie 401

Si un nouveau token d’accès renvoie également 401, ne relancez pas le flux. Vérifiez plutôt l’en-tête Authorization et le point de terminaison.

Référence rapide

Dépannage

Liste de contrôle d'implémentation

Connexion

• response_type est code
• client_id et redirect_uri sont enregistrés auprès de Deriv
• code_challenge et state sont générés à nouveau pour chaque demande
• code_verifier est stocké dans sessionStorage avant la redirection
• Le callback vérifie le state avant d'échanger le code
• L'échange de token se fait côté serveur (pas dans le navigateur)
• code_verifier est effacé du stockage après utilisation
• Le flux d’autorisation s’exécute à nouveau lorsque le token expire ou qu’un appel renvoie 401, mais pas lorsqu’un nouveau token d’accès renvoie également 401

Inscription (supplémentaire)

• prompt est défini sur registration (requis)
• Token de suivi (l'un de t, affiliate_token, sidi, ca) utm_source, utm_campaign, et utm_medium sont définis si nécessaire — utilisez le nom du paramètre affiché dans votre lien de parrainage ou le tableau de bord Partners (facultatif)