# 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](https://dts-identity.com/es/docs/integrations/apis.md) 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

```bash tab="Node.js" tab-group="lang"
npm install express jose
```

```bash tab="Python" tab-group="lang"
pip install fastapi uvicorn "pyjwt[crypto]"
```

```groovy tab="Java" tab-group="lang"
// build.gradle
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'
```

```bash tab="C#" tab-group="lang"
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
```

```bash tab="Go" tab-group="lang"
go get github.com/golang-jwt/jwt/v5 github.com/MicahParks/keyfunc/v3
```

```bash tab="PHP" tab-group="lang"
composer require firebase/php-jwt
```

```bash tab="Rust" tab-group="lang"
cargo add axum jsonwebtoken serde_json
cargo add tokio --features full
cargo add reqwest --features json
```

## 3. 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:

```js tab="Node.js" tab-group="lang"
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();
  }
}
```

```python tab="Python" tab-group="lang"
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"'})
```

```yaml tab="Java" tab-group="lang"
# 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 identifier
```

```csharp tab="C#" tab-group="lang"
using 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, ...)
    });
```

```go tab="Go" tab-group="lang"
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, ...
}
```

```php tab="PHP" tab-group="lang"
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;
    }
}
```

```rust tab="Rust" tab-group="lang"
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](https://dts-identity.com/es/docs/integrations/apis.md#the-api-as-a-verifiable-contract).

## 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**:

```js tab="Node.js" tab-group="lang"
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);
```

```python tab="Python" tab-group="lang"
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
```

```java tab="Java" tab-group="lang"
@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());
    }
}
```

```csharp tab="C#" tab-group="lang"
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");
```

```go tab="Go" tab-group="lang"
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)
}
```

```php tab="PHP" tab-group="lang"
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']]);
```

```rust tab="Rust" tab-group="lang"
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](https://dts-identity.com/es/docs/integrations/apis.md#role-based-access-control) 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:

```bash
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](https://dts-identity.com/es/docs/integrations/apis.md#scopes-vs-permissions).
- **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).

## Siguientes pasos

- [Tokens](https://dts-identity.com/es/docs/reference/tokens.md), para saber para qué sirve cada tipo de token y cuánto vive.
- [APIs](https://dts-identity.com/es/docs/integrations/apis.md), para scopes, políticas de acceso, tiempos de vida de los tokens y el diseño de audiences de un backend de microservicios.
