Autorisation des requêtes dans la console Try It !

Try It ! permet aux développeurs d’authentifier leurs requêtes directement dans la console, en utilisant le schéma de sécurité défini par votre API. Document360 lit la configuration d’authentification de votre spécification OpenAPI et affiche les champs appropriés pour chaque méthode, afin que les développeurs puissent fournir des identifiants et envoyer une requête autorisée sans quitter la documentation.

Cet article explique comment choisir une méthode d’authentification dans la console, comment chaque méthode prise en charge fonctionne, et comment configurer votre spécification OpenAPI pour que la méthode apparaisse correctement dans Essayez-le !. Pour un aperçu général de la console, voir Test des terminaux avec Essayez !.

Choisir une méthode d’authentification

Lorsqu’un point de terminaison définit un ou plusieurs schémas de sécurité, la console Essaie ! affiche un onglet Autorisation . En haut de cet onglet se trouve un sélecteur de méthodes d’authentification listant chaque schéma supporté par le point d’extrémité.

Sélectionnez une méthode, et la console affiche les champs d’identifiants pour ce schéma. Si un point de terminaison supporte plusieurs méthodes, les développeurs peuvent choisir celle qu’ils souhaitent authentifier.

Document360 prend en charge les méthodes d’authentification suivantes :

Les méthodes d’authentification sont définies dans votre spécification OpenAPI sous components/securitySchemes et appliquées à chaque point de terminaison via le security champ.

Clé API

L’authentification par clé API utilise une clé unique passée dans les en-têtes de requête.

Dans votre spécification OpenAPI :

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

Appliquez-le à un point de terminaison :

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

Dans la console, sélectionnez la clé API comme méthode d’authentification. Le champ Nom est fixé au nom de l’en-tête défini dans votre spécification (X-API-Key dans l’exemple ci-dessus), et les développeurs entrent leur clé dans le champ Value . La clé est ensuite envoyée dans cet en-tête avec la requête.

Authentification de base

L’authentification de base nécessite qu’un nom d’utilisateur et un mot de passe soient codés et transmis dans l’en-tête Authorization de chaque requête.

Dans votre spécification OpenAPI :

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

Appliquez-le à un point de terminaison :

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

Dans la console, sélectionnez Authentification de base et entrez le nom d’utilisateur et le mot de passe. Try It ! les encode et les envoie dans l’en-tête Authorization lorsque la requête est envoyée.

Jeton porteur

L’authentification du jeton porteur utilise un jeton passé dans l’en-tête Authorization comme Bearer <token>.

Dans votre spécification OpenAPI :

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

Appliquez-le à un point de terminaison :

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

Dans la console, sélectionnez le jeton porteur et saisissez le jeton. Essayez ! l’envoie dans l’en-tête Authorization comme Bearer <token>.

OAuth 2.0

OAuth 2.0 permet aux développeurs d’autoriser via un flux de connexion plutôt que d’entrer une identifiante statique. Document360 prend en charge les flux suivants — utilisez celui qui correspond à la manière dont votre API émet les jetons d’accès.

Connexion

Lorsqu’un développeur sélectionne OAuth 2.0 dans la console, il voit la configuration du schéma et une liste de portées, suivies d’un bouton Autoriser . Les champs définis pour le schéma sont présélectionnés ; Les développeurs peuvent éliminer ceux dont ils n’ont pas besoin avant d’autoriser.

Cliquer sur Autoriser lance le flux de connexion. Lorsque l’API utilise PKCE, aucune configuration manuelle n’est nécessaire dans la console — Try It ! gère l’échange automatiquement, et le développeur n’a qu’à se connecter. Une fois l’autorisation terminée, la console utilise le jeton d’accès résultant pour les requêtes à ce point d’extrémité.

Exemple de définition de la spécification (Flux de code d’autorisation)

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

Pour le comportement de redirection de l’URI et du rafraîchissement du jeton que requiert OAuth 2.0, voir Configurer votre fournisseur OAuth ci-dessous.

OpenID Connect

OpenID Connect étend OAuth 2.0 en ajoutant la vérification de l’identité utilisateur. Il est configuré de manière similaire à OAuth 2.0 et possède les mêmes exigences d’URI de redirection et de renouvellement silencieux.

Dans votre spécification OpenAPI :

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

Dans la console, sélectionnez OpenID Connect et terminez le flux de connexion. Comme pour OAuth 2.0, voir Configurer votre fournisseur OAuth ci-dessous pour les paramètres de fournisseur requis.

Configuration de votre fournisseur OAuth

OAuth 2.0 et OpenID Connect nécessitent tous deux paramètres pour que l’autorisation fonctionne correctement dans Essay !.

URI de redirection — Après qu’un développeur a terminé le flux d’autorisation, le fournisseur le redirige vers la référence de l’API. Ajoutez l’URL de rappel OAuth de la référence API à la liste des URI de redirection autorisées de votre fournisseur OAuth :

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

Remplacez <your-knowledge-base-domain> par le domaine sur lequel votre documentation API est publiée.

Renouvellement silencieux — Document360 actualise automatiquement le jeton d’accès en arrière-plan pendant qu’un développeur utilise activement Try It !, afin que la session n’expire pas en cours d’utilisation. Aucune configuration n’est requise de votre côté ; Cela est géré automatiquement.

Application de plusieurs schémas de sécurité à un seul point d’accès

Si un point d’accès nécessite plusieurs méthodes d’authentification simultanément, définissez-les ensemble sous security le niveau de l’opération :

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

Cela nécessite à la fois un jeton porteur et une clé API fournis avant que la requête puisse être envoyée. Try It ! prend en charge plusieurs schémas de sécurité en une seule session, permettant aux développeurs de fournir des identifiants pour chacun et d’envoyer une requête autorisée.

Sessions et sécurité

• Les accréditations sont réservées aux sessions. Les identifiants qu’un développeur saisit ne sont conservés que pour la session active et ne sont pas sauvegardés. À la fin de la séance, ils doivent être inscrits à nouveau.
• Les identifiants sont masqués dans l’aperçu des demandes. Les valeurs sensibles sont cachées dans l’aperçu de la requête afin qu’elles ne soient pas exposées à l’écran lors de la création d’une requête.

FAQ