En resumen (TL;DR)
Los ámbitos (scopes) de OAuth 2.0 son cadenas de permisos que definen lo que un token de acceso puede hacer. Utilice el formato recurso:acción como pets:read o orders:write. Solicite los ámbitos durante la autorización, y valídelos en los puntos finales de la API. La Modern PetstoreAPI implementa ámbitos para el acceso de lectura/escritura a mascotas, pedidos y datos de usuario.
Introducción
Una aplicación de terceros quiere leer el inventario de su tienda de mascotas. ¿Debería tener acceso completo para crear pedidos, eliminar mascotas y gestionar usuarios? No. Solo debería leer el inventario.
Los ámbitos de OAuth 2.0 resuelven esto. Los ámbitos definen qué permisos tiene un token de acceso. La aplicación solicita el ámbito inventory:read. Su API valida que el token tenga este ámbito antes de devolver los datos.
Modern PetstoreAPI implementa ámbitos granulares para todos los recursos: mascotas, pedidos, inventario y usuarios.
Si está probando APIs de OAuth, Apidog le ayuda a probar la validación de ámbitos y los flujos de autorización.
¿Qué son los ámbitos de OAuth 2.0?
Los ámbitos son cadenas de permisos incluidas en los tokens de acceso de OAuth.
Formato de ámbito
pets:read - Leer datos de mascotas
pets:write - Crear/actualizar mascotas
orders:read - Leer pedidos
orders:write - Crear pedidos
admin:all - Acceso de administrador completo
Ámbito en el flujo de OAuth
1. Solicitud de autorización:
GET /oauth/authorize?
client_id=app123&
scope=pets:read orders:read&
redirect_uri=https://app.com/callback
2. Consentimiento del usuario:
La aplicación "PetFinder" quiere:
- Leer tus mascotas
- Leer tus pedidos
[Permitir] [Denegar]
3. Token de acceso:
{
"access_token": "eyJhbGc...",
"scope": "pets:read orders:read",
"expires_in": 3600
}
4. Solicitud a la API:
GET /v1/pets
Authorization: Bearer eyJhbGc...
200 OK (ámbito validado)
Cómo funcionan los ámbitos
El token contiene ámbitos
El token de acceso incluye los ámbitos concedidos:
// JWT decodificado
{
"sub": "user-456",
"scope": "pets:read orders:read",
"exp": 1710331200
}
La API valida los ámbitos
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();
};
}
Diseño de ámbitos
Convenciones de nomenclatura de ámbitos
Patrón Recurso:Acción:
pets:read
pets:write
orders:read
orders:write
users:read
users:write
Ámbitos granulares:
pets:read
pets:create
pets:update
pets:delete
Ámbitos comodín:
pets:* - Todas las operaciones de mascotas
*:read - Leer todos los recursos
admin:* - Acceso de administrador completo
Jerarquía de ámbitos
admin:all
├── pets:*
│ ├── pets:read
│ ├── pets:write
│ └── pets:delete
├── orders:*
│ ├── orders:read
│ └── orders:write
└── users:*
├── users:read
└── users:write
Implementación de la validación de ámbitos
Enfoque con 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();
};
}
// Uso
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);
Enfoque con Decoradores (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);
};
};
}
// Uso
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);
}
}
Cómo la Modern PetstoreAPI usa los ámbitos
Ámbitos disponibles
pets:read - Leer datos de mascotas
pets:write - Crear/actualizar mascotas
pets:delete - Eliminar mascotas
orders:read - Leer pedidos
orders:write - Crear pedidos
inventory:read - Leer inventario
inventory:write - Actualizar inventario
users:read - Leer perfil de usuario
users:write - Actualizar perfil de usuario
admin:all - Acceso completo
Validación de ámbito
GET /v1/pets
Authorization: Bearer token_with_pets:read
200 OK
POST /v1/pets
Authorization: Bearer token_with_pets:read
403 Prohibido
{
"error": "insufficient_scope",
"required": ["pets:write"],
"provided": ["pets:read"]
}
Ver la documentación de OAuth de Modern PetstoreAPI.
Prueba de ámbitos con Apidog
Apidog soporta la prueba de ámbitos de OAuth:
- Configure la autenticación OAuth 2.0
- Solicite ámbitos específicos
- Pruebe puntos finales con diferentes ámbitos
- Valide las respuestas 403 para ámbitos insuficientes
Mejores prácticas
1. Use ámbitos granulares - pets:read no read_all
2. Siga las convenciones de nomenclatura - formato recurso:acción
3. Documente todos los ámbitos - Liste en la documentación de la API
4. Valide en cada solicitud - No confíe en el cliente
5. Devuelva errores claros - Muestre los ámbitos requeridos versus los proporcionados
6. Use el principio de menor privilegio - Solicite los ámbitos mínimos necesarios
Conclusión
Los ámbitos de OAuth 2.0 proporcionan un control de acceso granular. Utilice el formato recurso:acción, valide en cada solicitud y documente todos los ámbitos. Modern PetstoreAPI demuestra una implementación de ámbitos lista para producción.
Preguntas frecuentes
¿Cuál es la diferencia entre ámbitos y roles?
Los ámbitos son permisos para los tokens de acceso. Los roles son grupos de usuarios con permisos asignados.
¿Se pueden tener múltiples ámbitos?
Sí, sepárelos con espacios: pets:read orders:read users:write
¿Cómo se revocan los ámbitos?
Revoque el token de acceso o emita un nuevo token con diferentes ámbitos.
¿Deberían los ámbitos estar en el JWT?
Sí, inclúyalos en la afirmación scope para una validación sin estado.
¿Qué tan granulares deben ser los ámbitos?
Equilibre la granularidad con la usabilidad. pets:read y pets:write suelen ser suficientes.