OpenAPI Security Schemes praktisch verstehen

1. Warum Security Schemes in der API-Dokumentation entscheidend sind

OpenAPI-Dokumente ohne korrekte Security-Definitionen sind aus Konsumentensicht unvollständig. Wenn ein Frontend-Entwickler in der Swagger-UI sieht, dass ein Endpoint einen 401-Status zurückgeben kann, aber kein Security Scheme hinterlegt ist, muss er im Quellcode oder in der Projektdokumentation nachschlagen, welche Authentifizierungsmethode der Endpoint erwartet. Das kostet Zeit und führt zu Fehlern bei der Integration.

Die OpenAPI Specification definiert Security Schemes als Teil der components-Sektion und erlaubt es, diese Schemes global für alle Operationen oder individuell pro Endpoint zu referenzieren. Das Ergebnis: Die Swagger-UI zeigt einen "Authorize"-Button, über den Nutzer ihre Credentials eintragen können, und Testtools wie Postman importieren die Authentifizierungskonfiguration direkt aus dem OpenAPI-Dokument. Eine korrekte Security-Scheme-Modellierung macht den Unterschied zwischen einer Dokumentation, die tatsächlich verwendbar ist, und einer, die nur als Referenz existiert.

Besonders relevant wird das Thema, wenn mehrere Authentifizierungsmethoden parallel existieren: eine interne API für Microservices nutzt möglicherweise API-Keys, während die public-facing API OAuth2 verlangt. OpenAPI erlaubt es, beide Schemes zu definieren und sie an unterschiedlichen Endpoints zu referenzieren – ohne redundante Beschreibung und mit klarer Semantik für Tooling und Audits.

2. Die vier Security-Scheme-Typen im Überblick

OpenAPI 3.x definiert vier Security-Scheme-Typen: apiKey, http, oauth2 und openIdConnect. Jeder Typ hat einen anderen Mechanismus, unterschiedliche semantische Bedeutung und unterschiedliche Swagger-UI-Darstellung. Die Wahl des richtigen Typs ist keine Stilfrage – sie bestimmt, wie Tooling mit dem Scheme umgeht, welche Felder pflichtend sind und wie Codegeneratoren den Authentifizierungscode erzeugen.

Ein häufiger Fehler ist der Einsatz von apiKey für Bearer-Token, obwohl der Typ http mit scheme: bearer die semantisch korrekte Wahl wäre. Beide senden einen Wert im Authorization-Header, aber Tooling behandelt sie unterschiedlich: Für http bearer fügen Clients das "Bearer "-Präfix automatisch hinzu, für apiKey nicht. Diese subtilen Unterschiede haben direkte Auswirkungen auf generierte Client-Bibliotheken und Test-Konfigurationen.

# components/securitySchemes — all four types defined
components:
  securitySchemes:

    # Type 1: apiKey — sends value in header, query or cookie
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        Internal service-to-service key. Include the raw key value.
        Do NOT add a "Bearer " prefix — the server expects the key directly.

    # Type 2: http — standard HTTP auth schemes (basic, bearer, digest)
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        JWT issued by the authorization server. Include in the
        Authorization header. The "Bearer " prefix is added automatically
        by conforming clients.

    # Type 3: oauth2 — full OAuth2 flow support
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.mironsoft.de/oauth/authorize
          tokenUrl: https://auth.mironsoft.de/oauth/token
          refreshUrl: https://auth.mironsoft.de/oauth/token
          scopes:
            read:orders: Read order data
            write:orders: Create and update orders
            admin:users: Manage user accounts (requires admin role)

    # Type 4: openIdConnect — discovery document URL
    OpenIDConnect:
      type: openIdConnect
      openIdConnectUrl: https://auth.mironsoft.de/.well-known/openid-configuration

3. apiKey: einfach, aber mit Fallstricken

Der apiKey-Typ ist der einfachste Security-Scheme-Typ und eignet sich für APIs, die einen statischen Schlüssel zur Authentifizierung erwarten – typischerweise interne APIs, Webhook-Empfänger oder Partner-APIs mit begrenztem Scope. Der Schlüssel kann im Request-Header (in: header), im Query-Parameter (in: query) oder in einem Cookie (in: cookie) übertragen werden.

Der häufigste Fallstrick: API-Keys im Query-Parameter erscheinen in Server-Logs, Proxy-Protokollen und Browser-Historien. Das ist ein Sicherheitsrisiko, das in der Dokumentation explizit adressiert werden sollte. OpenAPI bietet keine eigene Möglichkeit, auf Security-Risiken hinzuweisen – das gehört in das description-Feld des Schemes. Wer API-Keys mit Ablaufdatum und Rotation modelliert, sollte das ebenfalls dokumentieren, da OpenAPI nur den Mechanismus, nicht die Lebensdauer beschreibt.

Ein weiterer praktischer Punkt: Wenn eine API zwei parallele apiKey-Schemes kennt – etwa einen Key für Lese- und einen für Schreiboperationen – lassen sich beide in components/securitySchemes definieren und an Endpoints einzeln referenzieren. Das zeigt Konsumenten sofort, welche Endpoints welchen Key erfordern, ohne dass diese Information in der Beschreibung versteckt ist.

4. http Bearer: der Standard für moderne APIs

Der http-Typ mit scheme: bearer ist die korrekte OpenAPI-Modellierung für JWT-basierte Authentifizierung und andere Bearer-Token-Verfahren. Das optionale Feld bearerFormat hat keine funktionale Bedeutung für die Validierung – es ist ein Hinweis für Tooling und Dokumentationsleser. Typische Werte sind JWT, opaque oder SAML.

Ein wichtiges Detail für die Swagger-UI-Integration: Wenn ein Nutzer in der Swagger-UI einen Bearer-Token einträgt, fügt die UI das "Bearer "-Präfix automatisch hinzu. Das bedeutet, dass Nutzer nur den Token selbst eintragen sollten, nicht "Bearer " vorangestellt. Diese Information gehört in das description-Feld des Schemes, weil sie für Tester nicht intuitiv ist und zu häufigen 401-Fehlern beim manuellen Testen führt.

# Bearer Auth with detailed description for Swagger UI users
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        **JWT Bearer Token Authentication**

        Obtain a token via POST /auth/token with your credentials.
        Enter ONLY the token — the "Bearer " prefix is added automatically.

        Token structure (claims):
        - sub: user ID
        - roles: array of role strings
        - exp: expiry as Unix timestamp (default: 3600s)

        Example token endpoint response:
        ```json
        {
          "access_token": "eyJhbGci...",
          "token_type": "Bearer",
          "expires_in": 3600
        }
        ```

paths:
  /orders:
    get:
      summary: List orders
      security:
        - BearerAuth: []      # bearer token required, no scopes for http scheme
      responses:
        '200':
          description: Order list
        '401':
          description: Missing or invalid token
        '403':
          description: Insufficient permissions

  /health:
    get:
      summary: Health check — public endpoint
      security: []            # override: no auth required for this endpoint
      responses:
        '200':
          description: Service is healthy

5. OAuth2 Flows vollständig modellieren

OpenAPI 3.x unterstützt alle vier OAuth2-Flows: authorizationCode, implicit, clientCredentials und password. In der Praxis dominieren heute authorizationCode (mit PKCE für Public Clients) und clientCredentials für Maschine-zu-Maschine-Kommunikation. Der implicit-Flow gilt als deprecated, der password-Flow als unsicher – beide sollten in neuen APIs nicht mehr modelliert werden, außer zur Dokumentation von Legacy-Verhalten.

Die Scope-Modellierung im OAuth2-Scheme ist der wichtigste Unterschied zu anderen Scheme-Typen: Scopes sind benannte Berechtigungen, die der Authorization Server dem Token ausstellt und die die API bei der Autorisierung prüft. OpenAPI erlaubt es, diese Scopes in der Security-Scheme-Definition zu benennen und pro Endpoint zu referenzieren. Das Tooling – Swagger-UI, Postman, generierte Clients – nutzt diese Information, um Nutzer bei der Token-Anfrage mit den richtigen Scopes zu unterstützen.

# OAuth2 with multiple flows for different client types
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        # Browser-based apps and mobile: use authorizationCode + PKCE
        authorizationCode:
          authorizationUrl: https://auth.mironsoft.de/oauth/authorize
          tokenUrl: https://auth.mironsoft.de/oauth/token
          refreshUrl: https://auth.mironsoft.de/oauth/token
          scopes:
            'read:products': View product catalog
            'write:products': Create and update products
            'read:orders': View own orders
            'write:orders': Place and cancel orders
            'admin:orders': Manage all orders (requires admin role)
            'admin:users': Manage user accounts (requires admin role)

        # Server-to-server: no user interaction, uses client credentials
        clientCredentials:
          tokenUrl: https://auth.mironsoft.de/oauth/token
          scopes:
            'service:read': Read-only service access
            'service:write': Read-write service access

paths:
  /products:
    post:
      summary: Create product
      security:
        - OAuth2:
          - write:products    # minimum required scope
      responses:
        '201':
          description: Product created
        '403':
          description: Scope write:products not present in token

  /admin/orders:
    get:
      summary: List all orders (admin)
      security:
        - OAuth2:
          - admin:orders      # admin scope required
        - BearerAuth: []      # OR: internal service with Bearer token
      responses:
        '200':
          description: All orders

6. OpenID Connect: Federation und Discovery

Der openIdConnect-Typ ist der am wenigsten genutzte und gleichzeitig der mächtigste Security-Scheme-Typ in OpenAPI. Er referenziert eine OpenID Connect Discovery URL (/.well-known/openid-configuration), aus der Tooling und Clients alle Endpoint-URLs, unterstützten Flows und Scopes automatisch ableiten können. Das spart Pflegeaufwand: Wenn der Authorization Server seine Endpoints ändert, muss nur das Discovery-Dokument aktualisiert werden – nicht das OpenAPI-Schema.

Ein praktischer Punkt für Swagger-UI: Die UI unterstützt openIdConnect ab Version 4.x und kann aus der Discovery-URL automatisch den Authorization-Endpoint für den authorizationCode-Flow ableiten. Für ältere Swagger-UI-Versionen ist ein paralleles OAuth2-Scheme empfehlenswert, das die Endpoints explizit ausschreibt. Beide Schemes können gleichzeitig in components/securitySchemes definiert sein – eines für Tooling-Kompatibilität, eines für semantische Korrektheit.

7. Scopes granular und konsistent definieren

Scope-Naming ist eine der häufigsten Inkonsistenzquellen in API-Designs. Wenn ein Team read_orders verwendet und ein anderes orders:read, entstehen Konfusionen bei Konsumenten und Probleme bei der Scope-Validierung im Authorization Server. Die Empfehlung: Eine Namenskonvention festlegen und in allen Schemes konsequent durchhalten. Üblich sind resource:action (z. B. orders:read), action:resource (z. B. read:orders) und hierarchische Scopes wie api.orders.read.

Ein wichtiges Konzept: Scopes in OpenAPI beschreiben die minimalen Berechtigungen, die ein Token haben muss, damit ein Endpoint die Anfrage verarbeitet. Sie sind keine Garantie dafür, dass die API keine weiteren Prüfungen durchführt – eine Business-Logic-Prüfung (z. B. "Darf dieser Nutzer diese spezifische Bestellung sehen?") ist keine Scope-Prüfung. Diese Unterscheidung sollte in der API-Dokumentation klar gemacht werden, damit Konsumenten keine falschen Erwartungen an den Scope-Mechanismus haben.

8. Globale vs. endpoint-spezifische Security

OpenAPI erlaubt es, ein Security-Scheme auf Root-Ebene des Dokuments zu definieren – das gilt dann für alle Operationen als Default. Endpoints, die eine andere Konfiguration benötigen (z. B. Public-Endpoints ohne Auth oder Endpoints mit höheren Berechtigungen), überschreiben das globale Security-Objekt mit einem eigenen. Ein leeres Array (security: []) deaktiviert die Authentifizierung explizit für diesen Endpoint.

Dieses Muster ist besonders nützlich für APIs, bei denen die überwiegende Mehrheit der Endpoints dieselbe Authentifizierung erwartet: Das globale Security-Scheme setzt den Default, und nur Ausnahmen werden explizit dokumentiert. Das reduziert Redundanz im YAML und macht deutlich, welche Endpoints bewusst ohne Authentifizierung zugänglich sind – eine Information, die für Security Audits und API-Reviews wichtig ist.

9. Globale und endpoint-spezifische Konfiguration

In der Praxis kombinieren produktive APIs häufig mehrere Security-Scheme-Typen. Eine typische Konfiguration: Globales Bearer-Scheme für alle authentifizierten Endpoints, OAuth2 mit Scopes für Drittanbieter-Zugriff, und ein apiKey-Scheme für Monitoring- und Health-Endpoints, die von internen Tools aufgerufen werden. Diese Kombination lässt sich in OpenAPI sauber modellieren, ohne dass Endpoints doppelt dokumentiert werden müssen.

# Global security + per-endpoint overrides
openapi: 3.1.0
info:
  title: Mironsoft Shop API
  version: 2.0.0

# Global default: all endpoints require Bearer auth
security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.mironsoft.de/oauth/token
          scopes:
            'api:read': Read access
            'api:write': Write access

paths:
  /orders:
    get:
      summary: List orders — uses global Bearer auth
      # No security key needed — inherits global BearerAuth: []
      responses:
        '200':
          description: OK

  /health:
    get:
      summary: Health check — public, no auth
      security: []            # explicitly disable all auth
      responses:
        '200':
          description: OK

  /metrics:
    get:
      summary: Prometheus metrics — internal key only
      security:
        - ApiKeyAuth: []      # override global: internal key instead of Bearer
      responses:
        '200':
          description: Metrics in text/plain

  /integrations/orders:
    get:
      summary: Order feed for partners — OAuth2 or Bearer
      security:
        - OAuth2:
          - api:read          # partner OAuth2 with scope
        - BearerAuth: []      # OR: internal Bearer token
      responses:
        '200':
          description: Order feed

10. Zusammenfassung

OpenAPI Security Schemes sind keine optionale Dokumentationserweiterung – sie sind das Fundament für nutzbare API-Dokumentation, funktionierendes Tooling und effiziente Security Audits. Der richtige Scheme-Typ macht den Unterschied: apiKey für statische Keys, http bearer für JWT, oauth2 wenn Scopes und Flows relevant sind, openIdConnect für Federation-Szenarien. Scopes konsequent und konsistent benennen, globale Security-Defaults setzen und Ausnahmen explizit mit security: [] dokumentieren.

Die Swagger-UI macht Security Schemes sofort nutzbar: Nutzer können Credentials eintragen und Endpoints direkt testen. Postman und andere Tools importieren die Konfiguration automatisch. Codegeneratoren wie openapi-generator erzeugen Authentifizierungscode, der dem Security-Scheme-Typ entspricht. Die Investition in sorgfältige Security-Scheme-Modellierung zahlt sich in weniger Supportaufwand, schnellerer Integration und besserer Auditierbarkeit aus.

11. FAQ: OpenAPI Security Schemes