Autorisierung von Anfragen in der Try It!-Konsole

Try It! ermöglicht es Entwicklern, ihre Anfragen direkt in der Konsole zu authentifizieren, mit dem Sicherheitsschema, das deine API definiert. Document360 liest die Authentifizierungskonfiguration aus Ihrer OpenAPI-Spezifikation und zeigt die richtigen Felder für jede Methode an, sodass Entwickler Zugangsdaten bereitstellen und eine autorisierte Anfrage senden können, ohne die Dokumentation zu verlassen.

Dieser Artikel erklärt, wie man eine Authentifizierungsmethode in der Konsole auswählt, wie jede unterstützte Methode funktioniert und wie man die OpenAPI-Spezifikation so konfiguriert, dass die Methode in Try It! korrekt erscheint. Für einen allgemeinen Überblick über die Konsole siehe Testing Endpoints mit Try it!.

Wahl einer Authentifizierungsmethode

Wenn ein Endpunkt ein oder mehrere Sicherheitsschemata definiert, zeigt die Try It!-Konsole einen Autorisierungstab an. Oben auf diesem Tab befindet sich ein Authentifizierungsmethoden-Selektor , der alle vom Endpunkt unterstützten Schemata auflistet.

Wählen Sie eine Methode aus, und die Konsole zeigt die Zugangsdaten für dieses Schema an. Wenn ein Endpunkt mehr als eine Methode unterstützt, können Entwickler die auswählen, mit der sie sich authentifizieren möchten.

Document360 unterstützt die folgenden Authentifizierungsmethoden:

Authentifizierungsmethoden werden in Ihrer OpenAPI-Spezifikation components/securitySchemes definiert und auf einzelne Endpunkte mit dem Feld security angewendet.

API-Schlüssel

Die API-Schlüssel-Authentifizierung verwendet einen eindeutigen Schlüssel, der in den Anfrageheadern übergeben wird.

In Ihrer OpenAPI-Spezifikation:

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

Wenden Sie es auf einen Endpunkt an:

/your-endpoint:
  get:
    security:
      - ApiKeyAuth: []

In der Konsole wählen Sie den API-Schlüssel als Authentifizierungsmethode aus. Das Namensfeld ist auf den in Ihrer Spezifikation definierten Header-Namen festgelegt (X-API-Key im obigen Beispiel), und Entwickler geben ihren Schlüssel im Wertfeld ein. Der Schlüssel wird dann zusammen mit der Anfrage in diesen Header gesendet.

Grundlegende Authentifizierung

Die grundlegende Authentifizierung erfordert einen Benutzernamen und ein Passwort, der in der Authorization Kopfzeile jeder Anfrage kodiert und weitergegeben wird.

In Ihrer OpenAPI-Spezifikation:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

Wenden Sie es auf einen Endpunkt an:

/your-endpoint:
  get:
    security:
      - basicAuth: []

Wähle in der Konsole Basis-Authentifizierung aus und gib Benutzername und Passwort ein. Try It! kodiert sie und sendet sie in den Authorization Header, wenn die Anfrage gesendet wird.

Inhabermarker

Die Trägertoken-Authentifizierung verwendet ein Token, das im Header Authorization als übergeben wird Bearer <token>.

In Ihrer OpenAPI-Spezifikation:

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

Wenden Sie es auf einen Endpunkt an:

/your-endpoint:
  get:
    security:
      - BearerAuth: []

In der Konsole wählen Sie den Inhaber-Token aus und geben Sie den Token ein. Try It! sendet es in den Authorization Header als Bearer <token>.

OAuth 2.0

OAuth 2.0 ermöglicht es Entwicklern, über einen Anmeldefluss zu autorisieren, anstatt eine statische Zugangsberechtigung einzugeben. Document360 unterstützt die folgenden Flows – verwenden Sie denjenigen, der mit der Art und Weise übereinstimmt, wie Ihre API Zugriffstoken ausgibt.

Anmeldung

Wenn ein Entwickler OAuth 2.0 in der Konsole auswählt, sieht er die Konfiguration des Schemas und eine Liste der Scopes, gefolgt von einem Autorisieren-Button . Die für das Schema definierten Scopes sind vorgewählt; Entwickler können alle löschen, die sie nicht benötigen, bevor sie autorisieren.

Das Klicken auf Autorisieren startet den Anmeldefluss. Wenn die API PKCE verwendet, ist in der Konsole keine manuelle Konfiguration nötig – Try It! übernimmt den Exchange automatisch, und der Entwickler muss sich nur anmelden. Nach Abschluss der Autorisierung verwendet die Konsole das resultierende Zugriffstoken für Anfragen an diesen Endpunkt.

Beispiel für eine Spezifikationsdefinition (Autorisierungscode-Fluss)

components:
  securitySchemes:
    oauth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.yourdomain.com/oauth/authorize
          tokenUrl: https://auth.yourdomain.com/oauth/token
          scopes:
            read: Read access
            write: Write access

Für das Redirect-URI- und Token-Refresh-Verhalten, das OAuth 2.0 verlangt, siehe Konfiguration Ihres OAuth-Anbieters unten.

OpenID Connect

OpenID Connect erweitert OAuth 2.0 durch die Hinzufügung der Benutzeridentitätsverifikation. Es ist ähnlich wie OAuth 2.0 konfiguriert und hat die gleichen Anforderungen an Redirect-URI und stille Verlängerung.

In Ihrer OpenAPI-Spezifikation:

components:
  securitySchemes:
    openIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://auth.yourdomain.com/.well-known/openid-configuration

Wählen Sie in der Konsole OpenID Connect aus und schließen Sie den Anmeldeprozess ab. Wie bei OAuth 2.0 siehe Konfigurieren Ihres OAuth-Anbieters unten für die erforderlichen Anbieter-Einstellungen.

Konfiguration Ihres OAuth-Anbieters

Sowohl OAuth 2.0 als auch OpenID Connect erfordern zwei Einstellungen, damit die Autorisierung in Try It! korrekt funktioniert.

Redirect URI — Nachdem ein Entwickler den Autorisierungsfluss abgeschlossen hat, leitet der Anbieter ihn zurück zur API-Referenz. Fügen Sie die OAuth-Callback-URL der API-Referenz zur Liste der erlaubten Redirect-URIs Ihres OAuth-Anbieters hinzu:

https://<your-knowledge-base-domain>/assets/apidocs-oauth-callback.html

Ersetzen Sie <your-knowledge-base-domain> sie durch die Domain, auf der Ihre API-Dokumentation veröffentlicht wird.

Stille Verlängerung — Document360 aktualisiert das Zugriffstoken automatisch im Hintergrund, während ein Entwickler Try It! nutzt, sodass die Sitzung während der Nutzung nicht abläuft. Bei dir ist keine Konfiguration erforderlich; Dies wird automatisch gehandhabt.

Anwendung mehrerer Sicherheitsschemata auf einen Endpunkt

Wenn ein Endpunkt gleichzeitig mehr als eine Authentifizierungsmethode benötigt, definieren Sie diese gemeinsam unter security Operationen:

/secure-endpoint:
  get:
    security:
      - BearerAuth: []
        ApiKeyAuth: []

Dafür müssen sowohl ein Bearer-Token als auch ein API-Schlüssel bereitgestellt werden, bevor die Anfrage gesendet werden kann. Try It! unterstützt mehrere Sicherheitsschemata in einer einzigen Sitzung, sodass Entwickler für jede Zugangsdaten bereitstellen und eine autorisierte Anfrage senden können.

Sitzungen und Sicherheit

• Die Qualifikationen sind nur für die Sitzung geeignet. Die von einem Entwickler eingegebenen Zugangsdaten werden nur für die aktive Sitzung gespeichert und nicht gespeichert. Wenn die Sitzung endet, müssen sie erneut eingetragen werden.
• Zugangsdaten sind in der Anfrage-Vorschau verdeckt. Sensitive Werte sind in der Anfrage-Vorschau versteckt, sodass sie beim Erstellen einer Anfrage nicht auf dem Bildschirm sichtbar werden.

FAQ