Les Tokens Expliqués

Auris utilise trois catégories de tokens : access tokens, refresh tokens et ID tokens. Comprendre ce que fait chaque token, ce qu’il contient et comment il doit être géré est essentiel pour construire des intégrations sécurisées.

Access Token

L’access token est la credential que ton application utilise pour appeler les API protégées. Il est de courte durée par conception — l’expiration par défaut est de 15 minutes.

Ce qu’il est

Un access token est un JWT signé (JSON Web Token). Il est auto-contenu : le resource server peut vérifier son authenticité en vérifiant la signature sans effectuer un appel réseau à Auris, en utilisant les clés publiques de l’endpoint JWKS.

Ce qu’il contient

Un payload décodé d’un access token Auris ressemble à ceci :


{
  "sub": "usr_abc123",
  "iss": "https://api.altovar.net",
  "aud": "votre-client-id",
  "iat": 1739880000,
  "exp": 1739880900,
  "jti": "tok_xyz789",
  "type": "user",
  "email": "[email protected]",
  "roles": ["editor", "viewer"],
  "scope": "openid profile email",
  "plan": "enterprise"
}

Claim	Description
`sub`	Subject — l’ID utilisateur (unique au sein du tenant)
`iss`	Issuer — l’URL de l’instance Auris
`aud`	Audience — le client ID de l’application
`iat`	Issued At — timestamp Unix quand le token a été émis
`exp`	Expiry — timestamp Unix quand le token expire
`jti`	JWT ID — identifiant unique pour ce token
`type`	`"user"` pour les utilisateurs réguliers, `"m2m"` pour les tokens client credentials
`email`	Adresse email de l’utilisateur
`roles`	Tableau des noms de rôles assignés à l’utilisateur
`scope`	Scopes accordés séparés par des espaces
Custom claims	Tous claims supplémentaires configurés via Custom Claims dans la Console

Comment l’utiliser

Envoie l’access token dans l’header Authorization à chaque requête vers une API protégée :


Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImtleS1pZC0xIn0...

Quand il expire

Les access tokens expirent après 15 minutes par défaut. Quand une API retourne 401 Unauthorized avec le code d’erreur TOKEN_EXPIRED, utilise le refresh token pour obtenir un nouvel access token. Les SDKs Auris gèrent cela automatiquement quand autoRefresh: true est configuré.

Refresh Token

Le refresh token permet à ton application d’obtenir de nouveaux access tokens sans demander à l’utilisateur de se reconnecter.

Ce qu’il est

Un refresh token est une chaîne opaque — il ne porte aucun claim et ne peut pas être décodé. C’est une valeur aléatoire qu’Auris stocke et valide en interne. Son opacité est intentionnelle : il doit être envoyé à Auris pour obtenir quelque chose d’utile.

Un refresh token ressemble à ceci :


rt_7fKp2mXa9qN3vB8yR4tL1wC6jD5sE0uH

Durée par défaut

Les refresh tokens expirent après 7 jours d’inactivité par défaut. Si l’utilisateur est actif, le token est rotaté à chaque utilisation et l’expiration se réinitialise. Les administrateurs du tenant peuvent configurer l’expiration dans la Console Auris sous Paramètres → Sécurité → Policy de Session.

Rotation

Auris utilise la rotation du refresh token : chaque fois que tu échanges un refresh token contre de nouveaux tokens, l’ancien refresh token est immédiatement invalidé et un nouveau est émis. Cela limite la fenêtre d’exposition si un refresh token est volé.


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_NOUVEAU_token_rotaté...",
    "expiresIn": 900
  }
}

Considérations de Sécurité

Stocke les refresh tokens dans des cookies httpOnly (non accessibles à JavaScript) quand c’est possible
Si tu les stockes en mémoire ou dans localStorage, accepte le compromis de risque XSS
N’inclus jamais les refresh tokens dans les URLs ou les fichiers de log
La courte durée de l’access token limite les dégâts s’il est intercepté — le refresh token est la credential de plus grande valeur

ID Token

L’ID token est un concept OIDC. Il est émis avec l’access token quand le scope openid est demandé.

Ce qu’il est

Un ID token est un JWT signé contenant les claims d’identité de l’utilisateur. Il est destiné à être consommé par l’application cliente — pas envoyé aux API. Les API doivent vérifier l’access token, pas l’ID token.

Ce qu’il contient


{
  "sub": "usr_abc123",
  "iss": "https://api.altovar.net",
  "aud": "votre-client-id",
  "iat": 1739880000,
  "exp": 1739883600,
  "email": "[email protected]",
  "email_verified": true,
  "name": "Alice Dupont",
  "given_name": "Alice",
  "family_name": "Dupont",
  "picture": "https://cdn.exemple.com/avatars/alice.jpg"
}

Quand l’utiliser

Afficher le nom et l’avatar de l’utilisateur dans ton UI sans un appel API supplémentaire
Vérifier l’identité de l’utilisateur dans une application server-side rendered
Passer le contexte utilisateur à des widgets tiers qui acceptent des tokens OIDC

N’utilise pas l’ID token pour autoriser les appels API.

Structure JWT

Tous les JWT (access tokens et ID tokens) partagent la même structure à trois parties, séparées par des points :


header.payload.signature

Chaque partie est encodée en Base64URL (Base64 URL-safe sans padding).

Header


{
  "alg": "RS256",
  "kid": "key-id-1",
  "typ": "JWT"
}

Champ	Description
`alg`	Algorithme de signature (`RS256` ou `HS256`)
`kid`	Key ID — identifie quelle clé publique utiliser pour la vérification (depuis JWKS)
`typ`	Type de token — toujours `JWT`

Signature

Pour RS256 : RSASHA256(base64url(header) + "." + base64url(payload), privateKey)

La signature garantit que le token n’a pas été altéré. N’importe qui peut décoder header et payload (ils sont juste du Base64), mais seul Auris (qui détient la clé privée) peut produire une signature valide.

Décoder un JWT ne le valide pas. Vérifie toujours la signature contre la clé publique avant de faire confiance aux claims. Utilise une bibliothèque JWT ou le SDK Auris — ne décode jamais les tokens manuellement en production sans vérification.

Algorithmes de Signature

Auris supporte deux algorithmes de signature, configurés via la variable d’environnement JWT_ALGORITHM :

RS256 (Recommandé)

RSA + SHA-256. Asymétrique — Auris signe avec une clé privée, les resource servers vérifient avec la clé publique. La clé publique est exposée via l’endpoint JWKS.

Avantages :

Les resource servers peuvent vérifier les tokens localement sans contacter Auris
La clé privée ne quitte jamais le serveur Auris
Support standard dans toutes les principales bibliothèques JWT

HS256

HMAC + SHA-256. Symétrique — le même secret est utilisé pour signer et vérifier. Auris et le resource server doivent tous deux connaître le secret partagé.

Auris supporte HS256 pour la compatibilité avec certaines intégrations legacy. RS256 est fortement préféré pour les nouveaux déploiements.

Vérification JWKS

Les resource servers vérifient les access tokens en récupérant les clés de signature depuis l’endpoint JWKS et en les utilisant pour valider la signature JWT localement.

Endpoint JWKS


GET /.well-known/jwks.json

Réponse


{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-1",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM...",
      "e": "AQAB"
    }
  ]
}

Étapes de Vérification

Décode l’header JWT (sans vérifier la signature) pour extraire le kid (key ID)
Récupère l’endpoint JWKS (ou utilise une version en cache — TTL recommandé : 1 heure)
Trouve la clé dans la réponse JWKS dont le kid correspond au kid de l’header
Utilise cette clé publique pour vérifier la signature JWT
Vérifie que exp est dans le futur, que iss correspond à ton domaine Auris, que aud correspond à ton client ID

La plupart des bibliothèques JWT gèrent les étapes 1 à 5 automatiquement quand une URL JWKS est fournie. Exemple avec la bibliothèque jose :


import { createRemoteJWKSet, jwtVerify } from 'jose'
 
const JWKS = createRemoteJWKSet(
  new URL('https://api.altovar.net/.well-known/jwks.json')
)
 
async function verifyToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: 'https://api.altovar.net',
    audience: 'votre-client-id',
  })
  return payload
}

Rotation des Clés

Auris fait pivoter périodiquement les clés de signature pour limiter l’impact d’une compromission de clé. Quand la rotation se produit :

Une nouvelle paire de clés RSA est générée et ajoutée à l’endpoint JWKS avec un nouveau kid
Les nouveaux tokens sont signés avec la nouvelle clé
Les anciens tokens (signés avec l’ancienne clé) continuent d’être valides car l’ancienne clé publique reste dans la réponse JWKS
L’ancienne clé n’est supprimée du JWKS qu’une fois que tous les tokens signés avec elle ont expiré

Cycle de Vie du Token


Login
  → Reçoit access token (15 min) + refresh token (7 jours) + ID token (1 heure)
  ↓
Utilise l'access token dans les appels API
  ↓
L'access token expire (401 TOKEN_EXPIRED)
  ↓
Échange le refresh token → nouvel access token + nouveau refresh token
  ↓
Continue à utiliser le nouvel access token
  ↓
L'utilisateur se déconnecte / le refresh token expire / le refresh token est révoqué
  ↓
L'utilisateur doit s'authentifier à nouveau

Bonnes Pratiques de Stockage

Applications Browser (SPA)

Stockage	Sécurité	Notes
Cookie `httpOnly`	Maximale	Non accessible à JavaScript — protège contre les attaques XSS
`sessionStorage`	Moyenne	Effacé à la fermeture de l’onglet. Vulnérable à XSS.
`localStorage`	Moyenne	Persiste entre les sessions. Vulnérable à XSS.
Fragment URL / query string	Minimale	Ne jamais faire — les tokens apparaissent dans l’historique du browser

Applications Côté Serveur

Stocke le refresh token dans la session côté serveur de l’utilisateur (chiffrée au repos). Émets des access tokens de courte durée à la demande et mets-les en cache en mémoire pour leur durée restante. Ne stocke jamais les access tokens dans la base de données.

Applications Mobile

Utilise le stockage sécurisé des credentials de la plateforme :

iOS : Keychain Services
Android : Android Keystore
React Native : react-native-keychain ou Expo SecureStore

Ne stocke jamais les tokens dans AsyncStorage sur mobile — ce n’est pas chiffré.

Le SDK React Auris (@auris/react) gère automatiquement le stockage des tokens. Sauf si tu implémentes une intégration personnalisée, tu n’as pas besoin de gérer toi-même le stockage des tokens.

Concepts Associés

OAuth 2.0 & OIDC — La couche protocolaire qui émet les tokens
Flux PKCE — Comment les tokens sont obtenus via Authorization Code + PKCE
Sessions & Rotation Token — Cycle de vie des sessions et rotation du refresh token
DPoP (Proof of Possession) — Liaison des tokens à des clés cryptographiques
Custom JWT Claims — Ajouter des claims personnalisés aux access tokens