Zum Hauptinhalt springen

Wie du Zugangstokens in deinem API-Dienst oder Backend validierst

Die Validierung von Zugangstokens ist ein entscheidender Bestandteil der Durchsetzung der rollenbasierten Zugangskontrolle (RBAC) in Logto. Diese Anleitung führt dich durch die Überprüfung von von Logto ausgestellten JWTs in deinem Backend / API, einschließlich der Prüfung von Signatur, Aussteller (Issuer), Zielgruppe (Audience), Ablauf, Berechtigungen (Scopes) und Organisationskontext.

Bevor du beginnst​

Schritt 1: Konstanten und Hilfsfunktionen initialisieren​

Definiere die notwendigen Konstanten und Hilfsfunktionen in deinem Code, um die Extraktion und Validierung von Tokens zu handhaben. Eine gültige Anfrage muss einen Authorization-Header in der Form Bearer <Zugangstoken (Access token)> enthalten.

auth-middleware.ts
import { IncomingHttpHeaders } from 'http';

const JWKS_URI = 'https://your-tenant.logto.app/oidc/jwks';
const ISSUER = 'https://your-tenant.logto.app/oidc';

export class AuthInfo {
  constructor(
    public sub: string,
    public clientId?: string,
    public organizationId?: string,
    public scopes: string[] = [],
    public audience: string[] = []
  ) {}
}

export class AuthorizationError extends Error {
  name = 'AuthorizationError';
  constructor(
    message: string,
    public status = 403
  ) {
    super(message);
  }
}

export function extractBearerTokenFromHeaders({ authorization }: IncomingHttpHeaders): string {
  const bearerPrefix = 'Bearer ';

  if (!authorization) {
    throw new AuthorizationError('Authorization-Header fehlt', 401);
  }

  if (!authorization.startsWith(bearerPrefix)) {
    throw new AuthorizationError(`Authorization-Header muss mit "${bearerPrefix}" beginnen`, 401);
  }

  return authorization.slice(bearerPrefix.length);
}

Schritt 2: Informationen über deinen Logto-Tenant abrufen​

Du benötigst die folgenden Werte, um von Logto ausgestellte Tokens zu validieren:

  • JSON Web Key Set (JWKS) URI: Die URL zu den öffentlichen Schlüsseln von Logto, die zur Überprüfung von JWT-Signaturen verwendet wird.
  • Aussteller (Issuer): Der erwartete Ausstellerwert (die OIDC-URL von Logto).

Zuerst finde den Endpunkt deines Logto-Tenants. Du findest ihn an verschiedenen Stellen:

  • In der Logto-Konsole unter Einstellungen → Domains.
  • In den Anwendungseinstellungen, die du in Logto konfiguriert hast, unter Einstellungen → Endpoints & Credentials.

Abrufen vom OpenID Connect Discovery-Endpunkt​

Diese Werte können vom OpenID Connect Discovery-Endpunkt von Logto abgerufen werden:

https://<your-logto-endpoint>/oidc/.well-known/openid-configuration

Hier ist ein Beispiel für eine Antwort (andere Felder wurden zur Übersichtlichkeit weggelassen):

{
  "jwks_uri": "https://your-tenant.logto.app/oidc/jwks",
  "issuer": "https://your-tenant.logto.app/oidc"
}

Da Logto keine Anpassung der JWKS-URI oder des Ausstellers (Issuer) erlaubt, kannst du diese Werte fest in deinem Code hinterlegen. Dies wird jedoch für Produktionsanwendungen nicht empfohlen, da dies den Wartungsaufwand erhöhen kann, falls sich zukünftig Konfigurationen ändern.

  • JWKS URI: https://<your-logto-endpoint>/oidc/jwks
  • Aussteller (Issuer): https://<your-logto-endpoint>/oidc

Schritt 3: Das Token und die Berechtigungen validieren​

Nach dem Extrahieren des Tokens und dem Abrufen der OIDC-Konfiguration überprüfe Folgendes:

  • Signatur: JWT muss gültig und von Logto (über JWKS) signiert sein.
  • Aussteller (Issuer): Muss mit dem Aussteller deines Logto-Tenants übereinstimmen.
  • Zielgruppe (Audience): Muss mit dem in Logto registrierten Ressourcenindikator der API oder dem Organisationskontext (falls zutreffend) übereinstimmen.
  • Ablauf (Expiration): Token darf nicht abgelaufen sein.
  • Berechtigungen (Scopes): Token muss die erforderlichen Berechtigungen für deine API / Aktion enthalten. Berechtigungen sind durch Leerzeichen getrennte Zeichenfolgen im scope-Anspruch.
  • Organisationskontext: Wenn du API-Ressourcen auf Organisationsebene schützt, überprüfe den organization_id-Anspruch.

Siehe JSON Web Token, um mehr über die Struktur und Ansprüche von JWT zu erfahren.

Was bei jedem Berechtigungsmodell zu prüfen ist​

  • Audience-Anspruch (aud): API-Ressourcenindikator
  • Organisations-Anspruch (organization_id): Nicht vorhanden
  • Zu prüfende Berechtigungen (scope): API-Ressourcen-Berechtigungen

Für nicht-API-Organisationsberechtigungen wird der Organisationskontext durch den aud-Anspruch dargestellt (z. B. urn:logto:organization:abc123). Der organization_id-Anspruch ist nur für Tokens von API-Ressourcen auf Organisationsebene vorhanden.
tipp:

Validiere immer sowohl Berechtigungen (Scopes) als auch Kontext (Audience, Organisation) für sichere Multi-Tenant-APIs.

Die Validierungslogik hinzufügen​

Wir verwenden jose in diesem Beispiel, um das JWT zu validieren. Installiere es, falls du es noch nicht getan hast:

npm install jose

Oder verwende deinen bevorzugten Paketmanager (z. B. pnpm oder yarn).

Füge zunächst diese gemeinsamen Hilfsfunktionen hinzu, um die JWT-Validierung zu handhaben:

jwt-validator.ts
import { createRemoteJWKSet, jwtVerify, JWTPayload } from 'jose';
import { AuthInfo, AuthorizationError } from './auth-middleware.js';

const jwks = createRemoteJWKSet(new URL(JWKS_URI));

export async function validateJwt(token: string): Promise<JWTPayload> {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: ISSUER,
  });

  verifyPayload(payload);
  return payload;
}

export function createAuthInfo(payload: JWTPayload): AuthInfo {
  const scopes = (payload.scope as string)?.split(' ') ?? [];
  const audience = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];

  return new AuthInfo(
    payload.sub!,
    payload.client_id as string,
    payload.organization_id as string,
    scopes,
    audience
  );
}

function verifyPayload(payload: JWTPayload): void {
  // Implementiere hier deine Verifizierungslogik basierend auf dem Berechtigungsmodell
  // Dies wird im Abschnitt zu den Berechtigungsmodellen unten gezeigt
}

Implementiere dann das Middleware, um das Zugangstoken zu überprüfen:

auth-middleware.ts
import { Request, Response, NextFunction } from 'express';
import { validateJwt, createAuthInfo } from './jwt-validator.js';

// Erweiterung der Express Request-Schnittstelle um auth
declare global {
  namespace Express {
    interface Request {
      auth?: AuthInfo;
    }
  }
}

export async function verifyAccessToken(req: Request, res: Response, next: NextFunction) {
  try {
    const token = extractBearerTokenFromHeaders(req.headers);
    const payload = await validateJwt(token);

    // Auth-Informationen im Request für generische Nutzung speichern
    req.auth = createAuthInfo(payload);

    next();
  } catch (err: any) {
    return res.status(err.status ?? 401).json({ error: err.message });
  }
}

Entsprechend deinem Berechtigungsmodell implementiere die passende Verifizierungslogik in jwt-validator.ts:

jwt-validator.ts
function verifyPayload(payload: JWTPayload): void {
  // Überprüfe, ob der Audience-Anspruch mit deinem API-Ressourcenindikator übereinstimmt
  const audiences = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];
  if (!audiences.includes('https://your-api-resource-indicator')) {
    throw new AuthorizationError('Ungültige Zielgruppe (audience)');
  }

  // Überprüfe erforderliche Berechtigungen für globale API-Ressourcen
  const requiredScopes = ['api:read', 'api:write']; // Ersetze durch deine tatsächlich erforderlichen Berechtigungen
  const scopes = (payload.scope as string)?.split(' ') ?? [];
  if (!requiredScopes.every((scope) => scopes.includes(scope))) {
    throw new AuthorizationError('Unzureichende Berechtigung (scope)');
  }
}

Schritt 4: Middleware auf deine API anwenden​

Wende die Middleware auf deine geschützten API-Routen an.

app.ts
import express from 'express';
import { verifyAccessToken } from './auth-middleware.js';

const app = express();

app.get('/api/protected', verifyAccessToken, (req, res) => {
  // Greife direkt über req.auth auf Authentifizierungsinformationen zu
  res.json({ auth: req.auth });
});

app.get('/api/protected/detailed', verifyAccessToken, (req, res) => {
  // Deine geschützte Endpunkt-Logik
  res.json({
    auth: req.auth,
    message: 'Geschützte Daten erfolgreich abgerufen',
  });
});

app.listen(3000);

Schritt 5: Deine Implementierung testen​

Zugangstokens erhalten​

Von deiner Client-Anwendung: Wenn du eine Client-Integration eingerichtet hast, kann deine App Tokens automatisch erhalten. Extrahiere das Zugangstoken und verwende es in API-Anfragen.

Zum Testen mit curl / Postman:

  1. Benutzertokens: Verwende die Entwicklertools deiner Client-App, um das Zugangstoken aus dem localStorage oder dem Netzwerk-Tab zu kopieren.

  2. Maschine-zu-Maschine-Tokens: Verwende den Client-Credentials-Flow. Hier ein nicht-normatives Beispiel mit curl:

    curl -X POST https://your-tenant.logto.app/oidc/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "client_id=your-m2m-client-id" \
      -d "client_secret=your-m2m-client-secret" \
      -d "resource=https://your-api-resource-indicator" \
      -d "scope=api:read api:write"

    Möglicherweise musst du die Parameter resource und scope entsprechend deiner API-Ressource und Berechtigungen anpassen; ein organization_id-Parameter kann ebenfalls erforderlich sein, wenn deine API organisationsgebunden ist.

tipp:

Möchtest du den Inhalt des Tokens inspizieren? Verwende unseren JWT Decoder, um deine JWTs zu dekodieren und zu überprüfen.

Geschützte Endpunkte testen​

Gültige Token-Anfrage
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:3000/api/protected

Erwartete Antwort:

{
  "auth": {
    "sub": "user123",
    "clientId": "app456",
    "organizationId": "org789",
    "scopes": ["api:read", "api:write"],
    "audience": ["https://your-api-resource-indicator"]
  }
}
Fehlendes Token
curl http://localhost:3000/api/protected

Erwartete Antwort (401):

{
  "error": "Authorization header is missing"
}
Ungültiges Token
curl -H "Authorization: Bearer invalid-token" \
  http://localhost:3000/api/protected

Erwartete Antwort (401):

{
  "error": "Invalid token"
}

Berechtigungsmodell-spezifisches Testen​

Testszenarien für APIs, die mit globalen Berechtigungen geschützt sind:

  • Gültige Berechtigungen: Teste mit Tokens, die deine erforderlichen API-Berechtigungen enthalten (z. B. api:read, api:write)
  • Fehlende Berechtigungen: Erwarte 403 Verboten, wenn das Token die erforderlichen Berechtigungen nicht enthält
  • Falsche Zielgruppe: Erwarte 403 Verboten, wenn die Zielgruppe nicht mit der API-Ressource übereinstimmt
# Token mit fehlenden Berechtigungen - erwarte 403
curl -H "Authorization: Bearer token-without-required-scopes" \
  http://localhost:3000/api/protected
Token-Ansprüche anpassen JSON Web Token (JWT)

OpenID Connect Discovery

 RFC 8707: Ressourcenindikatoren