Kısaca
OAuth 2.0 kapsamları (scopes), bir erişim token'ının ne yapabileceğini tanımlayan izin dizeleridir. pets:read veya orders:write gibi kaynak:eylem formatını kullanın. Yetkilendirme sırasında kapsamları isteyin, API uç noktalarında doğrulayın. Modern PetstoreAPI, evcil hayvanlara, siparişlere ve kullanıcı verilerine okuma/yazma erişimi için kapsamlar uygular.
Giriş
Üçüncü taraf bir uygulama, evcil hayvan mağazanızın envanterini okumak istiyor. Sipariş oluşturma, evcil hayvan silme ve kullanıcıları yönetme gibi tam erişime sahip olmalı mı? Hayır. Yalnızca envanteri okumalıdır.
OAuth 2.0 kapsamları bunu çözer. Kapsamlar, bir erişim token'ının hangi izinlere sahip olduğunu tanımlar. Uygulama inventory:read kapsamını ister. API'niz, veriyi döndürmeden önce token'ın bu kapsama sahip olduğunu doğrular.
Modern PetstoreAPI, tüm kaynaklar için (evcil hayvanlar, siparişler, envanter ve kullanıcılar) ayrıntılı kapsamlar uygular.
OAuth API'lerini test ediyorsanız, Apidog kapsam doğrulama ve yetkilendirme akışlarını test etmenize yardımcı olur.
OAuth 2.0 Kapsamları Nelerdir?
Kapsamlar, OAuth erişim token'larına dahil edilen izin dizeleridir.
Kapsam Formatı
pets:read - Evcil hayvan verilerini oku
pets:write - Evcil hayvan oluştur/güncelle
orders:read - Siparişleri oku
orders:write - Sipariş oluştur
admin:all - Tam yönetici erişimi
OAuth Akışında Kapsam
1. Yetkilendirme İsteği:
GET /oauth/authorize?
client_id=app123&
scope=pets:read orders:read&
redirect_uri=https://app.com/callback
2. Kullanıcı Onayı:
"PetFinder" uygulaması şunları istiyor:
- Evcil hayvanlarınızı okuma
- Siparişlerinizi okuma
[İzin Ver] [Reddet]
3. Erişim Token'ı:
{
"access_token": "eyJhbGc...",
"scope": "pets:read orders:read",
"expires_in": 3600
}
4. API İsteği:
GET /v1/pets
Authorization: Bearer eyJhbGc...
200 OK (kapsam doğrulandı)
Kapsamlar Nasıl Çalışır?
Token Kapsamları İçerir
Erişim token'ı verilen kapsamları içerir:
// Çözülmüş JWT
{
"sub": "user-456",
"scope": "pets:read orders:read",
"exp": 1710331200
}
API Kapsamları Doğrular
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: `Gereken kapsam: ${requiredScope}`
});
}
next();
};
}
Kapsam Tasarımı
Kapsam Adlandırma Kuralları
Kaynak:Eylem Deseni:
pets:read
pets:write
orders:read
orders:write
users:read
users:write
Ayrıntılı Kapsamlar:
pets:read
pets:create
pets:update
pets:delete
Joker Kapsamlar:
pets:* - Tüm evcil hayvan işlemleri
*:read - Tüm kaynakları oku
admin:* - Tam yönetici erişimi
Kapsam Hiyerarşisi
admin:all
├── pets:*
│ ├── pets:read
│ ├── pets:write
│ └── pets:delete
├── orders:*
│ ├── orders:read
│ └── orders:write
└── users:*
├── users:read
└── users:write
Kapsam Doğrulamayı Uygulama
Middleware Yaklaşımı
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();
};
}
// Kullanım
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 Yaklaşımı (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);
};
};
}
// Kullanım
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);
}
}
Modern PetstoreAPI Kapsamları Nasıl Kullanır?
Mevcut Kapsamlar
pets:read - Evcil hayvan verilerini oku
pets:write - Evcil hayvan oluştur/güncelle
pets:delete - Evcil hayvan sil
orders:read - Siparişleri oku
orders:write - Sipariş oluştur
inventory:read - Envanteri oku
inventory:write - Envanteri güncelle
users:read - Kullanıcı profilini oku
users:write - Kullanıcı profilini güncelle
admin:all - Tam erişim
Kapsam Doğrulama
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"]
}
Modern PetstoreAPI OAuth dokümantasyonuna bakın.
Apidog ile Kapsamları Test Etme
Apidog OAuth kapsam testini destekler:
- OAuth 2.0 kimlik doğrulamasını yapılandırın
- Belirli kapsamları isteyin
- Farklı kapsamlarla uç noktaları test edin
- Yetersiz kapsamlar için 403 yanıtlarını doğrulayın
En İyi Uygulamalar
1. Ayrıntılı kapsamlar kullanın - read_all yerine pets:read
2. Adlandırma kurallarına uyun - kaynak:eylem formatı
3. Tüm kapsamları belgeleyin - API dokümantasyonunda listeleyin
4. Her istekte doğrulama yapın - İstemciye güvenmeyin
5. Açık hatalar döndürün - İstenen ve sağlanan kapsamları gösterin
6. En az ayrıcalık ilkesini kullanın - Gereken minimum kapsamları isteyin
Sonuç
OAuth 2.0 kapsamları, ayrıntılı erişim kontrolü sağlar. kaynak:eylem formatını kullanın, her istekte doğrulayın ve tüm kapsamları belgeleyin. Modern PetstoreAPI, üretime hazır kapsam uygulamasını gösterir.
Sıkça Sorulan Sorular
Kapsamlar ve roller arasındaki fark nedir?
Kapsamlar, erişim token'ları için izinlerdir. Roller ise atanan izinlere sahip kullanıcı gruplarıdır.
Birden fazla kapsama sahip olabilir misiniz?
Evet, boşluklarla ayırın: pets:read orders:read users:write
Kapsamları nasıl iptal edersiniz?
Erişim token'ını iptal edin veya farklı kapsamlarla yeni bir token verin.
Kapsamlar JWT içinde olmalı mı?
Evet, durum bilgisiz doğrulama için scope talebine (claim) dahil edin.
Kapsamlar ne kadar ayrıntılı olmalı?
Ayrıntı düzeyi ile kullanılabilirlik arasında denge kurun. Genellikle pets:read ve pets:write yeterlidir.