Comment puis-je représenter 'Authorization: Bearer <token>' dans une spécification Swagger (swagger.json)


114

J'essaie de transmettre que le schéma d'authentification / sécurité nécessite de définir un en-tête comme suit:

Authorization: Bearer <token>

Voici ce que j'ai basé sur la documentation swagger :

securityDefinitions:
  APIKey:
    type: apiKey
    name: Authorization
    in: header
security:
  - APIKey: []

Réponses:


140

Peut-être que cela peut aider:

swagger: '2.0'
info:
  version: 1.0.0
  title: Based on "Basic Auth Example"
  description: >
    An example for how to use Auth with Swagger.

host: basic-auth-server.herokuapp.com
schemes:
  - http
  - https
securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
paths:
  /:
    get:
      security:
        - Bearer: []
      responses:
        '200':
          description: 'Will send `Authenticated`'
        '403': 
          description: 'You do not have necessary permissions for the resource'

Vous pouvez le copier et le coller ici: http://editor.swagger.io/#/ pour consulter les résultats.

Il existe également plusieurs exemples dans le Web de l'éditeur swagger avec des configurations de sécurité plus complexes qui pourraient vous aider.


4
Je ne vois pas comment vous indiquez à l'éditeur quel utilisateur et mot de passe ou jeton de base envoyer pour que vous puissiez obtenir un 200. Est-ce que je manque quelque chose?
Rob

1
OK, pas grave. Apparemment, vous pouvez cliquer sur "Authentifier" pour obtenir un formulaire de connexion.
Rob

Alors, comment définir une valeur pour le jeton? J'ai essayé curl -x get --header "Authorization: apiKey = 123" mais rien ne s'est passé
Gobliins

2
@Gobliins que vous voulez curl -X GET -H "Authorization: Bearer your_token", où your_tokenest votre jeton porteur. Par exemplecurl -X GET -H "Accept: application/json" -H "Authorization: Bearer 00000000-0000-0000-0000-000000000000" "http://localhost/secure-endpoint"
Steve K

15
Malheureusement, cela ne fonctionne pas bien avec Swagger UI - cliquer sur "Autoriser" et fournir un jeton nu générera des exemples de curl "Essayez-le" avec -H "Authorization: foo"au lieu de -H "Authorization: Bearer foo"comme la réponse OpenAPI 3
Abe Voelker

56

Authentification du support dans OpenAPI 3.0.0

OpenAPI 3.0 prend désormais en charge l'authentification Bearer / JWT de manière native. Il est défini comme ceci:

openapi: 3.0.0
...

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT  # optional, for documentation purposes only

security:
  - bearerAuth: []

Ceci est pris en charge dans Swagger UI 3.4.0+ et Swagger Editor 3.1.12+ (encore une fois, pour les spécifications OpenAPI 3.0 uniquement!).

L'interface utilisateur affichera le bouton «Autoriser», sur lequel vous pouvez cliquer et saisir le jeton porteur (juste le jeton lui-même, sans le préfixe «porteur»). Après cela, les demandes «essayez-le» seront envoyées avec l'en- Authorization: Bearer xxxxxxtête.

Ajout d'en- Authorizationtête par programme (Swagger UI 3.x)

Si vous utilisez l'interface utilisateur Swagger et que, pour une raison quelconque, vous devez ajouter l'en- Authorizationtête par programme au lieu de demander aux utilisateurs de cliquer sur "Autoriser" et de saisir le jeton, vous pouvez utiliser le requestInterceptor. Cette solution est pour Swagger UI 3.x ; UI 2.x a utilisé une technique différente.

// index.html

const ui = SwaggerUIBundle({
  url: "http://your.server.com/swagger.json",
  ...

  requestInterceptor: (req) => {
    req.headers.Authorization = "Bearer xxxxxxx"
    return req
  }
})

1
Comment implémenter cela dans la documentation swagger générée par flask-restplus?
Chang Zhao

Je doute que la réponse corresponde à la question qui a été posée.
Vishrant

16

Pourquoi "Réponse acceptée" fonctionne ... mais ce n'était pas suffisant pour moi

Cela fonctionne dans la spécification. Au moins swagger-tools(version 0.10.1) le valide comme un fichier valide.

Mais si vous utilisez d'autres outils comme swagger-codegen(version 2.1.6), vous rencontrerez des difficultés, même si le client généré contient la définition d'authentification, comme ceci:

this.authentications = {
  'Bearer': {type: 'apiKey', 'in': 'header', name: 'Authorization'}
};

Il n'y a aucun moyen de passer le jeton dans l'en-tête avant que la méthode (point de terminaison) ne soit appelée. Regardez dans cette signature de fonction:

this.rootGet = function(callback) { ... }

Cela signifie que je transmets uniquement le rappel (dans d'autres cas, les paramètres de requête, etc.) sans jeton, ce qui conduit à une construction incorrecte de la demande au serveur.

Mon alternative

Malheureusement, ce n'est pas "joli" mais cela fonctionne jusqu'à ce que j'obtienne le support des jetons JWT sur Swagger.

Remarque: ce qui est discuté dans

Donc, il gère l'authentification comme un en-tête standard. Sur l' pathobjet, ajoutez un paramètre d'en-tête:

swagger: '2.0'
info:
  version: 1.0.0
  title: Based on "Basic Auth Example"
  description: >
    An example for how to use Auth with Swagger.

host: localhost
schemes:
  - http
  - https
paths:
  /:
    get:
      parameters:
        - 
          name: authorization
          in: header
          type: string
          required: true
      responses:
        '200':
          description: 'Will send `Authenticated`'
        '403': 
          description: 'You do not have necessary permissions for the resource'

Cela générera un client avec un nouveau paramètre sur la signature de la méthode:

this.rootGet = function(authorization, callback) {
  // ...
  var headerParams = {
    'authorization': authorization
  };
  // ...
}

Pour utiliser cette méthode de la bonne manière, il suffit de passer la "chaîne complète"

// 'token' and 'cb' comes from elsewhere
var header = 'Bearer ' + token;
sdk.rootGet(header, cb);

Et fonctionne.


"le jeton vient d'ailleurs" ... je m'intéresse à l'ailleurs. Que faire lorsque vous êtes connecté à votre connexion et redirigé vers votre API Swagger, comment pouvez-vous utiliser le jeton d'accès que vous avez reçu?
Nadine

1

Publication de la réponse 2020 dans JSON en utilisant openapi 3.0.0:

{
  "openapi": "3.0.0",
  ...
  "servers": [
    {
      "url": "/"
    }
  ],
  ...
  "paths": {
    "/skills": {
      "put": {
        "security": [
           {
              "bearerAuth": []
           }
        ],
       ...
  },


  "components": {        
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}

0

Ma façon Hackie de résoudre ce problème était de modifier le fichier swagger.go dans le package echo-swagger dans mon cas:

Au bas du fichier, mettez à jour la fonction window.onload pour inclure un requestInterceptor qui formate correctement le jeton.

window.onload = function() {
  // Build a system
  const ui = SwaggerUIBundle({
  url: "{{.URL}}",
  dom_id: '#swagger-ui',
  validatorUrl: null,
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUIBundle.plugins.DownloadUrl
  ,
  layout: "StandaloneLayout",
  requestInterceptor: (req) => {
    req.headers.Authorization = "Bearer " + req.headers.Authorization
  return req
  }
})

window.ui = ui

}

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.