# Proteger uma API

Valide os access tokens da plataforma na sua própria API, com exemplos para Node.js, Python, Java, C#, Go, PHP e Rust.

Os restantes quickstarts tratam do lado do cliente: uma aplicação que obtém tokens. Este guia trata do lado do **resource server**: a sua própria API a validar os access tokens emitidos pela plataforma antes de servir um pedido. Os exemplos abrangem Node.js, Python, Java, C#, Go, PHP e Rust; as verificações são as mesmas em qualquer linguagem e framework.

Os access tokens emitidos para uma API registada são **JWT assinados**, pelo que a sua API os valida offline face às chaves de assinatura publicadas da plataforma; não é necessária qualquer chamada à plataforma por pedido.

## 1. Registar a API

Na Admin Console, em **Integrações → APIs**, registe a sua API com um **identificador** (por exemplo, `https://api.example.com`), defina os respetivos **scopes** e autorize pelo menos uma aplicação a invocá-la. Consulte [APIs](https://dts-identity.com/pt/docs/integrations/apis.md) para o percurso completo. Os clientes pedem então tokens *para a sua API* passando o identificador desta como resource indicator; o claim `aud` do token transporta-o.

## 2. Instalar as dependências

```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 o token

Verifique quatro coisas em cada pedido, por esta ordem: a **assinatura** (face ao JWKS da plataforma), o **issuer**, a **audience** (o identificador da sua API) e a **expiração**. Cada biblioteca faz as quatro numa única chamada:

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

Nunca dispense a verificação da audience: um token cunhado para outra API, ou um ID token (cuja audience é o client ID da aplicação), tem de ser rejeitado aqui. Consulte [A API como contrato verificável](https://dts-identity.com/pt/docs/integrations/apis.md#the-api-as-a-verifiable-contract).

## 4. Aplicar os scopes

O claim `scope` do token é uma cadeia de caracteres, separada por espaços, com os scopes efetivamente concedidos ao autor da chamada. A ausência de token é um **401**; um token válido a que falte o scope exigido é um **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();
}
```

O claim `sub` do token identifica o autor da chamada: o utilizador, nos tokens ligados a um utilizador, e a aplicação, nos tokens machine-to-machine. Um scope no token é uma concessão, não uma garantia; aplique na mesma as suas próprias verificações ao nível do objeto (é *este* autor da chamada que detém *este* registo?).

Se a API tiver o [RBAC](https://dts-identity.com/pt/docs/integrations/apis.md#role-based-access-control) ativado, os tokens ligados a um utilizador transportam adicionalmente as permissões deste num claim `permissions` (e, opcionalmente, `roles`), que pode verificar da mesma forma.

## 5. Experimentar

Peça um token para a sua API e invoque-a. O separador **Testar** da API na Admin Console gera estes comandos já preenchidos; manualmente, com uma aplicação 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"
```

Os tokens obtidos em nome de um utilizador com sessão iniciada (uma aplicação interativa que passa o identificador da sua API como resource indicator durante o início de sessão) são validados exatamente da mesma forma.

## Resolução de problemas

- **O token não é um JWT** (não tem três segmentos separados por pontos). Foi pedido sem o identificador da sua API como resource indicator, pelo que a plataforma emitiu um token opaco que só serve no endpoint UserInfo. Peça o token *para a sua API*.
- **A validação da audience falha.** O token foi cunhado para outra API, ou está a comparar com o valor errado: a audience tem de ser exatamente igual ao identificador da sua API tal como registado.
- **Falta o scope, apesar de o token ser válido.** Os scopes que não foram concedidos ao autor da chamada são silenciosamente retirados do token; consulte [Scopes versus permissões](https://dts-identity.com/pt/docs/integrations/apis.md#scopes-vs-permissions).
- **A verificação só falha às vezes, logo após o início de sessão.** Verifique se existe desvio de relógio entre o seu servidor e a plataforma; mantenha o relógio do servidor sincronizado por NTP (as bibliotecas aceitam também uma pequena tolerância de relógio).

## Passos seguintes

- [Tokens](https://dts-identity.com/pt/docs/reference/tokens.md): para que serve cada tipo de token e quanto tempo dura.
- [APIs](https://dts-identity.com/pt/docs/integrations/apis.md): scopes, políticas de acesso, tempos de vida dos tokens e o desenho das audiences num backend de microsserviços.
