web-dev-qa-db-fra.com

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

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

Authorization: Bearer <token>

C’est ce que j’ai basé sur le documentation swagger :

securityDefinitions:
  APIKey:
    type: apiKey
    name: Authorization
    in: header
security:
  - APIKey: []
swaggerswagger-2.0swagger-editor
89
Elmer Thomas

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 copier et coller ici: http://editor.swagger.io/#/ pour consulter les résultats.

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

115
David Lopez

Authentification du porteur dans OpenAPI 3.0.0

OpenAPI 3. supporte maintenant l'authentification Bearer/JWT en mode natif. C'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’UI affiche le bouton "Autoriser" sur lequel vous pouvez cliquer et entrer le jeton du porteur (juste le jeton lui-même, sans le préfixe "Au porteur"). Après cela, les requêtes "try it out" seront envoyées avec l'en-tête Authorization: Bearer xxxxxx.

Ajout de l'en-tête Authorization par programme (Swagger UI 3.x)

Si vous utilisez l'interface utilisateur Swagger et que, pour une raison quelconque, vous devez ajouter l'en-tête Authorization par programme au lieu de demander aux utilisateurs de cliquer sur "Autoriser" et de saisir le jeton, vous pouvez utiliser le paramètre requestInterceptor. Cette solution concerne Swagger UI 3.x ; L'interface utilisateur 2.x utilisait 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
  }
})
30
Helen

Pourquoi la "réponse acceptée" fonctionne ... mais cela ne m'a pas suffi

Cela fonctionne dans la spécification. Au moins swagger-tools (version 0.10.1) le valide comme 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 de l'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) soit appelée. Regardez dans cette signature de fonction:

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

Cela signifie que je ne fais que passer le rappel (dans les autres cas, les paramètres de requête, etc.) sans jeton, ce qui entraîne une génération incorrecte de la demande au serveur.

Mon alternative

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

Note: ce qui est discuté dans

Ainsi, il s’agit de l’authentification comme un en-tête standard. Sur l'objet path, 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 correctement, 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.

16
Paulo Oliveira