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 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
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 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:
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, ...
}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.
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:
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();
}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 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:
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.
- 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).