OAuth 2.0

Um guia completo para implementar Login e Registo usando o fluxo de Código de Autorização OAuth 2.0 da Deriv com PKCE.

Como o fluxo funciona

1. Gerar PKCE — Crie um code_verifier (string aleatória) e derive code_challenge = BASE64URL(SHA256(code_verifier)). Gere também um state aleatório para proteção CSRF.
2. Redirecionar para a Deriv — Envie o utilizador para o URL de autorização da Deriv com todos os parâmetros obrigatórios.
3. Utilizador autentica-se — A Deriv mostra o formulário de início de sessão ou de registo. Todos os ecrãs de início de sessão e consentimento são geridos pelo fornecedor OAuth.
4. Redirecionar de volta — A Deriv redireciona o utilizador para o seu redirect_uri com um código de autorização e state.
5. Verificar state — Confirme que o state devolvido corresponde ao que armazenou. Isto previne ataques CSRF.
6. Trocar código por token — O seu backend envia o código + code_verifier para o endpoint de token da Deriv e recebe um access_token.
7. Usar o token — Fazer chamadas de API autenticadas usando o token Bearer.

Antes de começar

Necessita de:

• Um cliente OAuth2 registado da Deriv com um client_id e um redirect_uri pré-registado.
• HTTPS ativado no seu URL de redirecionamento. Para desenvolvimento local, pode utilizar http://localhost.
• A sua app deve lidar com redirecionamentos, ler o código de autorização e trocá-lo por tokens.

Passo 1: Gerar parâmetros PKCE

Gerar PKCE em 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 pedido de autorização obrigatórios:

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

Passo 2: Redirecionar o utilizador para o endpoint de autorização

Envie os utilizadores para o endpoint de autorização OAuth 2.0 da Deriv:

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

Login

O login usa os parâmetros OAuth2 + PKCE padrão sem adições.

Parâmetros

Âmbitos de OAuth

O parâmetro scope é uma lista, separada por espaços, das permissões que a sua aplicação pede. Peça apenas os âmbitos de que a sua aplicação necessita.

URL de Login

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

Registe-se

O registo utiliza o mesmo URL base e parâmetros que o início de sessão, mais um parâmetro obrigatório adicional:

Parâmetro de registo obrigatório

Parâmetros de atribuição de parceiro opcionais

Os seguintes parâmetros são todos opcionais e geridos no painel Partners. Inclua-os para atribuir registos à sua conta de parceiro. O parâmetro de token de rastreamento tem quatro nomes equivalentes (t, affiliate_token, sidi, ca) — use aquele que aparece no seu link de referência ou painel Partners.

URL de Registo

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

Passo 3: Lidar com o callback

Quer o utilizador tenha iniciado sessão ou se tenha registado, o callback funciona exatamente da mesma forma. Após a autenticação, a Deriv redireciona para o seu redirect_uri:

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

Se algo correu mal:

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

A sua app deve:

1. Verificar o state — compare o state do URL com o valor que armazenou antes do redirecionamento. Se não corresponderem, aborte — pode ser um ataque CSRF.
2. Extrair o código — leia o parâmetro de query code.

Passo 4: Trocar código por tokens

Faça um pedido POST do seu backend para o endpoint de token. Nunca realize a troca de token a partir do navegador.

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

Corpo do pedido (codificado em formulário)

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

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

Resposta de token

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

expires_in é a duração do token em segundos. A resposta não inclui um token de atualização — consulte Duração e renovação do token.

Passo 5: Usar o token de acesso em chamadas de API

Inclua o token de acesso como um token Bearer no cabeçalho Authorization para todas as chamadas API:

Authorization: Bearer YOUR_ACCESS_TOKEN

Exemplo

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

Duração e renovação de tokens

Todos os tokens de acesso expiram. Consulte a respetiva duração em segundos em expires_in na resposta do token e, em seguida, guarde a hora de expiração (a hora em que recebeu o token mais expires_in) com o token. Não codifique uma duração fixa — esta pode mudar.

Para obter um novo token de acesso, encaminhe novamente o utilizador pelo fluxo de autorização (Authorization Code + PKCE) a partir do passo 1 quando:

• O número de segundos indicado em expires_in decorreu
• Uma chamada de API devolve 401

Se um novo token de acesso também receber um 401, não inicie novamente o fluxo. Em vez disso, verifique o Authorization cabeçalho e o endpoint.

Referência rápida

Resolução de Problemas

Lista de verificação de implementação

Login

• response_type é code
• client_id e redirect_uri estão registados na Deriv
• code_challenge e state são gerados de novo para cada pedido
• code_verifier é armazenado em sessionStorage antes do redirecionamento
• O callback verifica o state antes de trocar o código
• A troca de token acontece do lado do servidor (não no navegador)
• code_verifier é limpo do armazenamento após uso
• O fluxo de autorização é executado novamente quando o token expira ou uma chamada devolve 401, mas não quando um novo token de acesso também recebe um 401

Registo (adicional)

• prompt está definido para registration (obrigatório)
• Token de rastreamento (um de t, affiliate_token, sidi, ca) utm_source, utm_campaign, e utm_medium são definidos se necessário — use o nome do parâmetro mostrado na sua ligação de referência ou painel de Parceiros (opcional)