Proteger una API
Valide los access tokens de la plataforma en su propia API, con ejemplos para Node.js, Python, Java, C#, Go, PHP y Rust.
Los demás quickstarts cubren el lado del cliente: una aplicación que obtiene tokens. Esta guía cubre el lado del servidor de recursos: su propia API validando los access tokens que emite la plataforma antes de atender una solicitud. Los ejemplos abarcan Node.js, Python, Java, C#, Go, PHP y Rust; las comprobaciones son las mismas en todos los lenguajes y frameworks.
Los access tokens emitidos para una API registrada son JWT firmados, así que su API los valida sin conexión frente a las claves de firma publicadas por la plataforma; no hace falta ninguna llamada a la plataforma por solicitud.
1. Registrar la API
En la Admin Console, en Integraciones → APIs, registre su API con un identificador (por ejemplo, https://api.example.com), defina sus scopes y autorice al menos a una aplicación a llamarla. Consulte APIs para el recorrido completo. Los clientes solicitan después tokens para su API pasando su identificador como resource indicator; el claim aud del token lo transporta.
2. Instalar las dependencias
npm install express josepip install fastapi uvicorn "pyjwt[crypto]"// build.gradle
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'dotnet add package Microsoft.AspNetCore.Authentication.JwtBearergo get github.com/golang-jwt/jwt/v5 github.com/MicahParks/keyfunc/v3composer require firebase/php-jwtcargo add axum jsonwebtoken serde_json
cargo add tokio --features full
cargo add reqwest --features json3. Validar el token
Compruebe cuatro cosas en cada solicitud, en este orden: la firma (frente al JWKS de la plataforma), el issuer, la audience (el identificador de su API) y la caducidad. Cada biblioteca hace las cuatro en una sola llamada:
import express from 'express';
import { createRemoteJWKSet, jwtVerify } from 'jose';
const ISSUER = 'https://<your-domain>'; // your instance's login domain
const AUDIENCE = 'https://api.example.com'; // your API's identifier
// Fetches and caches the platform's signing keys, and refreshes them on rotation.
const jwks = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks`));
async function requireAccessToken(req, res, next) {
const auth = req.headers.authorization ?? '';
const token = auth.startsWith('Bearer ') ? auth.slice(7) : null;
if (!token) {
return res.status(401).set('WWW-Authenticate', 'Bearer').end();
}
try {
const { payload } = await jwtVerify(token, jwks, {
issuer: ISSUER,
audience: AUDIENCE,
});
req.claims = payload; // sub, scope, client_id, ...
return next();
} catch {
return res.status(401).set('WWW-Authenticate', 'Bearer error="invalid_token"').end();
}
}import jwt
from fastapi import HTTPException, Request
from jwt import PyJWKClient
ISSUER = "https://<your-domain>" # your instance's login domain
AUDIENCE = "https://api.example.com" # your API's identifier
# Fetches and caches the platform's signing keys.
jwks = PyJWKClient(f"{ISSUER}/.well-known/jwks")
def require_access_token(request: Request) -> dict:
auth = request.headers.get("authorization", "")
if not auth.startswith("Bearer "):
raise HTTPException(401, headers={"WWW-Authenticate": "Bearer"})
token = auth[7:]
try:
key = jwks.get_signing_key_from_jwt(token).key
return jwt.decode( # sub, scope, client_id, ...
token, key,
algorithms=["RS256"], # the signing algorithm configured on your API
issuer=ISSUER,
audience=AUDIENCE,
)
except jwt.InvalidTokenError:
raise HTTPException(401, headers={"WWW-Authenticate": 'Bearer error="invalid_token"'})# application.yml. Spring Boot reads the discovery document and validates
# signature, issuer, audience, and expiry against the platform's JWKS.
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://<your-domain> # your instance's login domain
audiences: https://api.example.com # your API's identifierusing Microsoft.AspNetCore.Authentication.JwtBearer;
var builder = WebApplication.CreateBuilder(args);
const string Issuer = "https://<your-domain>"; // your instance's login domain
const string Audience = "https://api.example.com"; // your API's identifier
builder.Services
.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer(options =>
{
// Reads the discovery document, then fetches and caches the signing keys.
options.Authority = Issuer;
options.Audience = Audience;
options.MapInboundClaims = false; // keep the raw claim names (sub, scope, ...)
});import (
"net/http"
"strings"
"github.com/MicahParks/keyfunc/v3"
"github.com/golang-jwt/jwt/v5"
)
const issuer = "https://<your-domain>" // your instance's login domain
const audience = "https://api.example.com" // your API's identifier
// Fetches and caches the platform's signing keys.
var jwks, _ = keyfunc.NewDefault([]string{issuer + "/.well-known/jwks"})
func requireAccessToken(w http.ResponseWriter, r *http.Request) (jwt.MapClaims, bool) {
auth := r.Header.Get("Authorization")
if !strings.HasPrefix(auth, "Bearer ") {
w.Header().Set("WWW-Authenticate", "Bearer")
w.WriteHeader(http.StatusUnauthorized)
return nil, false
}
claims := jwt.MapClaims{}
_, err := jwt.ParseWithClaims(strings.TrimPrefix(auth, "Bearer "), claims, jwks.Keyfunc,
jwt.WithValidMethods([]string{"RS256"}), // the signing algorithm configured on your API
jwt.WithIssuer(issuer),
jwt.WithAudience(audience),
jwt.WithExpirationRequired(),
)
if err != nil {
w.Header().Set("WWW-Authenticate", `Bearer error="invalid_token"`)
w.WriteHeader(http.StatusUnauthorized)
return nil, false
}
return claims, true // sub, scope, client_id, ...
}use Firebase\JWT\JWK;
use Firebase\JWT\JWT;
const ISSUER = 'https://<your-domain>'; // your instance's login domain
const AUDIENCE = 'https://api.example.com'; // your API's identifier
function requireAccessToken(): array {
$auth = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
if (!str_starts_with($auth, 'Bearer ')) {
header('WWW-Authenticate: Bearer');
http_response_code(401);
exit;
}
try {
// Cache the JWKS between requests (APCu, Redis, ...) instead of re-fetching.
$jwks = json_decode(file_get_contents(ISSUER . '/.well-known/jwks'), true);
$claims = (array) JWT::decode(substr($auth, 7), JWK::parseKeySet($jwks, 'RS256'));
if (($claims['iss'] ?? '') !== ISSUER || ($claims['aud'] ?? '') !== AUDIENCE) {
throw new UnexpectedValueException('wrong issuer or audience');
}
return $claims; // sub, scope, client_id, ...
} catch (Exception $e) {
header('WWW-Authenticate: Bearer error="invalid_token"');
http_response_code(401);
exit;
}
}use axum::http::{HeaderMap, StatusCode};
use jsonwebtoken::{decode, decode_header, jwk::JwkSet, Algorithm, DecodingKey, Validation};
use serde_json::Value;
const ISSUER: &str = "https://<your-domain>"; // your instance's login domain
const AUDIENCE: &str = "https://api.example.com"; // your API's identifier
// Fetch once at startup and cache; refresh when a kid is unknown.
async fn fetch_jwks() -> JwkSet {
reqwest::get(format!("{ISSUER}/.well-known/jwks")).await.unwrap().json().await.unwrap()
}
fn require_access_token(jwks: &JwkSet, headers: &HeaderMap) -> Result<Value, StatusCode> {
let token = headers.get("authorization")
.and_then(|h| h.to_str().ok())
.and_then(|h| h.strip_prefix("Bearer "))
.ok_or(StatusCode::UNAUTHORIZED)?;
let kid = decode_header(token).map_err(|_| StatusCode::UNAUTHORIZED)?.kid;
let jwk = kid.as_deref().and_then(|k| jwks.find(k)).ok_or(StatusCode::UNAUTHORIZED)?;
// RS256: the signing algorithm configured on your API
let mut validation = Validation::new(Algorithm::RS256);
validation.set_issuer(&[ISSUER]);
validation.set_audience(&[AUDIENCE]);
let data = decode::<Value>(token, &DecodingKey::from_jwk(jwk).unwrap(), &validation)
.map_err(|_| StatusCode::UNAUTHORIZED)?;
Ok(data.claims) // sub, scope, client_id, ...
}No omita nunca la comprobación de la audience: un token acuñado para otra API, o un ID token (cuya audience es el client ID de la aplicación), debe rechazarse aquí. Consulte La API como contrato verificable.
4. Aplicar los scopes
El claim scope del token es una cadena separada por espacios con los scopes que realmente se concedieron al llamante. Un token ausente es un 401; un token válido al que le falta el scope requerido es un 403:
function needScope(scope) {
return (req, res, next) => {
const granted = (req.claims.scope ?? '').split(' ');
if (!granted.includes(scope)) {
return res.status(403).json({ error: 'insufficient_scope', required: scope });
}
return next();
};
}
const app = express();
app.get('/orders', requireAccessToken, needScope('orders.read'), (req, res) => {
res.json({ orders: [], caller: req.claims.sub });
});
app.listen(8080);from fastapi import Depends, FastAPI
def need_scope(scope: str):
def check(claims: dict = Depends(require_access_token)) -> dict:
granted = (claims.get("scope") or "").split(" ")
if scope not in granted:
raise HTTPException(403, {"error": "insufficient_scope", "required": scope})
return claims
return check
app = FastAPI()
@app.get("/orders")
def orders(claims: dict = Depends(need_scope("orders.read"))):
return {"orders": [], "caller": claims["sub"]}
# run with: uvicorn main:app --port 8080@Bean
SecurityFilterChain api(HttpSecurity http) throws Exception {
http.oauth2ResourceServer(rs -> rs.jwt(Customizer.withDefaults()))
.authorizeHttpRequests(auth -> auth
// Spring maps the scope claim to SCOPE_* authorities automatically.
.requestMatchers("/orders").hasAuthority("SCOPE_orders.read")
.anyRequest().authenticated());
return http.build();
}
@RestController
class OrdersController {
@GetMapping("/orders")
Map<String, Object> orders(@AuthenticationPrincipal Jwt jwt) {
return Map.of("orders", List.of(), "caller", jwt.getSubject());
}
}using System.Security.Claims;
builder.Services.AddAuthorization(options =>
{
options.AddPolicy("orders.read", policy => policy.RequireAssertion(ctx =>
(ctx.User.FindFirst("scope")?.Value ?? "").Split(' ').Contains("orders.read")));
});
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapGet("/orders", (ClaimsPrincipal user) =>
Results.Json(new { orders = Array.Empty<object>(), caller = user.FindFirst("sub")?.Value }))
.RequireAuthorization("orders.read");
app.Run("http://localhost:8080");import (
"encoding/json"
"slices"
)
func needScope(w http.ResponseWriter, claims jwt.MapClaims, scope string) bool {
granted, _ := claims["scope"].(string)
if !slices.Contains(strings.Split(granted, " "), scope) {
w.WriteHeader(http.StatusForbidden)
json.NewEncoder(w).Encode(map[string]string{"error": "insufficient_scope", "required": scope})
return false
}
return true
}
func main() {
http.HandleFunc("GET /orders", func(w http.ResponseWriter, r *http.Request) {
claims, ok := requireAccessToken(w, r)
if !ok || !needScope(w, claims, "orders.read") {
return
}
json.NewEncoder(w).Encode(map[string]any{"orders": []any{}, "caller": claims["sub"]})
})
http.ListenAndServe(":8080", nil)
}function needScope(array $claims, string $scope): void {
$granted = explode(' ', $claims['scope'] ?? '');
if (!in_array($scope, $granted, true)) {
http_response_code(403);
header('Content-Type: application/json');
exit(json_encode(['error' => 'insufficient_scope', 'required' => $scope]));
}
}
// e.g. in orders.php
$claims = requireAccessToken();
needScope($claims, 'orders.read');
header('Content-Type: application/json');
echo json_encode(['orders' => [], 'caller' => $claims['sub']]);use axum::{extract::State, routing::get, Json, Router};
use serde_json::json;
fn need_scope(claims: &Value, scope: &str) -> Result<(), StatusCode> {
let granted = claims["scope"].as_str().unwrap_or("");
if granted.split(' ').any(|s| s == scope) { Ok(()) } else { Err(StatusCode::FORBIDDEN) }
}
async fn orders(State(jwks): State<&'static JwkSet>, headers: HeaderMap) -> Result<Json<Value>, StatusCode> {
let claims = require_access_token(jwks, &headers)?;
need_scope(&claims, "orders.read")?;
Ok(Json(json!({ "orders": [], "caller": claims["sub"] })))
}
#[tokio::main]
async fn main() {
let jwks: &'static JwkSet = Box::leak(Box::new(fetch_jwks().await));
let app = Router::new().route("/orders", get(orders)).with_state(jwks);
let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
axum::serve(listener, app).await.unwrap();
}El claim sub del token identifica al llamante: el usuario en los tokens vinculados a un usuario y la aplicación en los tokens machine-to-machine. Un scope en el token es una concesión, no una garantía; aplique igualmente sus propias comprobaciones a nivel de objeto (¿es este llamante el propietario de este registro?).
Si la API tiene RBAC activado, los tokens vinculados a un usuario transportan además los derechos del usuario en un claim permissions (y, opcionalmente, roles), que puede comprobar de la misma manera.
5. Probarlo
Solicite un token para su API y llámela. La pestaña Probar de la API en la Admin Console genera estos comandos ya rellenados; a mano, con una aplicación machine-to-machine:
TOKEN=$(curl -s -X POST https://<your-domain>/oauth/token \
-d grant_type=client_credentials \
-d client_id=$CLIENT_ID -d client_secret=$CLIENT_SECRET \
-d resource=https://api.example.com \
-d scope=orders.read | jq -r .access_token)
curl -s http://localhost:8080/orders -H "Authorization: Bearer $TOKEN"Los tokens obtenidos en nombre de un usuario con sesión iniciada (una aplicación interactiva que pasa el identificador de su API como resource indicator durante el inicio de sesión) se validan exactamente igual.
Solución de problemas
- El token no es un JWT (no tiene tres segmentos separados por puntos). Se solicitó sin el identificador de su API como resource indicator, así que la plataforma emitió un token opaco que solo sirve en el endpoint UserInfo. Solicite el token para su API.
- La validación de la audience falla. El token se acuñó para otra API, o está comparando con el valor equivocado: la audience debe ser exactamente igual al identificador de su API tal como se registró.
- Falta el scope aunque el token sea válido. Los scopes que no se concedieron al llamante se eliminan del token sin ningún aviso; consulte Scopes frente a permisos.
- La verificación solo falla a veces, justo después del inicio de sesión. Compruebe el desfase de reloj entre su servidor y la plataforma; mantenga el reloj de su servidor sincronizado por NTP (las bibliotecas también admiten una pequeña tolerancia de reloj).