Kurz gesagt
OAuth 2.0 Scopes sind Berechtigungs-Strings, die definieren, was ein Access Token tun kann. Verwenden Sie das Format Ressource:Aktion wie pets:read oder orders:write. Fordern Sie Scopes während der Autorisierung an und validieren Sie diese an API-Endpunkten. Die moderne PetstoreAPI implementiert Scopes für Lese-/Schreibzugriff auf Haustiere, Bestellungen und Benutzerdaten.
Einleitung
Eine Drittanbieter-App möchte das Inventar Ihres Tiergeschäfts lesen. Sollte sie vollen Zugriff haben, um Bestellungen zu erstellen, Haustiere zu löschen und Benutzer zu verwalten? Nein. Sie sollte nur das Inventar lesen dürfen.
OAuth 2.0 Scopes lösen dies. Scopes definieren, welche Berechtigungen ein Access Token besitzt. Die App fordert den Scope inventory:read an. Ihre API validiert, ob das Token diesen Scope besitzt, bevor Daten zurückgegeben werden.
Die moderne PetstoreAPI implementiert granulare Scopes für alle Ressourcen: Haustiere, Bestellungen, Inventar und Benutzer.
Wenn Sie OAuth-APIs testen, hilft Ihnen Apidog bei der Prüfung der Scope-Validierung und der Autorisierungs-Workflows.
Was sind OAuth 2.0 Scopes?
Scopes sind Berechtigungs-Strings, die in OAuth Access Tokens enthalten sind.
Scope-Format
pets:read - Haustierdaten lesen
pets:write - Haustiere erstellen/aktualisieren
orders:read - Bestellungen lesen
orders:write - Bestellungen erstellen
admin:all - Voller Admin-Zugriff
Scope im OAuth-Workflow
1. Autorisierungsanfrage:
GET /oauth/authorize?
client_id=app123&
scope=pets:read orders:read&
redirect_uri=https://app.com/callback
2. Benutzerzustimmung:
App "PetFinder" möchte:
- Ihre Haustiere lesen
- Ihre Bestellungen lesen
[Zulassen] [Ablehnen]
3. Access Token:
{
"access_token": "eyJhbGc...",
"scope": "pets:read orders:read",
"expires_in": 3600
}
4. API-Anfrage:
GET /v1/pets
Authorization: Bearer eyJhbGc...
200 OK (Scope validiert)
Wie Scopes funktionieren
Token enthält Scopes
Access Token enthält gewährte Scopes:
// Decoded JWT
{
"sub": "user-456",
"scope": "pets:read orders:read",
"exp": 1710331200
}
API validiert 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();
};
}
Scopes gestalten
Namenskonventionen für Scopes
Ressource:Aktion-Muster:
pets:read
pets:write
orders:read
orders:write
users:read
users:write
Granulare Scopes:
pets:read
pets:create
pets:update
pets:delete
Wildcard-Scopes:
pets:* - Alle Haustieroperationen
*:read - Alle Ressourcen lesen
admin:* - Voller Admin-Zugriff
Scope-Hierarchie
admin:all
├── pets:*
│ ├── pets:read
│ ├── pets:write
│ └── pets:delete
├── orders:*
│ ├── orders:read
│ └── orders:write
└── users:*
├── users:read
└── users:write
Implementierung der Scope-Validierung
Middleware-Ansatz
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();
};
}
// Verwendung
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);
Decorator-Ansatz (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);
};
};
}
// Verwendung
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);
}
}
Wie die moderne PetstoreAPI Scopes verwendet
Verfügbare Scopes
pets:read - Haustierdaten lesen
pets:write - Haustiere erstellen/aktualisieren
pets:delete - Haustiere löschen
orders:read - Bestellungen lesen
orders:write - Bestellungen erstellen
inventory:read - Inventar lesen
inventory:write - Inventar aktualisieren
users:read - Benutzerprofil lesen
users:write - Benutzerprofil aktualisieren
admin:all - Voller Zugriff
Scope-Validierung
GET /v1/pets
Authorization: Bearer token_with_pets:read
200 OK
POST /v1/pets
Authorization: Bearer token_with_pets:read
403 Verboten
{
"error": "insufficient_scope",
"required": ["pets:write"],
"provided": ["pets:read"]
}
Siehe die Modern PetstoreAPI OAuth Dokumentation.
Scopes mit Apidog testen
Apidog unterstützt OAuth Scope-Tests:
- OAuth 2.0 Authentifizierung konfigurieren
- Spezifische Scopes anfordern
- Endpunkte mit verschiedenen Scopes testen
- 403-Antworten bei unzureichenden Scopes validieren
Best Practices
1. Granulare Scopes verwenden - pets:read statt read_all
2. Namenskonventionen beachten - Format Ressource:Aktion
3. Alle Scopes dokumentieren - In der API-Dokumentation auflisten
4. Bei jeder Anfrage validieren - Dem Client nicht vertrauen
5. Klare Fehlermeldungen zurückgeben - Erforderliche vs. bereitgestellte Scopes anzeigen
6. Prinzip der geringsten Berechtigung anwenden - Nur die minimal benötigten Scopes anfordern
Fazit
OAuth 2.0 Scopes ermöglichen eine granulare Zugriffssteuerung. Verwenden Sie das Format Ressource:Aktion, validieren Sie bei jeder Anfrage und dokumentieren Sie alle Scopes. Die moderne PetstoreAPI demonstriert eine produktionsreife Scope-Implementierung.
FAQ
Was ist der Unterschied zwischen Scopes und Rollen?
Scopes sind Berechtigungen für Access Tokens. Rollen sind Benutzergruppen mit zugewiesenen Berechtigungen.
Kann man mehrere Scopes haben?
Ja, durch Leerzeichen getrennt: pets:read orders:read users:write
Wie entzieht man Scopes?
Entziehen Sie das Access Token oder stellen Sie ein neues Token mit anderen Scopes aus.
Sollten Scopes im JWT sein?
Ja, zur zustandslosen Validierung im scope-Claim enthalten.
Wie granular sollten Scopes sein?
Balancieren Sie Granularität mit Benutzerfreundlichkeit. pets:read und pets:write ist in der Regel ausreichend.