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

```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. 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:

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

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](https://dts-identity.com/pl/docs/integrations/apis.md#the-api-as-a-verifiable-contract).

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

```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();
}
```

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](https://dts-identity.com/pl/docs/integrations/apis.md#role-based-access-control), 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:

```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"
```

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

## Dalsze kroki

- [Tokeny](https://dts-identity.com/pl/docs/reference/tokens.md), aby dowiedzieć się, do czego służy każdy typ tokenu i jak długo żyje.
- [API](https://dts-identity.com/pl/docs/integrations/apis.md), po scope'y, polityki dostępu, czasy życia tokenów i projekt audience dla backendu opartego na mikrousługach.
