# Proteggere un'API

Validare gli access token della piattaforma nella propria API, con esempi per Node.js, Python, Java, C#, Go, PHP e Rust.

Gli altri quickstart trattano il lato client, ossia un'applicazione che ottiene i token. Questa guida tratta il lato **resource server**: la propria API che valida gli access token emessi dalla piattaforma prima di servire una richiesta. Gli esempi coprono Node.js, Python, Java, C#, Go, PHP e Rust; le verifiche sono le stesse in ogni linguaggio e framework.

Gli access token emessi per un'API registrata sono **JWT firmati**, quindi la propria API li valida offline rispetto alle chiavi di firma pubblicate dalla piattaforma; non serve alcuna chiamata alla piattaforma per ogni richiesta.

## 1. Registrare l'API

Nella Admin Console, in **Integrazioni → API**, registrare la propria API con un **identificatore** (per esempio `https://api.example.com`), definirne gli **scope** e autorizzare almeno un'applicazione a chiamarla. Per la procedura completa vedere [API](https://dts-identity.com/it/docs/integrations/apis.md). I client richiedono poi i token *per la propria API* passandone l'identificatore come resource indicator; il claim `aud` del token lo trasporta.

## 2. Installare le dipendenze

```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. Validare il token

Verificare quattro elementi a ogni richiesta, in quest'ordine: la **firma** (rispetto al JWKS della piattaforma), l'**issuer**, l'**audience** (l'identificatore della propria API) e la **scadenza**. Ogni libreria esegue tutte e quattro le verifiche in un'unica chiamata:

```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, ...
}
```

Non tralasciare mai la verifica dell'audience: un token coniato per un'API diversa, oppure un ID token (la cui audience è il client ID dell'applicazione), va rifiutato in questo punto. Vedere [L'API come contratto verificabile](https://dts-identity.com/it/docs/integrations/apis.md#the-api-as-a-verifiable-contract).

## 4. Applicare gli scope

Il claim `scope` del token è una stringa separata da spazi con gli scope effettivamente concessi al chiamante. Un token mancante è un **401**; un token valido privo dello scope richiesto è 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();
}
```

Il claim `sub` del token identifica il chiamante: l'utente per i token che trasportano un utente, l'applicazione per i token machine-to-machine. Uno scope presente nel token è una concessione, non una garanzia: vanno comunque applicati i propri controlli a livello di oggetto (*questo* chiamante è titolare di *questo* record?).

Se per l'API è abilitato l'[RBAC](https://dts-identity.com/it/docs/integrations/apis.md#role-based-access-control), i token che trasportano un utente contengono anche le autorizzazioni dell'utente in un claim `permissions` (e facoltativamente `roles`), verificabile allo stesso modo.

## 5. Provare

Richiedere un token per la propria API e chiamarla. La scheda **Test** dell'API nella Admin Console genera questi comandi già precompilati; a mano, utilizzando un'applicazione 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"
```

I token ottenuti per conto di un utente autenticato (un'applicazione interattiva che passa l'identificatore della propria API come resource indicator durante l'accesso) si validano esattamente allo stesso modo.

## Risoluzione dei problemi

- **Il token non è un JWT** (non ha tre segmenti separati da punti). È stato richiesto senza l'identificatore della propria API come resource indicator, quindi la piattaforma ha emesso un token opaco valido soltanto sull'endpoint UserInfo. Il token va richiesto *per la propria API*.
- **La validazione dell'audience non riesce.** Il token è stato coniato per un'API diversa, oppure il confronto avviene con il valore sbagliato: l'audience deve essere esattamente uguale all'identificatore della propria API così come è registrato.
- **Lo scope manca anche se il token è valido.** Gli scope non concessi al chiamante vengono rimossi silenziosamente dal token; vedere [Scope e autorizzazioni a confronto](https://dts-identity.com/it/docs/integrations/apis.md#scopes-vs-permissions).
- **La verifica fallisce solo a volte, subito dopo l'accesso.** Controllare lo scostamento di orologio tra il proprio server e la piattaforma; mantenere l'orologio del server sincronizzato via NTP (le librerie accettano anche una piccola tolleranza).

## Passi successivi

- [Token](https://dts-identity.com/it/docs/reference/tokens.md) per sapere a che cosa serve ciascun tipo di token e quanto dura.
- [API](https://dts-identity.com/it/docs/integrations/apis.md) per scope, criteri di accesso, durate dei token e progettazione delle audience di un backend a microservizi.
