En bref
Les scopes OAuth 2.0 sont des chaînes de permission qui définissent ce qu'un jeton d'accès peut faire. Utilisez le format ressource:action comme pets:read (lire les animaux) ou orders:write (écrire les commandes). Demandez les scopes lors de l'autorisation, validez-les sur les points de terminaison de l'API. Modern PetstoreAPI implémente des scopes pour l'accès en lecture/écriture aux animaux, aux commandes et aux données utilisateur.
Introduction
Une application tierce souhaite lire l'inventaire de votre animalerie. Devrait-elle avoir un accès complet pour créer des commandes, supprimer des animaux et gérer les utilisateurs ? Non. Elle ne devrait lire que l'inventaire.
Les scopes OAuth 2.0 résolvent ce problème. Les scopes définissent les permissions qu'un jeton d'accès possède. L'application demande le scope inventory:read. Votre API valide que le jeton possède ce scope avant de renvoyer les données.
Modern PetstoreAPI implémente des scopes granulaires pour toutes les ressources : animaux, commandes, inventaire et utilisateurs.
Si vous testez des API OAuth, Apidog vous aide à tester la validation des scopes et les flux d'autorisation.
Que sont les scopes OAuth 2.0 ?
Les scopes sont des chaînes de permission incluses dans les jetons d'accès OAuth.
Format des scopes
pets:read - Lire les données des animaux
pets:write - Créer/mettre à jour les animaux
orders:read - Lire les commandes
orders:write - Créer les commandes
admin:all - Accès administrateur complet
Scope dans le flux OAuth
1. Requête d'autorisation :
GET /oauth/authorize?
client_id=app123&
scope=pets:read orders:read&
redirect_uri=https://app.com/callback
2. Consentement de l'utilisateur :
L'application "PetFinder" souhaite :
- Lire vos animaux
- Lire vos commandes
[Autoriser] [Refuser]
3. Jeton d'accès :
{
"access_token": "eyJhbGc...",
"scope": "pets:read orders:read",
"expires_in": 3600
}
4. Requête API :
GET /v1/pets
Authorization: Bearer eyJhbGc...
200 OK (scope validé)
Comment fonctionnent les scopes
Le jeton contient les scopes
Le jeton d'accès inclut les scopes accordés :
// JWT décodé
{
"sub": "user-456",
"scope": "pets:read orders:read",
"exp": 1710331200
}
L'API valide les scopes
app.get('/v1/pets', requireScope('pets:read'), async (req, res) => {
const pets = await getPets();
res.json(pets);
});
app.post('/v1/pets', requireScope('pets:write'), async (req, res) => {
const pet = await createPet(req.body);
res.status(201).json(pet);
});
function requireScope(requiredScope) {
return (req, res, next) => {
const token = extractToken(req);
const decoded = verifyToken(token);
if (!decoded.scope.includes(requiredScope)) {
return res.status(403).json({
error: 'insufficient_scope',
message: `Requires scope: ${requiredScope}`
});
}
next();
};
}
Concevoir des scopes
Conventions de nommage des scopes
Modèle Ressource:Action :
pets:read
pets:write
orders:read
orders:write
users:read
users:write
Scopes granulaires :
pets:read
pets:create
pets:update
pets:delete
Scopes génériques (wildcard) :
pets:* - Toutes les opérations sur les animaux
*:read - Lire toutes les ressources
admin:* - Accès administrateur complet
Hiérarchie des scopes
admin:all
├── pets:*
│ ├── pets:read
│ ├── pets:write
│ └── pets:delete
├── orders:*
│ ├── orders:read
│ └── orders:write
└── users:*
├── users:read
└── users:write
Implémenter la validation des scopes
Approche par middleware
function requireScopes(...requiredScopes) {
return (req, res, next) => {
const token = extractToken(req);
const decoded = verifyToken(token);
const tokenScopes = decoded.scope.split(' ');
const hasAllScopes = requiredScopes.every(scope =>
tokenScopes.includes(scope) || tokenScopes.includes('admin:all')
);
if (!hasAllScopes) {
return res.status(403).json({
error: 'insufficient_scope',
required: requiredScopes,
provided: tokenScopes
});
}
req.user = decoded;
next();
};
}
// Utilisation
app.get('/v1/pets', requireScopes('pets:read'), getPets);
app.post('/v1/pets', requireScopes('pets:write'), createPet);
app.delete('/v1/pets/:id', requireScopes('pets:delete'), deletePet);
Approche par décorateur (TypeScript)
function RequireScopes(...scopes: string[]) {
return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
const originalMethod = descriptor.value;
descriptor.value = async function (...args: any[]) {
const req = args[0];
const res = args[1];
const token = extractToken(req);
const decoded = verifyToken(token);
if (!hasScopes(decoded.scope, scopes)) {
return res.status(403).json({ error: 'insufficient_scope' });
}
return originalMethod.apply(this, args);
};
};
}
// Utilisation
class PetsController {
@RequireScopes('pets:read')
async getPets(req, res) {
const pets = await this.petService.findAll();
res.json(pets);
}
@RequireScopes('pets:write')
async createPet(req, res) {
const pet = await this.petService.create(req.body);
res.status(201).json(pet);
}
}
Comment Modern PetstoreAPI utilise les scopes
Scopes disponibles
pets:read - Lire les données des animaux
pets:write - Créer/mettre à jour les animaux
pets:delete - Supprimer les animaux
orders:read - Lire les commandes
orders:write - Créer les commandes
inventory:read - Lire l'inventaire
inventory:write - Mettre à jour l'inventaire
users:read - Lire le profil utilisateur
users:write - Mettre à jour le profil utilisateur
admin:all - Accès complet
Validation des scopes
GET /v1/pets
Authorization: Bearer token_with_pets:read
200 OK
POST /v1/pets
Authorization: Bearer token_with_pets:read
403 Forbidden
{
"error": "insufficient_scope",
"required": ["pets:write"],
"provided": ["pets:read"]
}
Voir la documentation OAuth de Modern PetstoreAPI.
Tester les scopes avec Apidog
Apidog prend en charge le test des scopes OAuth :
- Configurez l'authentification OAuth 2.0
- Demandez des scopes spécifiques
- Testez les points de terminaison avec différents scopes
- Validez les réponses 403 pour les scopes insuffisants
Bonnes pratiques
1. Utilisez des scopes granulaires - pets:read et non read_all
2. Suivez les conventions de nommage - format ressource:action
3. Documentez tous les scopes - Listez-les dans la documentation de l'API
4. Validez à chaque requête - Ne faites pas confiance au client
5. Retournez des erreurs claires - Montrez les scopes requis et fournis
6. Utilisez le principe du moindre privilège - Demandez le minimum de scopes nécessaires
Conclusion
Les scopes OAuth 2.0 offrent un contrôle d'accès granulaire. Utilisez le format ressource:action, validez à chaque requête et documentez tous les scopes. Modern PetstoreAPI démontre une implémentation de scope prête pour la production.
FAQ
Quelle est la différence entre les scopes et les rôles ?
Les scopes sont des permissions pour les jetons d'accès. Les rôles sont des groupes d'utilisateurs avec des permissions assignées.
Pouvez-vous avoir plusieurs scopes ?
Oui, séparez-les par des espaces : pets:read orders:read users:write
Comment révoquer les scopes ?
Révoquez le jeton d'accès ou émettez un nouveau jeton avec des scopes différents.
Les scopes doivent-ils être dans le JWT ?
Oui, incluez-les dans la revendication scope pour une validation stateless.
Quelle doit être la granularité des scopes ?
Équilibrez la granularité et la facilité d'utilisation. pets:read et pets:write sont généralement suffisants.