Gestion des Tokens

Découvrez les tokens d'accès, les refresh tokens et la gestion du cycle de vie des tokens.

---

Types de Tokens

Access Token (Token d'Accès)

Propriété	Description
But	Autoriser les requêtes API
Format	JWT (JSON Web Token)
Durée de vie	1 heure (configurable)
Utilisation	Authorization: Bearer <token>

Refresh Token

Propriété	Description
But	Obtenir de nouveaux tokens d'accès
Format	Chaîne opaque
Durée de vie	30 jours (configurable)
Utilisation	Échange contre un nouveau token d'accès

ID Token

Propriété	Description
But	Contient les claims d'identité de l'utilisateur
Format	JWT
Durée de vie	Identique au token d'accès
Utilisation	Récupérer les informations utilisateur

---

Réponse Token

Quand vous échangez un code d'autorisation contre des tokens :

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200a1b2c3d4e5f6...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "scope": "openid profile email"
}

---

Claims de l'Access Token

Payload JWT décodé :

{
  "iss": "https://api.syauth.com/e/v1",
  "sub": "user-uuid",
  "aud": "votre-client-id",
  "exp": 1703123456,
  "iat": 1703119856,
  "scope": "openid profile email",
  "email": "[email protected]"
}

Claim	Description
iss	Émetteur du Token (SyAuth)
sub	Sujet (ID utilisateur)
aud	Audience (votre client ID)
exp	Timestamp d'expiration
iat	Timestamp d'émission (Issued at)
scope	Scopes accordés

---

Rafraîchir les Tokens

Les tokens d'accès ont une courte durée de vie (généralement 1 heure). Quand ils expirent, utilisez le refresh token pour en obtenir un nouveau.

SDK Next.js/Frontend

Le SDK gère automatiquement le rafraîchissement des tokens en arrière-plan avant que le token d'accès n'expire.

const { getAccessToken } = useSyAuth();

// Cette fonction garantit un token valide, en rafraîchissant si nécessaire
const token = await getAccessToken();

Manuel / API

Faites une requête POST vers l'endpoint de token :

curl -X POST https://api.syauth.com/e/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=VOTRE_REFRESH_TOKEN" \
  -d "client_id=VOTRE_CLIENT_ID" \
  -d "client_secret=VOTRE_CLIENT_SECRET" # Si utilisation d'un Client Confidentiel

Note : Si la Rotation de Token est activée, vous recevrez un nouveau refresh token dans la réponse. Vous devez utiliser le nouveau pour la prochaine requête.

Python

import requests

response = requests.post("https://api.syauth.com/e/v1/oauth/token", data={
    "grant_type": "refresh_token",
    "refresh_token": "VOTRE_REFRESH_TOKEN",
    "client_id": "VOTRE_CLIENT_ID",
    # "client_secret": "VOTRE_SECRET" # Optionnel
})
tokens = response.json()
print(tokens['access_token'])

---

Révocation de Token

Quand un utilisateur se déconnecte, vous devez révoquer ses tokens.

Manuel / API

curl -X POST https://api.syauth.com/e/v1/oauth/revoke \
  -d "token=TOKEN_A_REVOQUER" \
  -d "token_type_hint=access_token" \
  -d "client_id=VOTRE_CLIENT_ID"

SDK

Appeler logout() efface automatiquement les tokens du client.

---

Stockage de Token

Recommandé : Cookies HttpOnly

Le SDK stocke les tokens dans des cookies HttpOnly sécurisés :

Cookie	Flags
syauth_access_token	HttpOnly, Secure, SameSite=Lax
syauth_refresh_token	HttpOnly, Secure, SameSite=Lax

Non Recommandé : localStorage

Ne stockez jamais les tokens dans localStorage car :

• Accessible au JavaScript (vulnérable XSS)
• Persiste à travers les sessions du navigateur
• Pas de contrôle d'expiration

---

Validation de Token

Vous pouvez valider les tokens en appelant l'endpoint autorisé ou en vérifiant la signature JWT localement.

Validation Distante (Le plus simple)

Vérifiez simplement le token en l'utilisant pour récupérer les infos utilisateur. Si le token est invalide, cela retournera 401.

curl https://api.syauth.com/e/v1/oauth/userinfo \
  -H "Authorization: Bearer <access_token>"

Validation Locale (Node.js)

Pour de meilleures performances, validez la signature JWT localement en utilisant la clé publique.

import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';

const client = jwksClient({
  jwksUri: 'https://api.syauth.com/e/v1/.well-known/jwks.json'
});

function getKey(header, callback){
  client.getSigningKey(header.kid, function(err, key) {
    var signingKey = key.publicKey || key.rsaPublicKey;
    callback(null, signingKey);
  });
}

jwt.verify(token, getKey, {}, function(err, decoded) {
  console.log(decoded);
});

Validation Locale (Python)

import jwt
from jwt import PyJWKClient

url = "https://api.syauth.com/e/v1/.well-known/jwks.json"
jwks_client = PyJWKClient(url)
signing_key = jwks_client.get_signing_key_from_jwt(token)

data = jwt.decode(
    token,
    signing_key.key,
    algorithms=["RS256"],
    audience="VOTRE_CLIENT_ID",
    issuer="https://api.syauth.com/e/v1"
)

---

Gestion de l'Expiration des Tokens

Gestion Automatique SDK

Le SDK gère l'expiration automatiquement :

1. Surveille l'expiration du token
2. Rafraîchit 5 minutes avant l'expiration
3. Met à jour les tokens stockés de manière transparente
4. Ré-authentifie si le rafraîchissement échoue

Gestion Personnalisée

function MyComponent() {
  const { getAccessToken, isAuthenticated } = useSyAuth();
  
  const fetchData = async () => {
    // getAccessToken() retourne un token valide ou rafraîchit si nécessaire
    const token = await getAccessToken();
    
    const response = await fetch('/api/data', {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    
    return response.json();
  };
}

---

Considérations de Sécurité

Risque	Atténuation
Vol de token	Utilisez des cookies HttpOnly, expiration courte
Rejeu de token	Validez les claims audience et issuer
Abus de refresh token	Rotation de token à l'utilisation
Attaques XSS	N'exposez jamais les tokens au JavaScript

---

Prochaines Étapes

• Gestion de Session - Gérer les sessions utilisateur
• Sécurité des Tokens - Plongée approfondie dans la sécurité