Comment sécuriser vos API avec les schémas de sécurité OpenAPI

Si vous développez ou consommez des API, vous savez probablement à quel point il est important de les protéger contre les accès non autorisés et les utilisations abusives. Les API sont l'épine dorsale de nombreuses applications modernes, et elles doivent être sécurisées avec des mécanismes d'authentification et d'autorisation appropriés.

Mais comment décrire et documenter les exigences de sécurité de vos API ? Comment vous assurez-vous que les consommateurs de votre API savent comment accéder à vos API de manière sécurisée et correcte ? Comment éviter la confusion et l'incohérence entre les différentes API et les schémas de sécurité ?

C'est là que les schémas de sécurité OpenAPI entrent en jeu. OpenAPI est une norme largement utilisée pour décrire et documenter les API dans un format lisible par machine et convivial pour l'homme. Les schémas de sécurité OpenAPI font partie de la spécification OpenAPI qui vous permet de définir et de référencer les mécanismes de sécurité qui protègent vos API.

Dans cet article de blog, nous allons expliquer ce que sont les schémas de sécurité OpenAPI, comment ils fonctionnent et comment vous pouvez les utiliser pour sécuriser vos API. Nous vous montrerons également quelques exemples de schémas de sécurité OpenAPI et comment les utiliser avec Apidog, un outil puissant pour la conception, le test et la documentation des API.

button

Que sont les schémas de sécurité OpenAPI ?

Les schémas de sécurité OpenAPI sont un moyen de décrire les exigences de sécurité de vos API à l'aide de la spécification OpenAPI. Ils sont définis dans la section components/securitySchemes de votre document OpenAPI, et ils peuvent être référencés par le mot-clé security au niveau racine ou au niveau de l'opération de votre API.

Les schémas de sécurité OpenAPI peuvent décrire différents types de mécanismes de sécurité, tels que :

Clés API
Schémas d'authentification HTTP (Basic, Bearer, etc.)
OAuth 2.0
OpenID Connect

Chaque schéma de sécurité a une propriété type qui indique le type de mécanisme de sécurité, et d'autres propriétés qui dépendent du type. Par exemple, un schéma de sécurité de clé API a une propriété name qui spécifie le nom de l'en-tête, du paramètre de requête ou du cookie qui contient la clé API, et une propriété in qui spécifie l'emplacement de la clé API.

Voici un exemple de schéma de sécurité de clé API :

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

Pour appliquer un schéma de sécurité à votre API ou à une opération spécifique, vous devez utiliser le mot-clé security et fournir un tableau d'objets de exigences de sécurité. Un objet de exigences de sécurité est une carte des noms de schémas de sécurité vers un tableau de noms de portée (pour OAuth 2.0 et OpenID Connect) ou un tableau vide (pour d'autres types).

Par exemple, pour appliquer le schéma de sécurité de clé API à l'ensemble de l'API, vous pouvez utiliser la syntaxe suivante :

security:
  - ApiKeyAuth: []

Pour appliquer le schéma de sécurité de clé API à une opération spécifique, vous pouvez utiliser la syntaxe suivante :

paths:
  /pets:
    get:
      security:
        - ApiKeyAuth: []

Vous pouvez également utiliser plusieurs schémas de sécurité pour votre API ou pour une opération spécifique, soit comme alternatives (OU logique) soit comme combinaisons (ET logique). Par exemple, pour exiger une clé API ou un jeton Bearer pour une opération spécifique, vous pouvez utiliser la syntaxe suivante :

paths:
  /pets:
    get:
      security:
        - ApiKeyAuth: []
        - BearerAuth: []

Pour exiger à la fois une clé API et un jeton Bearer pour une opération spécifique, vous pouvez utiliser la syntaxe suivante :

paths:
  /pets:
    get:
      security:
        - ApiKeyAuth: []
          BearerAuth: []

Pourquoi utiliser les schémas de sécurité OpenAPI ?

Les schémas de sécurité OpenAPI présentent plusieurs avantages pour les fournisseurs et les consommateurs d'API, tels que :

Ils fournissent un moyen clair et cohérent de décrire les exigences de sécurité de vos API, ce qui peut aider à éviter la confusion et les erreurs entre les différents consommateurs et développeurs d'API.
Ils permettent la génération d'une documentation interactive et d'exemples de code qui montrent comment accéder à vos API de manière sécurisée et correcte, ce qui peut améliorer l'expérience utilisateur et réduire la courbe d'apprentissage de vos API.
Ils facilitent l'intégration de vos API avec divers outils et plateformes qui prennent en charge la spécification OpenAPI, tels que Apidog, ce qui peut vous aider à concevoir, tester et documenter vos API plus facilement et plus efficacement.

Comment utiliser les schémas de sécurité OpenAPI avec Apidog ?

Apidog est un outil puissant pour la conception, le test et la documentation des API. Il prend en charge la spécification OpenAPI et vous permet de créer et de modifier des documents OpenAPI de manière visuelle et intuitive. Il fournit également des fonctionnalités telles que les tests en direct, les serveurs simulés, la génération de code et la documentation interactive.

button

L'un des avantages de l'utilisation d'Apidog est qu'il peut détecter et appliquer automatiquement les schémas de sécurité que vous définissez dans votre document OpenAPI. Par exemple, si vous définissez un schéma de sécurité de clé API, Apidog vous invitera à saisir votre clé API et à l'envoyer avec vos requêtes. Si vous définissez un schéma de sécurité OAuth 2.0, Apidog vous guidera tout au long du flux d'autorisation et obtiendra et actualisera le jeton d'accès pour vous.

Pour utiliser les schémas de sécurité OpenAPI avec Apidog, vous devez suivre ces étapes :

Créez un nouveau projet ou importez un document OpenAPI existant dans Apidog.
Définissez vos schémas de sécurité dans la section components/securitySchemes de votre document OpenAPI, en utilisant la syntaxe et les propriétés décrites ci-dessus.
Référencez vos schémas de sécurité dans le mot-clé security au niveau racine ou au niveau de l'opération de votre API, en utilisant la syntaxe et les valeurs décrites ci-dessus.
Enregistrez votre document OpenAPI et passez à l'onglet Test dans Apidog.
Sélectionnez une opération qui nécessite une sécurité et cliquez sur le bouton Sécurité dans le panneau de droite.
Saisissez les paramètres de sécurité requis, tels que votre clé API, votre nom d'utilisateur et votre mot de passe, ou votre code d'autorisation, en fonction du type de schéma de sécurité.
Cliquez sur le bouton Envoyer pour envoyer la requête avec les paramètres de sécurité.

Apidog affichera la réponse de votre API et vous montrera les détails de la requête et les paramètres de sécurité. Vous pouvez également afficher et modifier le document OpenAPI brut dans l'onglet Code, et générer une documentation interactive et des exemples de code dans les onglets Docs et Code.

Conclusion

Les schémas de sécurité OpenAPI sont une fonctionnalité utile de la spécification OpenAPI qui vous permet de décrire et de documenter les exigences de sécurité de vos API. Ils peuvent vous aider à communiquer les mécanismes de sécurité qui protègent vos API à vos consommateurs et développeurs d'API, et à permettre la génération d'une documentation interactive et d'exemples de code qui montrent comment accéder à vos API de manière sécurisée et correcte.

Ils peuvent également vous aider à intégrer vos API avec divers outils et plateformes qui prennent en charge la spécification OpenAPI, tels que Apidog, ce qui peut vous aider à concevoir, tester et documenter vos API plus facilement et plus efficacement.

button