Authentification OAuth

En bref

Ontologie prend en charge le protocole OAuth2 avec PKCE (Proof Key for Code Exchange) pour les applications qui necessitent une authentification au nom d'un utilisateur. Ce flux est recommande pour les applications frontend et mobiles.

Quand utiliser OAuth ?

Methode	Cas d'usage
Cle API	Scripts, automatisations, integrations serveur a serveur
OAuth2 PKCE	Applications frontend, applications mobiles, integrations qui agissent au nom d'un utilisateur

OAuth est necessaire lorsque :

• Votre application doit acceder aux donnees d'un utilisateur specifique
• Vous ne pouvez pas stocker de secret cote client (application frontend)
• Vous souhaitez que l'utilisateur autorise explicitement l'acces

Flux OAuth2 PKCE

Etape 1 : Generer le code verifier et le challenge

Votre application genere un code_verifier aleatoire et calcule le code_challenge correspondant :

// Generer un code verifier aleatoire
function generateCodeVerifier(): string {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return btoa(String.fromCharCode(...array))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

// Calculer le code challenge (SHA-256)
async function generateCodeChallenge(verifier: string): Promise<string> {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return btoa(String.fromCharCode(...new Uint8Array(hash)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

Etape 2 : Rediriger l'utilisateur

Redirigez l'utilisateur vers la page d'autorisation :

https://auth.ontologie-growthsystemes.com/authorize?
  response_type=code
  &client_id=VOTRE_CLIENT_ID
  &redirect_uri=https://votre-app.com/callback
  &scope=read:nodes write:nodes
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_STATE

Parametre	Description
client_id	Identifiant de votre application (obtenu lors de l'enregistrement)
redirect_uri	URL de retour apres autorisation (doit correspondre a celle enregistree)
scope	Permissions demandees, separees par des espaces
code_challenge	Hash SHA-256 du code verifier
state	Valeur aleatoire pour proteger contre les attaques CSRF

Etape 3 : Echanger le code contre un token

Apres autorisation, l'utilisateur est redirige vers votre redirect_uri avec un code :

const response = await fetch('https://auth.ontologie-growthsystemes.com/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: 'CODE_RECU',
    redirect_uri: 'https://votre-app.com/callback',
    client_id: 'VOTRE_CLIENT_ID',
    code_verifier: 'CODE_VERIFIER_ORIGINAL',
  }),
});

const { access_token, refresh_token, expires_in } = await response.json();

Etape 4 : Utiliser le token

Incluez le token dans vos requetes API :

curl -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "x-workspace-id: WORKSPACE_ID" \
     "https://api.ontologie-growthsystemes.com/api/queries/nodes"

Etape 5 : Rafraichir le token

Lorsque le token expire, utilisez le refresh token :

const response = await fetch('https://auth.ontologie-growthsystemes.com/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'refresh_token',
    refresh_token: 'VOTRE_REFRESH_TOKEN',
    client_id: 'VOTRE_CLIENT_ID',
  }),
});

Scopes OAuth

Les scopes disponibles sont identiques a ceux des cles API :

Scope	Description
read:nodes	Lire les entites
write:nodes	Creer et modifier les entites
read:edges	Lire les relations
write:edges	Creer et modifier les relations
read:livedata	Lire les sources Live Data
write:livedata	Gerer les sources Live Data

Pour la liste complete, consultez Permissions.

Securite

Pratique	Description
Stockez les tokens de maniere securisee	Utilisez le stockage securise du navigateur (pas le localStorage)
Validez le parametre state	Comparez le state retourne avec celui envoye
Utilisez toujours PKCE	Ne transmettez jamais le code verifier dans l'URL
Duree de vie des tokens	Access token : 1 heure. Refresh token : 30 jours
Revocation	Revoquez les tokens via l'endpoint /revoke lorsqu'un utilisateur se deconnecte

Avec le SDK

Le package @ontologie/oauth simplifie le flux OAuth :

import { createOAuthClient } from '@ontologie/oauth';

const oauth = createOAuthClient({
  clientId: 'VOTRE_CLIENT_ID',
  redirectUri: 'https://votre-app.com/callback',
  scopes: ['read:nodes', 'write:nodes'],
});

// Demarrer le flux
const authUrl = await oauth.getAuthorizationUrl();
window.location.href = authUrl;

// Callback : echanger le code
const tokens = await oauth.handleCallback(window.location.search);

Voir aussi

• Cles API — Authentification par cle
• Permissions — Reference des scopes
• SDK — Clients TypeScript et Python
• Limites et quotas — Rate limits

Besoin d'aide ?

Ecrivez-nous : Support et contact.