Zabezpieczanie API
Weryfikuj access tokeny platformy we własnym API, z przykładami dla Node.js, Pythona, Javy, C#, Go, PHP i Rusta.
Pozostałe szybkie starty opisują stronę klienta, czyli aplikację uzyskującą tokeny. Ten przewodnik opisuje stronę serwera zasobów: Twoje własne API, które weryfikuje access tokeny wystawione przez platformę, zanim obsłuży żądanie. Przykłady obejmują Node.js, Pythona, Javę, C#, Go, PHP i Rusta; kontrole są takie same w każdym języku i frameworku.
Access tokeny wystawione dla zarejestrowanego API to podpisane JWT, więc Twoje API weryfikuje je offline względem opublikowanych kluczy podpisywania platformy; przy każdym żądaniu nie jest potrzebne żadne wywołanie platformy.
1. Zarejestruj API
W Admin Console w sekcji Integracje → API zarejestruj swoje API z identyfikatorem (na przykład https://api.example.com), zdefiniuj jego scope'y i autoryzuj co najmniej jedną aplikację do jego wywoływania. Pełny opis znajdziesz na stronie API. Klienci żądają następnie tokenów dla Twojego API, przekazując jego identyfikator jako resource indicator; claim aud tokenu go niesie.
2. Zainstaluj zależności
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. Zweryfikuj token
Przy każdym żądaniu sprawdź cztery rzeczy, w tej kolejności: podpis (względem JWKS platformy), issuera, audience (identyfikator Twojego API) oraz datę wygaśnięcia. Każda z bibliotek robi wszystkie cztery rzeczy w jednym wywołaniu:
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, ...
}Nigdy nie pomijaj sprawdzenia audience: token wystawiony dla innego API albo ID token (którego audience to client ID aplikacji) musi zostać tutaj odrzucony. Zobacz API jako weryfikowalny kontrakt.
4. Egzekwuj scope'y
Claim scope tokenu to ciąg znaków rozdzielony spacjami, zawierający scope'y faktycznie przyznane wywołującemu. Brak tokenu to 401; ważny token bez wymaganego scope'a to 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();
}Claim sub tokenu identyfikuje wywołującego: użytkownika w przypadku tokenów wystawionych w imieniu użytkownika, aplikację w przypadku tokenów machine-to-machine. Scope w tokenie jest przyznaniem uprawnienia, a nie gwarancją; nadal egzekwuj własne kontrole na poziomie obiektów (czy ten wywołujący jest właścicielem tego rekordu?).
Jeśli dla API włączono RBAC, tokeny wystawione w imieniu użytkownika niosą dodatkowo jego uprawnienia w claimie permissions (a opcjonalnie także roles), które możesz sprawdzić w ten sam sposób.
5. Wypróbuj
Poproś o token dla swojego API i wywołaj je. Karta Test danego API w Admin Console generuje te polecenia wstępnie wypełnione; ręcznie, przy użyciu aplikacji 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"Tokeny uzyskane w imieniu zalogowanego użytkownika (przez aplikację interaktywną przekazującą identyfikator Twojego API jako resource indicator podczas logowania) są weryfikowane dokładnie w ten sam sposób.
Rozwiązywanie problemów
- Token nie jest formatem JWT (nie ma trzech segmentów rozdzielonych kropkami). Zażądano go bez identyfikatora Twojego API jako resource indicator, więc platforma wystawiła token nieprzejrzysty, przydatny wyłącznie na punkcie końcowym UserInfo. Poproś o token dla swojego API.
- Weryfikacja audience kończy się niepowodzeniem. Token został wystawiony dla innego API albo porównujesz go z nieprawidłową wartością: audience musi być dokładnie równy identyfikatorowi Twojego API w postaci, w jakiej go zarejestrowano.
- Brakuje scope'a, choć token jest ważny. Scope'y, których wywołującemu nie przyznano, są po cichu pomijane w tokenie; zobacz Scope'y a uprawnienia.
- Weryfikacja zawodzi tylko czasami, tuż po zalogowaniu. Sprawdź rozjazd zegarów między Twoim serwerem a platformą; utrzymuj zegar serwera zsynchronizowany przez NTP (biblioteki akceptują też niewielką tolerancję zegara).